> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-home-button.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> 无需重写任何 SQL，即可直接在 PostgreSQL 中对 ClickHouse 运行分析查询

# pg_clickhouse 参考文档

<div id="introduction">
  ## 简介
</div>

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

一旦 [ClickPipes](/zh/integrations/clickpipes/home) 开始将数据同步到 ClickHouse，
就可以使用 pg\_clickhouse 快速、轻松地将\[foreign tables 导入]到
PostgreSQL schema 中。然后即可针对这些
表运行现有的 PostgreSQL 查询，在保留现有代码库的同时将执行下推到
ClickHouse。

<div id="getting-started">
  ## 快速开始
</div>

体验 pg\_clickhouse 最简单的方法是使用 \[Docker 镜像]。该镜像基于标准的 PostgreSQL Docker 镜像，并包含 pg\_clickhouse 和 [re2]
扩展：

```sh theme={null}
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 表并进行
查询下推。

<div id="test-case-tpc-h">
  ## 测试用例：TPC-H
</div>

此表比较了常规 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 |     |

<div id="compile-from-source">
  ### 从源码编译
</div>

<div id="general-unix">
  #### 通用 Unix
</div>

PostgreSQL 和 curl 的开发包会将 `pg_config` 和
`curl-config` 放在 path 中，因此你应该可以直接运行 `make` (或
`gmake`) ，然后执行 `make install`，接着在你的 database 中执行
`CREATE EXTENSION pg_clickhouse`。

<div id="debian--ubuntu--apt">
  #### Debian / Ubuntu / APT
</div>

有关如何从 PostgreSQL Apt 软件源拉取，请参阅 [PostgreSQL Apt] 了解详细信息。

```sh theme={null}
sudo apt install \
  postgresql-server-18 \
  libcurl4-openssl-dev \
  uuid-dev \
  libssl-dev \
  make \
  cmake \
  g++
```

<div id="redhat--centos--yum">
  #### RedHat / CentOS / Yum
</div>

```sh theme={null}
sudo yum install \
  postgresql-server \
  libcurl-devel \
  libuuid-devel \
  openssl-libs \
  automake \
  cmake \
  gcc
```

有关如何从 PostgreSQL Yum 软件源拉取内容的详细信息，请参阅 [PostgreSQL Yum]。

<div id="install-from-pgxn">
  #### 通过 PGXN 安装
</div>

满足上述依赖项后，使用 [PGXN client] (可通过
[Homebrew]、[Apt] 或名为 `pgxnclient` 的 Yum 软件包安装) 下载、编译
并安装 `pg_clickhouse`：

```sh theme={null}
pgxn install pg_clickhouse
```

<div id="compile-and-install">
  #### 编译并安装
</div>

要编译并安装 ClickHouse 库和 `pg_clickhouse`，请运行：

```sh theme={null}
make
sudo make install
```

如果你的主机上安装了多个 PostgreSQL 版本，你可能需要指定
对应版本的 `pg_config`：

```sh theme={null}
export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config
make
sudo make install
```

如果你的主机上找不到 `curl-config`，可以显式指定其路径：

```sh theme={null}
export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config
make
sudo make install
```

如果遇到以下错误：

```text theme={null}
"Makefile", line 8: Need an operator
```

你需要使用 GNU make；它在你的系统上很可能是以
`gmake` 的名称安装的：

```sh theme={null}
gmake
gmake install
gmake installcheck
```

如果你遇到如下错误：

```text theme={null}
make: pg_config: Command not found
```

请确保已安装 `pg_config`，并且它已在你的 path 中。如果你是通过
RPM 等包管理系统安装 PostgreSQL 的，请确保
`-devel` 包也已安装。如有必要，请告知构建过程应在哪里找到它：

```sh theme={null}
export PG_CONFIG=/path/to/pg_config
make
sudo make install
```

要在 PostgreSQL 18 或更高版本中将该扩展安装到自定义前缀下，请将
`prefix` 参数传递给 `install` (但不要传给其他 `make` 目标) ：

```sh theme={null}
sudo make install prefix=/usr/local/extras
```

然后，确保以下 \[`postgresql.conf`
参数]中包含该前缀：

```ini theme={null}
extension_control_path = '/usr/local/extras/postgresql/share:$system'
dynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'
```

<div id="testing">
  #### 测试
</div>

安装好扩展后，要运行测试套件，请执行

```sh theme={null}
make installcheck
```

如果你遇到如下错误：

```text theme={null}
ERROR:  must be owner of database regression
```

你需要使用超级用户来运行测试套件，例如默认的
"postgres" 超级用户：

```sh theme={null}
make installcheck PGUSER=postgres
```

<div id="loading">
  ### 加载
</div>

安装 `pg_clickhouse` 后，使用超级用户连接到数据库，并运行以下命令即可将其添加到数据库中：

```sql theme={null}
CREATE EXTENSION pg_clickhouse;
```

如果你想将 `pg_clickhouse` 及其所有相关对象安装到
某个特定的 schema 中，可以使用 `SCHEMA` 子句来指定该 schema，例如：

```sql theme={null}
CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;
```

<div id="dependencies">
  ## 依赖项
</div>

`pg_clickhouse` 扩展需要 [PostgreSQL] 13 或更高版本、[libcurl]
以及 [libuuid]。构建该扩展还需要 C 和 C++ 编译器、[libSSL]、[GNU
make] 和 [CMake]。

<div id="road-map">
  ## 路线图
</div>

我们的首要目标是在添加 DML 功能之前，先完成面向分析工作负载的下推覆盖。路线图如下：

* 让其余 10 个尚未下推的 TPC-H 查询获得最优规划
* 测试并修复 ClickBench 查询的下推
* 支持对所有 PostgreSQL 聚合函数进行透明下推
* 支持对所有 PostgreSQL 函数进行透明下推
* 允许通过 CREATE SERVER
  和 GUCs 设置服务器级和会话级 ClickHouse 设置
* 支持所有 ClickHouse 数据类型
* 支持轻量级 DELETE 和 UPDATE
* 支持通过 COPY 进行批次插入
* 添加一个函数，用于执行任意 ClickHouse 查询，并将其
  结果以表的形式返回
* 当 UNION 查询都针对远程数据库时，增加对其下推的支持

<div id="authors">
  ## 作者
</div>

* [David E. Wheeler](https://justatheory.com/)
* [Ildus Kurbangaliev](https://github.com/ildus)
* [Ibrar Ahmed](https://github.com/ibrarahmad)

<div id="copyright">
  ## 版权
</div>

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

[pg_clickhouse]: https://github.com/clickHouse/pg_clickhouse "GitHub 上的 pg_clickhouse"

[import foreign tables]: /integrations/connectors/tools/pg_clickhouse/reference#import-foreign-schema

[Docker image]: https://github.com/ClickHouse/pg_clickhouse/pkgs/container/pg_clickhouse "最新 Docker 发行版"

[tutorial]: /integrations/connectors/tools/pg_clickhouse/tutorial "pg_clickhouse 教程"

[PostgreSQL Apt]: https://wiki.postgresql.org/wiki/Apt

[PostgreSQL Yum]: https://yum.postgresql.org

[PGXN client]: https://pgxn.github.io/pgxnclient/ "PGXN client 文档"

[Homebrew]: https://formulae.brew.sh/formula/pgxnclient#default "Homebrew 上的 PGXN client"

[Apt]: https://tracker.debian.org/pkg/pgxnclient "Debian Apt 上的 PGXN client"

[`postgresql.conf` parameters]: https://www.postgresql.org/docs/devel/runtime-config-client.html#RUNTIME-CONFIG-CLIENT-OTHER

[PostgreSQL]: https://www.postgresql.org "PostgreSQL：世界上最先进的开源关系型数据库"

[libcurl]: https://curl.se/libcurl/ "libcurl — 您的网络传输库"

[libuuid]: https://linux.die.net/man/3/libuuid "libuuid - 与 DCE 兼容的通用唯一标识符库"

[GNU make]: https://www.gnu.org/software/make "GNU Make"

[CMake]: https://cmake.org/ "CMake：功能强大的软件构建系统"

[LibSSL]: https://openssl-library.org "OpenSSL Library"

[TPC-H]: https://www.tpc.org/tpch/

[re2]: https://github.com/ClickHouse/pg_re2 "pg_re2：使用 RE2 的兼容 ClickHouse 的正则表达式函数"

\[查询 1] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/1.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/1.sql)
\[查询 2] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/2.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/2.sql)
\[查询 3] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/3.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/3.sql)
\[查询 4] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/4.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/4.sql)
\[查询 5] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/5.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/5.sql)
\[查询 6] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/6.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/6.sql)
\[查询 7] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/7.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/7.sql)
\[查询 8] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/8.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/8.sql)
\[查询 9] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/9.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/9.sql)
\[查询 10] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/10.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/10.sql)
\[查询 11] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/11.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/11.sql)
\[查询 12] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/12.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/12.sql)
\[查询 13] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/13.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/13.sql)
\[查询 14] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/14.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/14.sql)
\[查询 15] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/15.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/15.sql)
\[查询 16] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/16.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/16.sql)
\[查询 17] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/17.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/17.sql)
\[查询 18] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/18.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/18.sql)
\[查询 19] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/19.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/19.sql)
\[查询 20] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/20.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/20.sql)
\[查询 21] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/21.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/21.sql)
\[查询 22] [https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/22.sql](https://github.com/ClickHouse/pg\&#95;clickhouse/blob/main/dev/tpch/queries/22.sql)