pg_clickhouse リファレンスドキュメント

はじめに

オープンソースの PostgreSQL 拡張機能である[pg_clickhouse]を使うと、SQL を書き換えることなく、 PostgreSQL から直接 ClickHouse に分析クエリを実行できます。PostgreSQL 13 以降と ClickHouse v23 以降をサポートしています。

ClickPipes による ClickHouse へのデータ同期が開始されたら、 pg_clickhouse を使用して [外部テーブルをインポート] し、それらを PostgreSQL スキーマにすばやく簡単に取り込めます。続いて、それらのテーブルに対して既存の PostgreSQL クエリを実行すれば、既存のコードベースを維持したまま、実行処理を ClickHouse 側にプッシュダウンできます。

はじめに

pg_clickhouse を試す最も簡単な方法は Docker image を使うことです。これには、 pg_clickhouse と re2 拡張機能を含む標準の PostgreSQL 用 Docker image が含まれています。

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 について、スケーリング係数 1 でデータをロードした場合の TPC-H クエリパフォーマンスを比較したものです。✔︎ は単一の foreign scan として完全にプッシュダウンされることを、✼ は複数の foreign scan として完全にプッシュダウンされることを示します。すべてのテストは、メモリ 36 GB を搭載した MacBook Pro M4 Max で実行しました。

クエリ	PostgreSQL	pg_clickhouse	Pushdown
[クエリ 1]	4483 ms	59 ms	✔
[クエリ 2]	588 ms	24 ms	✔
[クエリ 3]	786 ms	62 ms	✔
[クエリ 4]	550 ms	38 ms	✔
[クエリ 5]	721 ms	1439 ms	✔
[クエリ 6]	592 ms	17 ms	✔
[クエリ 7]	639 ms	29 ms	✔
[クエリ 8]	398 ms	383 ms	✔
[クエリ 9]	2842 ms	162 ms	✔
[クエリ 10]	860 ms	125 ms	✔
[クエリ 11]	276 ms	21 ms	✼
[クエリ 12]	963 ms	26 ms	✔
[クエリ 13]	1037 ms	1354 ms
[クエリ 14]	675 ms	30 ms	✔
[クエリ 15]	2520 ms	387 ms
[クエリ 16]	539 ms	823 ms
[クエリ 17]	2107 ms	37 ms	✔
[クエリ 18]	5230 ms	7228 ms
[クエリ 19]	68 ms	47 ms	✔
[クエリ 20]	473 ms	28 ms
[クエリ 21]	1145 ms	4470 ms
[クエリ 22]	270 ms	45 ms	✼

ソースからコンパイル

General Unix

PostgreSQL と curl の開発パッケージでは、pg_config と curl-config が PATH に含まれるため、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 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

ホストで 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 以降で拡張機能をカスタムのプレフィックスにインストールするには、 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 のすべてのデータ型をサポートする
論理削除と UPDATE をサポートする
COPY によるバッチ挿入をサポートする
任意の ClickHouse クエリを実行し、その結果をテーブルとして返す関数を追加する
すべてがリモートデータベースをクエリする場合の UNION クエリのプッシュダウン対応を追加する

著者

著作権