pg_clickhouse 参考文档 - ClickHouse Documentation

简介

[pg_clickhouse] 是一个开源 PostgreSQL 扩展，可让你直接在 PostgreSQL 中对 ClickHouse 运行分析查询，而无需重写任何 SQL。它支持 PostgreSQL 13 及更高版本，以及 ClickHouse v23 及更高版本。一旦 ClickPipes 开始将数据同步到 ClickHouse，就可以使用 pg_clickhouse 快速、轻松地将[foreign tables 导入]到 PostgreSQL schema 中。然后即可针对这些表运行现有的 PostgreSQL 查询，在保留现有代码库的同时将执行下推到 ClickHouse。

快速开始

体验 pg_clickhouse 最简单的方法是使用 [Docker 镜像]。该镜像基于标准的 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 上运行。

查询	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，接着在你的 database 中执行 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，可以显式指定其路径：

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 或更高版本中将该扩展安装到自定义前缀下，请将 prefix 参数传递给 install (但不要传给其他 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 查询都针对远程数据库时，增加对其下推的支持

作者

版权

部分版权归 Ildus Kurbangaliev 所有 (c) 2023-2025
部分版权归 Adjust GmbH 所有 (c) 2019-2023
部分版权归 PostgreSQL Global Development Group 所有 (c) 2012-2019

​简介

​快速开始

​测试用例：TPC-H

​从源码编译

​通用 Unix

​Debian / Ubuntu / APT

​RedHat / CentOS / Yum

​通过 PGXN 安装

​编译并安装

​测试

​加载

​依赖项

​路线图

​作者

​版权

简介