pg_lake

概览

pkg 3.5.9; SQL 3.5; PG16-18; OpenSSL 3/no EL8; preload pg_extension_base; run matching pgduck_server; DuckDB hook/COPY order matters.

版本

构建

您可以使用 pig build 命令构建 pg_lake 扩展的 RPM / DEB 包：

pig build pkg pg_lake         # 构建 RPM / DEB 包

安装

您可以直接安装 pg_lake 扩展包的预置二进制包，首先确保 PGDG 和 PIGSTY 仓库已经添加并启用：

pig repo add pgsql -u          # 添加仓库并更新缓存

使用 pig 或者是 apt/yum/dnf 安装扩展：

pig install pg_lake;          # 当前活跃 PG 版本安装

pig ext install -y pg_lake -v 18  # PG 18
pig ext install -y pg_lake -v 17  # PG 17
pig ext install -y pg_lake -v 16  # PG 16

dnf install -y pg_lake_18       # PG 18
dnf install -y pg_lake_17       # PG 17
dnf install -y pg_lake_16       # PG 16

apt install -y postgresql-18-pg-lake   # PG 18
apt install -y postgresql-17-pg-lake   # PG 17
apt install -y postgresql-16-pg-lake   # PG 16

预加载配置：

shared_preload_libraries = 'pg_extension_base';

创建扩展：

CREATE EXTENSION pg_lake CASCADE;  -- 依赖: pg_lake_copy, pg_lake_table

用法

来源：

• 官方 pg_lake README
• 版本 3.5 控制文件
• 官方构建和启动指南
• 官方项目文档索引
• pg_lake v3.5.3 发布说明
• DuckDB Secret 管理器
• 上游 v3.5.10 发布说明

pg_lake 是 Snowflake PostgreSQL 湖仓套件的顶层扩展。它会安装查询对象存储文件和创建事务型 Iceberg 表所需的表访问、Iceberg、COPY、查询引擎、扩展基础设施和映射组件。PostgreSQL 扩展负责查询规划与事务协调，独立的本地 pgduck_server 进程则使用 DuckDB 执行向量化计算。

下述打包流程对应 3.5.3，本次核对的最新上游发布为 3.5.10，SQL 扩展版本仍为 3.5。动态库与查询服务器应使用同一发布版本。

启动打包版服务栈

版本 3.5 支持 PostgreSQL 16 至 18。PIGSTY 的 RPM 与 DEB 包会安装扩展文件和带版本路径的 pgduck_server 二进制，但目前不会安装或自动启动 systemd 服务；执行 CREATE EXTENSION 也不会拉起 pgduck_server。

将 pg_extension_base 加入 shared_preload_libraries，然后重启 PostgreSQL：

shared_preload_libraries = 'pg_extension_base'

pgduck_server 默认监听 /tmp/.s.PGSQL.5332，socket 权限为 0770。应使用 PostgreSQL 的操作系统用户启动它，确保 PostgreSQL 可以访问该 socket；不要直接使用无关的登录用户运行裸命令。

# Debian/Ubuntu with PostgreSQL 18; use 16 or 17 as appropriate.
PG_LAKE_SERVER=/usr/lib/postgresql/18/bin/pgduck_server
# RHEL-compatible systems use /usr/pgsql-18/bin/pgduck_server.

sudo install -d -o postgres -g postgres -m 0700 \
  /var/lib/pg_lake /var/lib/pg_lake/extensions
sudo install -d -o postgres -g postgres -m 0750 /var/cache/pg_lake
sudo -u postgres -H "$PG_LAKE_SERVER" \
  --duckdb_database_file_path /var/lib/pg_lake/pgduck_server.db \
  --extensions_dir /var/lib/pg_lake/extensions \
  --cache_dir /var/cache/pg_lake

该命令会以前台方式持续运行，不能退出；生产环境应交由服务管理器监管。如果使用独立服务账号，应将其加入 postgres 用户组，并使用 --unix_socket_group postgres --unix_socket_permissions 0770 启动服务。

在另一个终端中先验证查询引擎，再创建扩展：

sudo -u postgres psql -X \
  "host=/tmp port=5332 dbname=postgres connect_timeout=2" \
  -c 'SELECT version();'

然后在目标数据库中创建完整的依赖树：

CREATE EXTENSION pg_lake CASCADE;
SELECT lake.version();

配置对象存储访问

对象存储凭据由 pgduck_server 解析，而不是由 PostgreSQL 后端解析。AWS 与 GCP 可以使用各自的标准凭据链。对于 MinIO 等本地 S3 兼容服务，先创建存储桶，再直接连接 pgduck_server 创建持久化的 DuckDB Secret：

sudo -u postgres psql -X -h /tmp -p 5332 -d postgres

CREATE PERSISTENT SECRET pglake_object_store (
    TYPE S3,
    KEY_ID 'access-key',
    SECRET 'secret-key',
    REGION 'us-east-1',
    ENDPOINT 'minio.example.com:9000',
    SCOPE 's3://analytics-bucket',
    URL_STYLE 'path',
    USE_SSL false
);

连接 PostgreSQL，并在创建表的同一会话中指定托管 Iceberg 数据的位置：

SET pg_lake_iceberg.default_location_prefix =
    's3://analytics-bucket/warehouse';

核心工作流

创建和修改事务型 Iceberg 表：

CREATE TABLE measurements (
    station_name text NOT NULL,
    measured_at timestamptz NOT NULL,
    value double precision
) USING iceberg;

INSERT INTO measurements VALUES
    ('Istanbul', now(), 18.5),
    ('Haarlem', now(), 9.3);

通过 COPY 导入或导出 Parquet、CSV 或换行符分隔的 JSON 文件：

COPY (SELECT * FROM measurements)
TO 's3://analytics-bucket/export/measurements.parquet';

COPY measurements
FROM 's3://analytics-bucket/import/measurements.parquet';

直接查询文件，无需先将其载入 PostgreSQL：

CREATE FOREIGN TABLE external_events ()
SERVER pg_lake
OPTIONS (path 's3://analytics-bucket/events/*.parquet');

SELECT count(*) FROM external_events;

组件索引

• pg_lake：元扩展，并提供 lake.version()。
• pg_lake_table：数据湖 FDW、Iceberg 表语法、文件工具和表目录。
• pg_lake_iceberg：Iceberg 元数据、快照、清单和目录集成。
• pg_lake_copy：拦截针对对象存储文件和湖格式的 COPY。
• pg_lake_engine：共享查询重写、类型转换、清理以及 pgduck_server 客户端层。
• pg_extension_base：预加载和生命周期工作进程基础设施。
• pg_map：为嵌套湖数据生成 PostgreSQL 映射类型。

运营注意事项

• 每台可能执行湖查询的 PostgreSQL 主机都必须运行 pgduck_server。应使用服务管理器监管进程，并在承载流量前验证本地 socket。
• 默认 socket 权限为 0770，其属主和属组取决于启动 pgduck_server 的账号。服务用户不匹配时会出现 ERROR: could not start query engine。
• S3 及兼容存储的凭据由 DuckDB Secret/凭据链解析。仅授予工作负载所需的存储桶权限。
• 首次启动可能下载 DuckDB Spatial 扩展。请确保服务账号具备必要的网络权限，并能写入状态目录和缓存目录。
• CREATE PERSISTENT SECRET 创建的凭据可跨服务重启保留，但 DuckDB 会将其以未加密形式存放在 ~/.duckdb/stored_secrets。应保持服务账号及其主目录不变，限制文件权限，并按凭据进行保护。
• 默认内存上限为系统内存的 80%。当 PostgreSQL 与 pgduck_server 共用生产主机时，应显式设置 --memory_limit。
• Iceberg 写入会按语句创建 Parquet 文件。应批量插入并定期运行 VACUUM，避免产生大量小文件。
• PostgreSQL 扩展、pgduck_server、对象存储数据和 Iceberg 目录共同构成一个部署单元。单独创建扩展并不能证明外部服务可用；备份和升级时也应分别核验这些组件。

升级服务栈

部署同一 3.5.3 发布的扩展文件与 pgduck_server，然后重启已经加载旧动态库的进程。在每个数据库执行迁移，并检查各组件版本：

ALTER EXTENSION pg_lake UPDATE TO '3.5';
SELECT extname, extversion
FROM pg_extension
WHERE extname LIKE 'pg_lake%'
   OR extname IN ('pg_extension_base', 'pg_extension_updater', 'pg_map')
ORDER BY extname;

3.5.3 补丁加强了对象删除时的凭据选择，并避免发布无表名的目录条目。它仍使用 SQL 版本 3.5，因此仅凭 SQL 版本不能证明补丁级二进制已部署到位。

上游 3.5.10 变化

3.5.10 加强了对目录返回的凭据端点与文件路径的限制，固定后台工作进程的搜索路径，并增加 Iceberg 元数据校验。它支持目录下发的 Azure SAS 令牌，以及通过 pg_lake_iceberg.horizon_tls_ca_path 设置自定义 Horizon TLS CA 路径。查询服务器也将无效嵌套值和过大结果处理为错误，避免崩溃。这些属于上游变化；文档所述的 3.5.3 软件包并不能证明这些修复已安装。升级时应部署互相匹配的扩展动态库和查询服务器二进制。

3.5.10 变化

上游 3.5.10 在目录停止下发凭据后清理缓存的临时凭据，保留对象存储中的 Iceberg 目录 URL，并将 Brotli 更新到 1.1.1 以修复 CVE-2026-111497。部署时应匹配扩展动态库和 pgduck_server，SQL 版本仍为 3.5。