pg_clickhouse 참고 문서

소개

오픈소스 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:18
docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'

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

테스트 케이스: TPC-H

이 표는 일반 PostgreSQL 테이블과 ClickHouse에 연결된 pg_clickhouse의 TPC-H 쿼리 성능을 비교한 것으로, 둘 다 스케일 팩터 1로 로드되었습니다. ✔︎는 완전한 푸시다운을 의미하며, 대시는 1분 후 쿼리가 취소되었음을 의미합니다. 모든 테스트는 36 GB 메모리를 탑재한 MacBook Pro M4 Max에서 실행되었습니다.

쿼리	PostgreSQL	pg_clickhouse	푸시다운
[Query 1]	4693 ms	268 ms	✔︎
[Query 2]	458 ms	3446 ms
[Query 3]	742 ms	111 ms	✔︎
[Query 4]	270 ms	130 ms	✔︎
[Query 5]	337 ms	1460 ms	✔︎
[Query 6]	764 ms	53 ms	✔︎
[Query 7]	619 ms	96 ms	✔︎
[Query 8]	342 ms	156 ms	✔︎
[Query 9]	3094 ms	298 ms	✔︎
[Query 10]	581 ms	197 ms	✔︎
[Query 11]	212 ms	24 ms
[Query 12]	1116 ms	84 ms	✔︎
[Query 13]	958 ms	1368 ms
[Query 14]	181 ms	73 ms	✔︎
[Query 15]	1118 ms	557 ms
[Query 16]	497 ms	1714 ms
[Query 17]	1846 ms	32709 ms
[Query 18]	5823 ms	10649 ms
[Query 19]	53 ms	206 ms	✔︎
[Query 20]	421 ms	-
[Query 21]	1349 ms	4434 ms
[Query 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-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 클라이언트](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 이상에서 확장 기능을 사용자 지정 경로에 설치하려면 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 및 GUC를 통해 서버 수준 및 세션 수준 ClickHouse 설정 허용
모든 ClickHouse 데이터 타입 지원
경량한 DELETE 및 UPDATE 지원
COPY를 통한 일괄 삽입 지원
임의의 ClickHouse 쿼리를 실행하고 그 결과를 테이블로 반환하는 함수 추가
모두 원격 데이터베이스를 쿼리하는 경우 UNION 쿼리에 대한 푸시다운 지원 추가

저자

저작권

소개​

시작하기​

테스트 케이스: TPC-H​

소스 코드로 빌드하기​

일반 Unix​

Debian / Ubuntu / APT​

RedHat / CentOS / Yum​

PGXN에서 설치​

컴파일 및 설치​

테스트​

로드​

종속 항목​

로드맵​

저자​

저작권​

소개