pg_ducklake
基于 DuckDB 与 Parquet 的 DuckLake 湖仓一体扩展
仓库
relytcloud/pg_ducklake
https://github.com/relytcloud/pg_ducklake
源码
pg_ducklake-1.0.0.tar.gz
pg_ducklake-1.0.0.tar.gz
概览
| 扩展包名 | 版本 | 分类 | 许可证 | 语言 |
|---|---|---|---|---|
pg_ducklake | 1.0.0 | OLAP | MIT | C++ |
| ID | 扩展名 | Bin | Lib | Load | Create | Trust | Reloc | 模式 |
|---|---|---|---|---|---|---|---|---|
| 2490 | pg_ducklake | 否 | 是 | 是 | 是 | 否 | 否 | ducklake |
| 相关扩展 | pg_lake pg_duckdb pg_mooncake pg_parquet duckdb_fdw aws_s3 file_fdw pg_bulkload columnar pg_clickhouse |
|---|
版本
| 类型 | 仓库 | 版本 | PG 大版本 | 包名 | 依赖 |
|---|---|---|---|---|---|
| EXT | PIGSTY | 1.0.0 | 1817161514 | pg_ducklake | - |
| RPM | PIGSTY | 1.0.0 | 1817161514 | pg_ducklake_$v | - |
| DEB | PIGSTY | 1.0.0 | 1817161514 | postgresql-$v-pg-ducklake | - |
构建
您可以使用 pig build 命令构建 pg_ducklake 扩展的 RPM / DEB 包：
pig build pkg pg_ducklake # 构建 RPM / DEB 包
安装
您可以直接安装 pg_ducklake 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：
pig repo add pgsql -u # 添加仓库并更新缓存
使用 pig 或者是 apt/yum/dnf 安装扩展：
pig install pg_ducklake; # 当前活跃 PG 版本安装
pig ext install -y pg_ducklake -v 18 # PG 18
pig ext install -y pg_ducklake -v 17 # PG 17
pig ext install -y pg_ducklake -v 16 # PG 16
pig ext install -y pg_ducklake -v 15 # PG 15
pig ext install -y pg_ducklake -v 14 # PG 14
dnf install -y pg_ducklake_18 # PG 18
dnf install -y pg_ducklake_17 # PG 17
dnf install -y pg_ducklake_16 # PG 16
dnf install -y pg_ducklake_15 # PG 15
dnf install -y pg_ducklake_14 # PG 14
apt install -y postgresql-18-pg-ducklake # PG 18
apt install -y postgresql-17-pg-ducklake # PG 17
apt install -y postgresql-16-pg-ducklake # PG 16
apt install -y postgresql-15-pg-ducklake # PG 15
apt install -y postgresql-14-pg-ducklake # PG 14
预加载配置：
shared_preload_libraries = 'pg_ducklake';
创建扩展：
CREATE EXTENSION pg_ducklake;
用法
pg_ducklake 为 PostgreSQL 增加 DuckLake 表。DuckLake 元数据存储在 PostgreSQL 中，表数据以 Parquet 格式存储并通过 DuckDB 查询，让 PostgreSQL SQL 客户端可以使用快照、时间旅行查询、分区、排序键和外部对象存储等湖仓功能。
创建 DuckLake 表
CREATE EXTENSION pg_ducklake;
CREATE TABLE events (
id int,
kind text,
ts timestamptz
) USING ducklake;
INSERT INTO events VALUES
(1, 'login', now()),
(2, 'click', now());
SELECT * FROM events ORDER BY id;
当数据需要放在默认路径之外时，应显式设置表路径：
CREATE TABLE lake_events (
id int,
payload jsonb
) WITH (
ducklake.table_path = 's3://my-bucket/prefix/'
) USING ducklake;
时间旅行查询
每次提交都会创建快照。在修改前记录快照 ID，然后查询旧状态：
SELECT max(snapshot_id) AS before_delete
FROM ducklake.ducklake_snapshot \gset
DELETE FROM events WHERE id = 1;
SELECT * FROM ducklake.time_travel('events'::regclass, :before_delete);
转换与加载数据
可以从已有的 PostgreSQL 堆表或外部数据读取器创建 DuckLake 表：
CREATE TABLE row_store AS
SELECT i AS id, 'hello pg_ducklake' AS msg
FROM generate_series(1, 10000) AS i;
CREATE TABLE col_store USING ducklake AS
SELECT * FROM row_store;
CREATE TABLE titanic USING ducklake AS
SELECT * FROM ducklake.read_csv('https://raw.githubusercontent.com/datasciencedojo/datasets/master/titanic.csv');
内联、分区与维护
小批量写入默认内联到元数据中，避免产生大量小 Parquet 文件。可以调整行数限制或显式刷出数据：
CALL ducklake.set_option('data_inlining_row_limit', 100);
SELECT * FROM ducklake.flush_inlined_data('events'::regclass);
为表设置分区键和排序键，以便执行裁剪和分析：
CALL ducklake.set_partition('events'::regclass, 'bucket(4, id)', 'month(ts)');
CREATE INDEX ON events USING ducklake_sorted (id, ts);
当自动后台维护不足时，可以按需执行维护：
SELECT * FROM ducklake.merge_adjacent_files('events'::regclass);
CALL ducklake.set_option('expire_older_than', '7 days');
SELECT * FROM ducklake.expire_snapshots();
SELECT * FROM ducklake.cleanup_old_files();
外部 DuckDB 访问
DuckDB 客户端可以挂载同一份 DuckLake 元数据：
INSTALL ducklake;
LOAD ducklake;
ATTACH 'ducklake:postgres:dbname=postgres host=localhost' AS my_ducklake
(METADATA_SCHEMA 'ducklake');
SELECT * FROM my_ducklake.public.events;
注意事项
- 版本 1.0.0 支持 PostgreSQL 14-18。
- README 列出的源码构建目标包括 Ubuntu 22.04-24.04 和 macOS。
- 云凭据通过
ducklake_secret外部服务器和逐用户映射存储；应像保护其他数据库密钥一样保护这些目录对象。 - 对于从堆表到 DuckLake 的增量转换，上游指向单独的
pg_duckpipe项目。