pg_clickhouse 参考文档 - ClickHouse Documentation

简介

[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:18
docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'

请参阅[教程]，了解如何开始导入 ClickHouse 表并下推查询。

测试用例：TPC-H

下表比较了常规 PostgreSQL 表与连接到 ClickHouse 的 pg_clickhouse 在 TPC-H 查询上的性能表现，二者均使用扩缩容因子 1 加载；✔︎ 表示完全下推，短横线表示查询在 1 分钟后被取消。所有测试均在配备 36 GB 内存的 MacBook Pro M4 Max 上运行。

Query	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 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

如果你的主机上的 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，并且它已在你的 path 中。如果你使用了 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 查询添加下推支持

作者

版权

​简介

​快速开始

​测试用例：TPC-H

​从源码编译

​通用 Unix

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​从 PGXN 安装

​编译并安装

​测试

​加载

​依赖项

​路线图

​作者

​版权

简介