跳到主要内容
跳到主要内容

pg_clickhouse

介绍​

pg_clickhouse 是一个开源的 PostgreSQL 扩展，可以直接从 PostgreSQL 在 ClickHouse 上运行分析查询，而无需重写任何 SQL。它支持 PostgreSQL 13 及以上版本，以及 ClickHouse v23 及以上版本。

一旦 ClickPipes 开始将数据同步到 ClickHouse 后，即可使用 pg_clickhouse 快速、轻松地将 [外部表导入] 到 PostgreSQL 的某个模式（schema）中。然后即可在这些表上运行现有的 PostgreSQL 查询，在将执行下推到 ClickHouse 的同时，保留你现有的代码库。

入门​

试用 pg_clickhouse 最简单的方法是使用 Docker image，它 基于标准 PostgreSQL Docker 镜像，并已包含 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'

请参阅 tutorial，开始导入 ClickHouse 表并启用查询下推。

测试用例：TPC-H​

下表比较了在规模因子 1 数据集上，TPC-H 查询在常规 PostgreSQL 表与通过 pg_clickhouse 连接到 ClickHouse 时的性能；✅ 表示查询完全下推， 而短横线表示查询在 1 分钟后被取消。所有测试均在配备 36 GB 内存的 MacBook Pro M4 Max 上运行。

QueryPushdownpg_clickhousePostgreSQL
[Query 1]✅73ms4478ms
[Query 2]-560ms
[Query 3]✅74ms1454ms
[Query 4]✅67ms650ms
[Query 5]✅104ms452ms
[Query 6]✅42ms740ms
[Query 7]✅83ms633ms
[Query 8]✅114ms320ms
[Query 9]✅136ms3028ms
[Query 10]✅10ms6ms
[Query 11]✅78ms213ms
[Query 12]✅37ms1101ms
[Query 13]1242ms967ms
[Query 14]✅51ms193ms
[Query 15]522ms1095ms
[Query 16]1797ms492ms
[Query 17]9ms1802ms
[Query 18]10ms6185ms
[Query 19]532ms64ms
[Query 20]4595ms473ms
[Query 21]1702ms1334ms
[Query 22]268ms257ms

从源代码编译​

通用 Unix​

PostgreSQL 和 curl 的开发包会将 pg_config 和 curl-config 安装到 PATH 中，因此你只需运行 make（或 gmake），然后运行 make install，接着在数据库中执行 CREATE EXTENSION http 即可。

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 和 Yum 获取，软件包名为 pgxnclient）下载、编译 并安装 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 或更高版本上将该扩展安装到自定义前缀目录中，请在执行 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。

Road Map​

我们当前的首要任务是在添加 DML 功能之前，先完成对分析型工作负载的下推覆盖率。我们的路线图：

  • 让剩余的 10 个尚未下推的 TPC-H 查询都能够获得最优执行计划
  • 测试并修复 ClickBench 查询的下推
  • 支持对所有 PostgreSQL 聚合函数的透明下推
  • 支持对所有 PostgreSQL 函数的透明下推
  • 允许通过 CREATE SERVER 和 GUC 在服务器级和会话级配置 ClickHouse 设置
  • 支持所有 ClickHouse 数据类型
  • 支持轻量级 DELETE 和 UPDATE
  • 通过 COPY 支持批量插入
  • 添加一个函数，用于执行任意 ClickHouse 查询并将其结果作为表返回
  • 在所有子查询都访问远程数据库时，添加对 UNION 查询下推的支持

作者​

  • Copyright (c) 2025，ClickHouse
  • 部分版权 (c) 2023-2025，Ildus Kurbangaliev
  • 部分版权 (c) 2019-2023，Adjust GmbH
  • 部分版权 (c) 2012-2019，PostgreSQL Global Development Group