pg_clickhouse 参考文档 | ClickHouse Docs

简介

[pg_clickhouse] 是一个开源 PostgreSQL 扩展，无需重写任何 SQL，即可直接在 PostgreSQL 中对 ClickHouse 运行分析查询。它支持 PostgreSQL 13 及更高版本，以及 ClickHouse v23 及更高版本。

一旦 ClickPipes 开始将数据同步到 ClickHouse，即可使用 pg_clickhouse 快速轻松地将导入外部表导入到 PostgreSQL schema 中。然后，您就可以针对这些表运行现有的 PostgreSQL 查询，在保留现有代码库的同时，将执行下推到 ClickHouse。

快速开始

体验 pg_clickhouse 的最简单方式是使用 Docker image，其中包含标准的 PostgreSQL Docker 镜像，以及 pg_clickhouse 和 re2 扩展：

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 表并下推查询。

测试用例：TPC-H

下表比较了常规 PostgreSQL 表与连接到 ClickHouse 的 pg_clickhouse 在 TPC-H 查询上的性能，两者均加载了扩展因子为 1 的数据；✔︎ 表示以单次外部扫描实现完全下推，✼ 表示以多次外部扫描实现完全下推。所有测试均在配备 36 GB 内存的 MacBook Pro M4 Max 上运行。

查询	PostgreSQL	pg_clickhouse	下推
[Query 1]	4483 ms	59 ms	✔
[Query 2]	588 ms	24 ms	✔
[Query 3]	786 ms	62 ms	✔
[Query 4]	550 ms	38 ms	✔
[Query 5]	721 ms	1439 ms	✔
[Query 6]	592 ms	17 ms	✔
[Query 7]	639 ms	29 ms	✔
[Query 8]	398 ms	383 ms	✔
[Query 9]	2842 ms	162 ms	✔
[Query 10]	860 ms	125 ms	✔
[Query 11]	276 ms	21 ms	✼
[Query 12]	963 ms	26 ms	✔
[Query 13]	1037 ms	1354 ms
[Query 14]	675 ms	30 ms	✔
[Query 15]	2520 ms	387 ms
[Query 16]	539 ms	823 ms
[Query 17]	2107 ms	37 ms	✔
[Query 18]	5230 ms	7228 ms
[Query 19]	68 ms	47 ms	✔
[Query 20]	473 ms	28 ms
[Query 21]	1145 ms	4470 ms
[Query 22]	270 ms	45 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-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 软件包。如有必要，请告诉 build 过程应到哪里查找它：

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 中，可使用 SCHEMA 子句指定该 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 数据类型
支持轻量级 DELETE 和 UPDATE
支持通过 COPY 进行批次插入
添加一个函数来执行任意 ClickHouse 查询，并将其结果以表的形式返回
为所有都查询远程数据库的 UNION 查询添加下推支持

作者

版权