pg_clickhouse 참고 문서 - ClickHouse Documentation

소개

오픈 소스 PostgreSQL 확장 기능인 [pg_clickhouse]를 사용하면 SQL을 전혀 다시 작성하지 않고도 PostgreSQL에서 바로 ClickHouse에 분석 쿼리를 실행할 수 있습니다. PostgreSQL 13 이상과 ClickHouse v23 이상을 지원합니다. ClickPipes가 데이터를 ClickHouse로 동기화하기 시작하면, pg_clickhouse를 사용해 [외부 테이블 가져오기]를 PostgreSQL 스키마로 빠르고 쉽게 가져올 수 있습니다. 그런 다음 해당 테이블에 대해 기존 PostgreSQL 쿼리를 실행하면 기존 코드베이스를 유지하면서도 실행은 ClickHouse로 푸시할 수 있습니다.

시작하기

pg_clickhouse를 가장 간단하게 사용해 보려면 [Docker 이미지]를 이용하면 됩니다. 여기에는 pg_clickhouse 및 re2 확장 기능이 포함된 표준 PostgreSQL Docker 이미지가 포함되어 있습니다:

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

ClickHouse 테이블을 가져오고 쿼리 푸시다운을 시작하려면 tutorial을 참조하십시오.

테스트 케이스: TPC-H

이 표는 일반 PostgreSQL 테이블과 ClickHouse에 연결된 pg_clickhouse의 TPC-H 쿼리 성능을 비교합니다. 두 환경 모두 스케일 팩터 1로 적재했으며, ✔︎는 전체 푸시다운을, 대시는 1분 후 쿼리가 취소되었음을 나타냅니다. 모든 테스트는 36 GB 메모리를 탑재한 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 개발 패키지에는 pg_config와 curl-config가 경로에 포함되어 있으므로 make(또는 gmake)를 실행한 다음 make install을 실행하고, 데이터베이스에서 CREATE EXTENSION pg_clickhouse를 실행하면 됩니다.

Debian / Ubuntu / APT

PostgreSQL Apt 리포지토리에서 가져오는 방법에 대한 자세한 내용은 PostgreSQL Apt를 참조하십시오.

sudo apt install \
  postgresql-server-19 \
  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 클라이언트](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

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

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가 설치되어 있고 경로에 포함되어 있는지 확인하십시오. PostgreSQL을 설치할 때 RPM과 같은 패키지 관리 시스템을 사용했다면 -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;

종속성

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

로드맵

현재 최우선 과제는 DML 기능을 추가하기 전에 분석 워크로드에 대한 푸시다운 적용 범위를 마무리하는 것입니다. 로드맵은 다음과 같습니다:

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

저자

저작권

​소개

​시작하기

​테스트 케이스: TPC-H

​소스 코드로 빌드하기

​일반적인 Unix

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​PGXN에서 설치

​컴파일 및 설치

​테스트

​로드

​종속성

​로드맵

​저자

​저작권

소개