chdb 扩展参考文档

在 Postgres 与各类数据格式、对象存储之间导入和导出数据。

​

简介

该库提供了一组 PostgreSQL 扩展，可在 Postgres 中执行 chDB 查询，并在多种数据格式与对象存储之间复制数据。

​

chdb 扩展

chdb 扩展用于运行 chDB 查询。chdb_query() 函数执行单条查询。例如，以下查询：

SELECT * FROM chdb_query($$
  SELECT * FROM s3('s3://datasets-documentation/my-test-bucket-768/some_prefix/some_file_1.csv')
$$) AS (id int, months int, days int);

输出：

 id | months | days
----+--------+------
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
(3 rows)

详情请参阅 chdb 文档。

​

chdb_hook 模块

chdb_hook 模块挂接到 COPY 命令，可将数据复制到 S3、GCS、Azure Blob、文件或 http URL，也可从这些位置复制数据。以下示例通过单条 COPY 命令从 S3 上的多个 CSV 文件中加载记录：

CREATE TABLE times (
    id     INT NOT NULL,
    months INT NOT NULL,
    days   INT NOT NULL
);

LOAD 'chdb_hook';
COPY times FROM 's3://datasets-documentation/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv';

之后，times 表中就包含了从每个已加载文件中读取的记录：

# SELECT * FROM times;
 id | months | days
----+--------+------
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
(18 rows)

CREATE TABLE 也可以从这样的 URL 推断出列结构，并加载其中的行：

CREATE TABLE reviews () WITH (
    copy_from = 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/amazon_reviews/amazon_reviews_2015.snappy.parquet'
);

详情请参阅 chdb_hook 文档。

​

格式基准测试

有一项benchmark以约 100 万行 NYC Taxi dataset 数据为基础，在多种格式下将 [chdb_hook] 的 COPY 性能与 [aws_s3]、[pg_duckdb] 和 [pg_lake] 进行了对比。

在这四个扩展中，chdb 的性能最为稳定。同样以 DuckDB 为底层的 [pg_duckdb] 和 [pg_lake]，从 CSV、JSON 和 Parquet 导入数据的耗时约为其 2-3 倍。只有 [aws_s3] 的性能接近 [chdb_hook]，但它支持的数据格式要少得多：

Extension	Compression	数据格式
aws_s3	无	Text (TSV), CSV, Postgres Binary
pg_lake	gzip, zstd, snappy (仅 Parquet)	CSV, JSON, Parquet
pg_duckdb	gzip, zstd, snappy (仅 Parquet)	CSV, JSON, Parquet
chdb	gzip, zstd, lz4, bz2, snappy, brotli	TSV、CSV、JSON、BSON、Prometheus、Protobuf、Avro、Parquet、Arrow、XML、CapnProto、Markdown、MsgPack、ORC，以及更多！

进一步的基准测试表明，以多种格式导入 NYC Taxi dataset 时，性能相对稳定：

为与其他扩展保持可比性，该基准测试采用了 JSONCompact 格式；其他 JSON 数据格式 (例如 JSONCompactEachRow) 的性能会更接近上述其他格式。

​

架构

chdb 和 chdb_hook 扩展依赖 chdb_helper 进程来执行 chDB 查询。该辅助进程将 chDB 的资源占用与 Postgres 主进程隔离开来，对于从数据湖加载数据这类偶尔才会用到的工作流而言，这是一大优势。

                  +-------------+
                  |   helper    |
+----------+      |    app      |      +------+
| Postgres |      | +---------+ |      | chDB |
| Backend  |----->| |  chDB   | |----->| Data |
+----------+      | | Library | |      +------+
                  | +---------+ |
                  +-------------+

与 background worker 不同，该辅助进程不持有 Postgres 共享内存，postmaster 也不对其进行管理。因此崩溃被隔离开来，不会影响 Postgres。辅助进程一旦终止，只会在启动它的 backend 中引发一个错误，其他 session 则完全不受影响。

​

依赖项

chdb 扩展 需要 PostgreSQL 15 或更高版本，以及 v26.7.0 或更高版本的 chDB library (目前仅支持 Linux 和 macOS) 。最简单的安装方式是使用 lib.chdb.io shell 脚本：

curl -sL https://lib.chdb.io | bash

若要将 chDB 静态编译进辅助应用，请在运行 安装 make 命令之前设置以下变量。

export BUNDLE_LIBCHDB=1 LIBCHDB_BUILD=static

Makefile 会下载静态 libchdb 库，并将其编译进应用中。

在 Linux 上，也可以在执行安装所需的 make 命令前设置 export BUNDLE_LIBCHDB=1，让安装过程改为下载并安装动态 libchdb 库。

​

从源码编译

要构建 chdb，只需执行以下操作：

make
make installcheck
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 过程指定它的所在位置：

env PG_CONFIG=/path/to/pg_config make && make installcheck && make install

如果遇到类似如下的错误：

chdb_helper.c:22:10: fatal error: 'chdb.h' file not found

你需要安装 chDB，或者告知编译器在何处查找它。例如，如果你是通过 lib.chdb.io 的 shell 脚本安装的，则将其指向 /usr/local：

make CFLAGS=-I/usr/local/include \
     LDFLAGS=-L/usr/local/lib

如果你遇到如下错误：

ERROR:  must be owner of database regression

你需要使用 super user 运行 test suite，例如默认的 “postgres” super user：

make installcheck PGUSER=postgres

若要在 PostgreSQL 18 或更高版本上将该 扩展 安装到 custom prefix 中，请向 install 传递 prefix argument (但不要传给其他 make 目标) ：

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'

​

作者

• David E. Wheeler
• serprex

​

版权

Copyright (c) 2026, ClickHouse