pg_lake_iceberg

概览

The control file declares pg_lake_engine; canonical metadata also retains plpgsql because the install SQL uses PL/pgSQL. plpgsql is installed by default in normal PostgreSQL databases. Extension SQL/control version is 3.4; source and DEB/RPM package version is 3.4.0.

版本

构建

您可以使用 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
• dnf
• apt

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

创建扩展：

CREATE EXTENSION pg_lake_iceberg CASCADE;  -- 依赖: pg_lake_engine, plpgsql

用法

来源：

• 官方Iceberg表指南
• 版本3.4控制文件
• Iceberg元数据SQL API
• 版本3.4目录FDW SQL

pg_lake_iceberg 在PostgreSQL内部实现了Iceberg的元数据、快照、清单、分区规范和目录集成。依赖组件 CREATE TABLE ... USING iceberg 暴露了熟悉的 pg_lake_table 语法；用户通常通过 pg_lake 安装这两个组件。

创建并检查一个Iceberg表

CREATE EXTENSION pg_lake CASCADE;

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

CREATE TABLE events (
    event_time timestamptz NOT NULL,
    user_id bigint NOT NULL,
    payload jsonb
) USING iceberg
WITH (partition_by = 'day(event_time), bucket(32, user_id)');

SELECT table_namespace, table_name, metadata_location
FROM iceberg_tables
WHERE table_name = 'events';

检查Iceberg元数据文件及其引用的状态：

SELECT lake_iceberg.metadata(metadata_location)
FROM iceberg_tables
WHERE table_name = 'events';

SELECT f.*
FROM iceberg_tables AS t
CROSS JOIN LATERAL lake_iceberg.files(t.metadata_location) AS f
WHERE t.table_name = 'events';

元数据和目录API

• iceberg_tables: pg_catalog 视图，结合本地管理表和外部目录条目。
• iceberg_namespace_properties: 目录命名空间属性。
• lake_iceberg.metadata(uri): 原始Iceberg元数据JSON。
• lake_iceberg.files(uri): 清单路径、内容类型、数据文件路径/格式、规范ID、记录数和文件大小。
• lake_iceberg.snapshots(uri): 序列号、快照ID、时间戳和清单列表路径。
• lake_iceberg.data_file_stats(uri): 每个文件的序列号及下限/上限；执行权限授予 lake_read 而非 PUBLIC。
• iceberg_catalog: 版本3.4 FDW，用于命名PostgreSQL、对象存储或REST目录配置。

定义一个用户管理的REST目录服务器，并将凭据保存在用户映射中：

CREATE SERVER my_polaris TYPE 'rest'
FOREIGN DATA WRAPPER iceberg_catalog
OPTIONS (rest_endpoint 'https://polaris.example.com');

CREATE USER MAPPING FOR app_role SERVER my_polaris
OPTIONS (client_id 'app', client_secret 'secret');

CREATE TABLE catalog_events (id bigint)
USING iceberg
WITH (catalog = 'my_polaris');

目录和存储注意事项

• 用户创建的目录服务器需要自己的 USER MAPPING 凭证，不会回退到内置的REST目录凭证GUC。
• 内置的 postgres、object_store 和 rest 目录映射到不可变的扩展拥有者服务器。通过文档中的GUC进行配置，而不是修改这些服务器。
• 对 iceberg_tables 的外部修改默认被阻止，因为更改元数据可能会破坏pg_lake的事务和查询引擎一致性。
• Iceberg写操作应分批执行。每次语句可以添加Parquet文件和快照；常规 VACUUM 会压缩小文件并根据表/GUC策略过期数据。
• Iceberg对某些PostgreSQL值有更窄的表现形式。默认的 out_of_range_values = 'error' 保持完整性；clamp 默默改变超出范围的时间戳值，并用 NULL 替换一些不支持的值。