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

はじめに

オープンソースの PostgreSQL 拡張機能である[pg_clickhouse]を使うと、SQL を書き換えることなく、 PostgreSQL から直接 ClickHouse に分析クエリを実行できます。PostgreSQL 14 以降と 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 14 以降、libcurl、 libuuid が必要です。拡張機能をビルドするには、C および C++ コンパイラ、libSSL、GNU make、CMake が必要です。

ロードマップ

現在最も注力しているのは、DML 機能を追加する前に、分析ワークロード向けのプッシュダウン対応を完成させることです。ロードマップは次のとおりです。

残る 10 件の未対応の TPC-H クエリについて、最適な実行計画を実現する
ClickBench クエリに対するプッシュダウンをテストし、修正する
PostgreSQL のすべての集約関数の透過的なプッシュダウンをサポートする
PostgreSQL のすべての関数の透過的なプッシュダウンをサポートする
CREATE SERVER および GUCs を通じて、サーバーレベルおよびセッションレベルの ClickHouse 設定を許可する
ClickHouse のすべてのデータ型をサポートする
論理削除と UPDATE をサポートする
COPY によるバッチ挿入をサポートする
任意の ClickHouse クエリを実行し、その結果をテーブルとして返す関数を追加する
すべてがリモートデータベースをクエリする場合の UNION クエリのプッシュダウン対応を追加する

著者

著作権

はじめる

機能

ガイド

料金

ClickHouse 連携

移行

監視

よくある質問

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

はじめに

はじめに

テストケース: TPC-H

ソースからコンパイル

General Unix

Debian / Ubuntu / APT

RedHat / CentOS / Yum

PGXN からインストール

コンパイルとインストール

テスト

読み込み

依存関係

ロードマップ

著者

著作権

​はじめに

​はじめに

​テストケース: TPC-H

​ソースからコンパイル

​General Unix

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​PGXN からインストール

​コンパイルとインストール

​テスト

​読み込み

​依存関係

​ロードマップ

​著者

​著作権

はじめに

はじめに

テストケース: TPC-H

ソースからコンパイル

General Unix

Debian / Ubuntu / APT

RedHat / CentOS / Yum

PGXN からインストール

コンパイルとインストール

テスト

読み込み

依存関係

ロードマップ

著者

著作権