pg_clickhouse

はじめに

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

ClickPipes が ClickHouse へのデータの同期を開始したら、 pg_clickhouse を使って PostgreSQL スキーマに import foreign tables を迅速かつ簡単にインポートします。既存の 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 分経過後にクエリがキャンセルされたことを示します。すべてのテストは、メモリ 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 が PATH に含まれているため、そのまま 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

ホスト上で 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 がインストールされており、PATH で参照できることを確認してください。RPM などのパッケージ管理システムを使用して PostgreSQL をインストールした場合は、-devel パッケージもインストールされていることを確認してください。必要に応じて、ビルドプロセスに対してその場所を指定してください。

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

PostgreSQL 18 以降でカスタムプレフィックス配下に拡張機能をインストールするには、（他のどの make ターゲットも指定せずに）install に prefix 引数を渡してください。

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 データ型をサポートする
論理削除 (lightweight DELETE) と UPDATE をサポートする
COPY 経由でのバッチ挿入をサポートする
任意の ClickHouse クエリを実行し、その結果をテーブルとして返す関数を追加する
すべてがリモートデータベースを参照している場合に、UNION クエリのプッシュダウンをサポートする

著者

著作権

はじめに​

はじめに​

テストケース: TPC-H​

ソースコードからコンパイル​

一般的な Unix​

Debian / Ubuntu / APT​

RedHat / CentOS / Yum​

PGXN からインストール​

コンパイルおよびインストール​

テスト​

読み込み​

依存関係​

今後のロードマップ​

著者​

著作権​

はじめに

はじめに

テストケース: TPC-H

ソースコードからコンパイル

一般的な Unix

Debian / Ubuntu / APT

RedHat / CentOS / Yum

PGXN からインストール

コンパイルおよびインストール

テスト

読み込み

依存関係

今後のロードマップ

著者

著作権