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:18
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	푸시다운
[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가 설치되어 있고 경로에 포함되어 있는지 확인하세요. 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;

의존성

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

로드맵

가장 우선순위가 높은 과제는 DML 기능을 추가하기에 앞서 분석 워크로드에 대한 푸시다운 커버리지를 완성하는 것입니다. 로드맵은 다음과 같습니다.

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

저자

저작권

​소개

​시작하기

​테스트 케이스: TPC-H

​소스에서 컴파일하기

​일반 Unix

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​PGXN에서 설치

​컴파일 및 설치

​테스트

​불러오기

​의존성

​로드맵

​저자

​저작권

소개