pg_clickhouse

소개

pg_clickhouse는 오픈 소스 PostgreSQL 확장 프로그램으로, SQL을 다시 작성할 필요 없이 PostgreSQL에서 바로 ClickHouse로 분석 쿼리를 실행할 수 있습니다. PostgreSQL 13 이상과 ClickHouse v23 이상을 지원합니다.

ClickPipes가 ClickHouse로 데이터를 동기화하기 시작하면, pg_clickhouse를 사용하여 [외부 테이블 가져오기]를 통해 PostgreSQL 스키마로 외부 테이블을 빠르고 쉽게 가져올 수 있습니다. 그런 다음 기존 PostgreSQL 쿼리를 그대로 해당 테이블에 실행해, 실행은 ClickHouse로 위임하면서도 기존 코드베이스는 그대로 유지합니다.

시작하기

pg_clickhouse를 가장 간단하게 사용해 보는 방법은 Docker image를 사용하는 것입니다. 이 이미지에는 표준 PostgreSQL Docker image와 pg_clickhouse 확장이 포함되어 있습니다.

docker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \
       -d ghcr.io/clickhouse/pg_clickhouse:18
docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'

ClickHouse 테이블 가져오기와 쿼리 푸시다운을 시작하려면 [튜토리얼]을 참조하십시오.

테스트 케이스: TPC-H

이 표는 스케일링 팩터 1로 적재된 일반 PostgreSQL 테이블과 ClickHouse에 연결된 pg_clickhouse 간의 TPC-H 쿼리 성능을 비교합니다. ✔︎는 완전한 푸시다운을 나타내고, 대시(-)는 1분 후 쿼리가 취소되었음을 나타냅니다. 모든 테스트는 36GB 메모리를 장착한 MacBook Pro M4 Max에서 실행되었습니다.

쿼리	PostgreSQL	pg_clickhouse	푸시다운
[쿼리 1]	4693 ms	268 ms	✔︎
[쿼리 2]	458 ms	3446 ms
[쿼리 3]	742 ms	111 ms	✔︎
[쿼리 4]	270 ms	130 ms	✔︎
[쿼리 5]	337 ms	1460 ms	✔︎
[쿼리 6]	764 ms	53 ms	✔︎
[쿼리 7]	619 ms	96 ms	✔︎
[쿼리 8]	342 ms	156 ms	✔︎
[쿼리 9]	3094 ms	298 ms	✔︎
[쿼리 10]	581 ms	197 ms	✔︎
[쿼리 11]	212 ms	24 ms	✔︎
[쿼리 12]	1116 ms	84 ms	✔︎
[쿼리 13]	958 ms	1368 ms
[쿼리 14]	181 ms	73 ms	✔︎
[쿼리 15]	1118 ms	557 ms
[쿼리 16]	497 ms	1714 ms
[쿼리 17]	1846 ms	32709 ms
[쿼리 18]	5823 ms	10649 ms
[쿼리 19]	53 ms	206 ms	✔︎
[쿼리 20]	421 ms	-
[쿼리 21]	1349 ms	4434 ms
[쿼리 22]	258 ms	1415 ms

소스 코드에서 컴파일하기

일반 Unix

PostgreSQL 및 curl 개발 패키지에는 PATH에 pg_config와 curl-config가 포함되어 있으므로 make(또는 gmake)를 실행한 다음 make install을 실행하고, 데이터베이스에서 CREATE EXTENSION pg_clickhouse를 실행하면 됩니다.

Debian / Ubuntu / APT

PostgreSQL Apt 리포지토리에서 패키지를 가져오는 방법에 대해서는 PostgreSQL Apt를 참조하십시오.

sudo apt install \
  postgresql-server-18 \
  libcurl4-openssl-dev \
  uuid-dev \
  libssl-dev \
  make \
  cmake \
  g++

RedHat / CentOS / Yum

sudo yum install \
  postgresql-server \
  libcurl-devel \
  libuuid-devel \
  openssl-libs \
  automake \
  cmake \
  gcc

PostgreSQL Yum 저장소에서 패키지를 가져오는 방법에 대한 자세한 내용은 PostgreSQL Yum을 참고하십시오.

PGXN에서 설치

위에서 언급한 의존성이 충족되면 PGXN client(Homebrew, Apt, pgxnclient라는 이름의 Yum 패키지로 제공됨)을 사용하여 pg_clickhouse를 다운로드, 컴파일 및 설치합니다.

pgxn install pg_clickhouse

컴파일 및 설치

ClickHouse 라이브러리와 pg_clickhouse를 빌드하고 설치하려면 다음 명령을 실행하십시오:

make
sudo make install

호스트에 PostgreSQL 인스턴스가 여러 개 설치되어 있는 경우, 적절한 버전의 pg_config를 지정해야 할 수 있습니다:

export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config
make
sudo make install

호스트 시스템의 PATH에 curl-config가 없으면, 경로를 명시적으로 지정할 수 있습니다:

export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config
make
sudo make install

다음과 같은 오류가 발생하면:

"Makefile", line 8: Need an operator

GNU make를 사용해야 하며, 시스템에는 gmake라는 이름으로 설치되어 있을 수 있습니다:

gmake
gmake install
gmake installcheck

다음과 같은 오류가 발생하면:

make: pg_config: Command not found

pg_config가 설치되어 있고 PATH에 포함되어 있는지 확인하십시오. RPM과 같은 패키지 관리 시스템을 사용하여 PostgreSQL을 설치했다면, -devel 패키지도 설치되어 있는지 확인하십시오. 필요하다면 빌드 과정에 해당 파일의 위치를 지정하십시오:

export PG_CONFIG=/path/to/pg_config
make
sudo make install

PostgreSQL 18 이상에서 사용자 지정 prefix 경로에 확장을 설치하려면, install에 prefix 인수를 전달하십시오 (make의 다른 타깃은 사용하지 마십시오).

sudo make install prefix=/usr/local/extras

그런 다음 아래 [postgresql.conf 매개변수]에 해당 접두사가 포함되어 있는지 확인합니다:

extension_control_path = '/usr/local/extras/postgresql/share:$system'
dynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'

테스트

확장을 설치한 후 테스트 스위트를 실행하려면 다음을 실행하십시오.

make installcheck

다음과 같은 오류가 발생하면:

ERROR:  must be owner of database regression

기본 슈퍼유저인 「postgres」와 같은 슈퍼유저로 테스트 스위트를 실행해야 합니다.

make installcheck PGUSER=postgres

로딩

pg_clickhouse가 설치된 후 슈퍼유저 권한으로 접속하여 다음 명령을 실행하면 데이터베이스에 추가할 수 있습니다:

CREATE EXTENSION pg_clickhouse;

pg_clickhouse와 이를 지원하는 모든 오브젝트를 특정 스키마에 설치하려면 SCHEMA 절을 사용하여 다음과 같이 스키마를 지정하십시오:`

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

Dependencies

pg_clickhouse 확장은 PostgreSQL 13 이상과 libcurl, libuuid가 필요합니다. 확장을 빌드하려면 C 및 C++ 컴파일러와 libSSL, GNU make, CMake가 필요합니다.

로드맵

가장 중요한 목표는 DML 기능을 추가하기 전에 분석 워크로드에 대한 푸시다운 적용 범위를 완료하는 것입니다. 로드맵은 다음과 같습니다:

푸시다운되지 않은 나머지 10개의 TPC-H 쿼리에 대해 최적의 실행 계획 구현
ClickBench 쿼리에 대한 푸시다운을 테스트하고 수정
모든 PostgreSQL 집계 함수의 투명한 푸시다운 지원
모든 PostgreSQL 함수의 투명한 푸시다운 지원
서버 수준 및 세션 수준에서 ClickHouse 설정을 CREATE SERVER 및 GUC를 통해 구성 가능하도록 지원
모든 ClickHouse 데이터 타입 지원
경량한 삭제(lightweight DELETE) 및 UPDATE 지원
COPY를 통한 배치 삽입 지원
임의의 ClickHouse 쿼리를 실행하고 그 결과를 테이블로 반환하는 함수 추가
모든 하위 쿼리가 원격 데이터베이스를 조회하는 경우 UNION 쿼리의 푸시다운 지원 추가

저자

저작권

소개​

시작하기​

테스트 케이스: TPC-H​

소스 코드에서 컴파일하기​

일반 Unix​

Debian / Ubuntu / APT​

RedHat / CentOS / Yum​

PGXN에서 설치​

컴파일 및 설치​

테스트​

로딩​

Dependencies​

로드맵​

저자​

저작권​

소개

시작하기

테스트 케이스: TPC-H

소스 코드에서 컴파일하기

일반 Unix

Debian / Ubuntu / APT

RedHat / CentOS / Yum

PGXN에서 설치

컴파일 및 설치

테스트

로딩

Dependencies

로드맵

저자

저작권