跳转到主要内容

​
简介

[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 上运行。
查询PostgreSQLpg_clickhouse下推
[查询 1]4693 ms268 ms✔︎
[查询 2]458 ms3446 ms
[查询 3]742 ms111 ms✔︎
[查询 4]270 ms130 ms✔︎
[查询 5]337 ms1460 ms✔︎
[查询 6]764 ms53 ms✔︎
[查询 7]619 ms96 ms✔︎
[查询 8]342 ms156 ms✔︎
[查询 9]3094 ms298 ms✔︎
[查询 10]581 ms197 ms✔︎
[查询 11]212 ms24 ms
[查询 12]1116 ms84 ms✔︎
[查询 13]958 ms1368 ms
[查询 14]181 ms73 ms✔︎
[查询 15]1118 ms557 ms
[查询 16]497 ms1714 ms
[查询 17]1846 ms32709 ms
[查询 18]5823 ms10649 ms
[查询 19]53 ms206 ms✔︎
[查询 20]421 ms-
[查询 21]1349 ms4434 ms
[查询 22]258 ms1415 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 查询都针对远程数据库时，增加对其下推的支持

​
作者

  • Copyright (c) 2025-2026, ClickHouse
  • 部分版权归 Ildus Kurbangaliev 所有 (c) 2023-2025
  • 部分版权归 Adjust GmbH 所有 (c) 2019-2023
  • 部分版权归 PostgreSQL Global Development Group 所有 (c) 2012-2019
[查询 1] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/1.sql [查询 2] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/2.sql [查询 3] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/3.sql [查询 4] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/4.sql [查询 5] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/5.sql [查询 6] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/6.sql [查询 7] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/7.sql [查询 8] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/8.sql [查询 9] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/9.sql [查询 10] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/10.sql [查询 11] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/11.sql [查询 12] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/12.sql [查询 13] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/13.sql [查询 14] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/14.sql [查询 15] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/15.sql [查询 16] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/16.sql [查询 17] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/17.sql [查询 18] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/18.sql [查询 19] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/19.sql [查询 20] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/20.sql [查询 21] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/21.sql [查询 22] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/22.sql
最后修改于 2026年6月10日