SeaTunnel 实战:PostgreSQL CDC 实时同步到 Iceberg(字段整形与 Upsert 完整指南)
SeaTunnel 实战:PostgreSQL CDC 实时同步到 Iceberg(字段整形与 Upsert 完整指南)
本篇技术指南基于 Apache SeaTunnel 官方 Recipe 文档(docs/en/getting-started/recipes/postgresql-cdc-to-iceberg.md),完整演示如何用 SeaTunnel Zeta 引擎将 PostgreSQL 14 的初始快照与增量变更(含 UPDATE / INSERT / DELETE)实时同步到 Apache Iceberg 表,并通过 Sql transform 对字段进行清洗与整形、以 Iceberg 的 upsert 模式维护目标表最新状态。读完本文,你将掌握 PostgreSQL 逻辑复制环境的搭建、connector-cdc-postgres 与 connector-iceberg 的完整配置、复制槽与 publication 的正确用法,以及一套可复现的验证与故障排查方法。
场景与管道总览
本 Recipe 解决的是数据湖实时入仓场景中的典型需求:源库表只允许只读账号访问,但目标数据湖需要拿到最新的一行状态。整个管道由三段组成:
Postgres-CDC源:通过 PostgreSQL 逻辑复制读取sales.inventory.customer_orders表的初始快照与后续变更;Sqltransform:对每一行做清洗与富化——去除客户姓名的首尾空格、将状态值规范化为大写、并补充sync_source字段标识数据来源;Icebergsink:以id为标识字段(primary key),开启 upsert 模式应用 CDC 事件,使得 INSERT 插入新行、UPDATE 覆盖旧行、DELETE 删除对应行,最终 Iceberg 表中始终保留“最新状态”。
该示例覆盖了 snapshot、update、insert、delete 四类事件,是理解 SeaTunnel CDC 全链路语义(快照 + 增量、行级变更、upsert 合并)的最佳入门案例。
前置条件
1. 完成 SeaTunnel 本地部署
先完成 Run your first job 指南,确认 bin/seatunnel.sh 可用,并已用 Zeta 引擎成功运行过第一个作业。
2. 安装所需连接器
在 ${SEATUNNEL_HOME}/config/plugin_config 中启用两个连接器。该文件使用 --connectors-v2-- 与 --end-- 分隔符标记插件选择区,仓库中默认已列出全部可用插件(见 config/plugin_config,其中第 34 行即 connector-cdc-postgres、第 92 行即 connector-iceberg),只需保留本次所需的两个即可:
--seatunnel-connectors--
connector-cdc-postgres
connector-iceberg
--end--
执行 bin/install-plugin.sh 下载插件(该脚本按 config/plugin_config 的选择清单解析 Maven 坐标并下载到 connectors/ 目录,默认插件版本为 3.0.0,也支持通过第一个参数指定自定义版本):
cd "${SEATUNNEL_HOME}"
sh bin/install-plugin.sh
ls connectors | grep -E 'connector-(cdc-postgres|iceberg)'
3. 放置 PostgreSQL JDBC 驱动
Zeta 引擎要求把 PostgreSQL JDBC 驱动 jar 放入 ${SEATUNNEL_HOME}/lib(Flink/Spark 引擎则放在 plugins/ 目录)。验证方式:
ls "${SEATUNNEL_HOME}/lib" | grep 'postgresql-'
驱动类为 org.postgresql.Driver,详见 PostgreSQL CDC 连接器文档 的 “Using Dependency” 一节。如需操作 GEOMETRY/GEOGRAPHY 类型,还需额外引入 postgis-jdbc。
4. 开启 PostgreSQL 逻辑复制
在 postgresql.conf 中修改以下参数,修改 wal_level 后必须重启 PostgreSQL(其他两项可用 ALTER SYSTEM + pg_reload_conf() 生效,但 wal_level 需重启):
wal_level = logical
max_replication_slots = 10
max_wal_senders = 10
确认配置已生效:
SHOW wal_level;
SHOW max_replication_slots;
SHOW max_wal_senders;
5. 创建源数据库与只读 CDC 账号
以 PostgreSQL 管理员身份创建数据库 sales 与专用 CDC 账号。若对象已存在则跳过对应 CREATE 语句直接复用:
CREATE DATABASE sales;
CREATE DATABASE 必须在事务外执行,完成后继续:
CREATE ROLE seatunnel_cdc WITH REPLICATION LOGIN PASSWORD 'change_me';
GRANT CONNECT ON DATABASE sales TO seatunnel_cdc;
在 pg_hba.conf 中为 CDC 账号添加一条匹配规则(将示例 CIDR 替换为 SeaTunnel 节点所在网络):
host sales seatunnel_cdc 192.0.2.0/24 scram-sha-256
关键点:逻辑复制连接的是实际数据库,因此这条规则中数据库名写 sales 而非物理复制所用的 replication 关键字。保存后重载配置:
SELECT pg_reload_conf();
关于权限的补充:从 PostgreSQL CDC 文档 FAQ 可知,CDC 账号必须具备
REPLICATION角色与目标表的SELECT权限;同时需要CONNECT、schema 的USAGE权限。SeaTunnel 只能从主库(primary)消费逻辑复制槽,不能直接从 standby 读取。
6. 选择 Iceberg 仓库路径
选择一个所有 SeaTunnel worker 都可写的空 Iceberg warehouse 路径:
- 本地
file://warehouse 仅适用于所有 worker 共享同一文件系统的单机/同机场景; - 分布式集群应使用 HDFS、S3 或其它共享 Catalog 存储,避免“每个节点各自落盘”导致数据分片。
准备源数据
以管理员身份连接 sales 库,在 PostgreSQL 14 中创建源 schema 与表,并授予只读 CDC 账号访问权限:
CREATE SCHEMA inventory;
CREATE TABLE inventory.customer_orders (
id BIGINT PRIMARY KEY,
customer_name VARCHAR(64) NOT NULL,
amount NUMERIC(10, 2) NOT NULL,
status VARCHAR(16) NOT NULL,
updated_at TIMESTAMP NOT NULL
);
ALTER TABLE inventory.customer_orders REPLICA IDENTITY FULL;
INSERT INTO inventory.customer_orders VALUES
(1001, ' Alice Zhang ', 120.50, 'pending', '2026-07-18 09:00:00'),
(1002, 'Bob Li', 80.00, 'paid', '2026-07-18 09:05:00');
GRANT USAGE ON SCHEMA inventory TO seatunnel_cdc;
GRANT SELECT ON TABLE inventory.customer_orders TO seatunnel_cdc;
CREATE PUBLICATION seatunnel_sales_orders_pub
FOR TABLE inventory.customer_orders;
几个值得注意的设计点:
REPLICA IDENTITY FULL让逻辑复制流中的 UPDATE/DELETE 事件携带完整的旧行数据。从 PostgreSQL CDC 文档 可知,默认require-replica-identity-full = true时,连接器会强制要求源表启用 FULL 复制标识;只有 append-only 场景(如 outbox 模式)才应显式关闭该校验。- 由管理员创建 publication,而不是 CDC 账号,这样 CDC 账号可以保持只读。作业配置中复用该 publication,而不是为库中每张表动态创建。
- 注意
pg_hba.conf中 publication 与 replication slot 均在sales数据库上维护,这与物理复制的全局语义不同。
初始快照写入 Iceberg 后,用源应用的写账号或管理员账号(而非只读 CDC 账号)执行以下变更,模拟增量事件:
UPDATE inventory.customer_orders
SET amount = 150.75, status = 'paid', updated_at = '2026-07-18 10:00:00'
WHERE id = 1001;
INSERT INTO inventory.customer_orders VALUES
(1003, ' Carol Wang ', 42.00, 'pending', '2026-07-18 10:05:00');
DELETE FROM inventory.customer_orders WHERE id = 1002;
完整作业配置(HOCON)
以下 HOCON 配置实现了完整管道。请将示例中的主机名、凭据、槽名与 warehouse 路径替换为你的环境值:
env {
parallelism = 1
job.mode = "STREAMING"
checkpoint.interval = 3000
}
source {
Postgres-CDC {
plugin_output = "postgres_orders_raw"
url = "jdbc:postgresql://postgresql.example.com:5432/sales"
username = "seatunnel_cdc"
password = "change_me"
database-names = ["sales"]
schema-names = ["inventory"]
table-names = ["sales.inventory.customer_orders"]
startup.mode = "initial"
decoding.plugin.name = "pgoutput"
slot.name = ${slot_name}
debezium = {
"publication.name" = "seatunnel_sales_orders_pub"
"publication.autocreate.mode" = "disabled"
}
}
}
transform {
Sql {
plugin_input = "postgres_orders_raw"
plugin_output = "iceberg_customer_orders"
query = "select id, trim(customer_name) as customer_name, amount, upper(status) as status_name, updated_at, 'postgresql_cdc' as sync_source from dual"
}
}
sink {
Iceberg {
plugin_input = "iceberg_customer_orders"
catalog_name = "recipe_catalog"
iceberg.catalog.config = {
"type" = "hadoop"
"warehouse" = ${warehouse}
}
namespace = "sales_analytics"
table = "customer_orders"
iceberg.table.primary-keys = "id"
iceberg.table.upsert-mode-enabled = true
schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST"
data_save_mode = "APPEND_DATA"
}
}
将配置保存为 ${SEATUNNEL_HOME}/config/postgresql-cdc-to-iceberg.conf,把 ${slot_name} 与 ${warehouse} 替换为带引号的字面量后运行:
cd "${SEATUNNEL_HOME}"
./bin/seatunnel.sh --config ./config/postgresql-cdc-to-iceberg.conf -m local
例如:
slot.name = "seatunnel_sales_orders"
"warehouse" = "file:///tmp/seatunnel/iceberg/postgres-cdc-recipe/"
配置逐段解析
env 段
parallelism = 1 保证 CDC 事件按序处理;job.mode = "STREAMING" 使作业在快照后持续消费 WAL;checkpoint.interval = 3000 控制提交间隔——Iceberg 的变更在每次 checkpoint 成功提交后才对外可见,因此该值同时决定了端到端可见延迟。
source 段(Postgres-CDC)
对照 PostgreSQL CDC 连接器文档 的 Source Options 表:
url:JDBC 连接串,格式jdbc:postgresql://host:5432/dbname,可追加?loggerLevel=OFF降低日志噪音;database-names/schema-names/table-names:监控范围。table-names使用全限定名database.schema.table格式;从 PostgresSourceConfigFactory.java 源码可见,连接器会把三位表名裁剪为 Debezium 使用的schema.table形式写入table.include.list,并把schema-names映射到schema.include.list;startup.mode = "initial":先同步历史快照再进入增量;其它可选值包括snapshot-only(一次性快照批作业)、committed-offset(从已存在复制槽的 committed LSN 开始,要求槽已存在)、earliest、latest;decoding.plugin.name = "pgoutput":PostgreSQL 10+ 内置的逻辑解码插件,也是默认值;可选decoderbufs、wal2json及其变体;slot.name:逻辑解码槽名称。同一 PostgreSQL 实例上并发的每个 CDC 作业必须使用不同的槽名,否则会互相抢占;默认值为seatunnel(见 PostgresIncrementalSourceOptions.java 中slot.name的定义);debezium段:透传 Debezium 属性。这里publication.name指向前面手动创建的 publication,publication.autocreate.mode = "disabled"禁止连接器自动建 publication——这与“管理员建 publication、CDC 账号保持只读”的设计一致。
transform 段(Sql)
Sql transform 文档 说明它使用内存 SQL 引擎对输入行做变换,plugin_input 必须与上游 plugin_output 一致,query 中的表名即 plugin_input 的值(这里用 from dual 占位)。本示例完成了三类操作:
trim(customer_name):去除客户姓名的首尾空格(清洗);upper(status) as status_name:将pending/paid规范化为PENDING/PAID并重命名(标准化);'postgresql_cdc' as sync_source:追加常量列,标记数据来源(富化/血缘)。
sink 段(Iceberg)
对照 Iceberg sink 文档:
catalog_name/namespace/table:指定目标 Catalog、命名空间与表名,默认 namespace 为default;iceberg.catalog.config:初始化 Iceberg Catalog 的属性。type = "hadoop"表示使用 Hadoop Catalog,warehouse指向存储根路径;也可改用hive(需uri = thrift://...)、rest或 Glue Catalog;iceberg.table.primary-keys = "id":必须显式声明。从 IcebergSinkOptions.java 源码注释可见:启用 upsert 模式后 sink 不再自动继承源表主键,必须显式提供 primary-key 列表;iceberg.table.upsert-mode-enabled = true:开启 upsert 合并。源码 IcebergSinkFactory.java 中通过Conditions.notBlank(IcebergSinkOptions.TABLE_PRIMARY_KEYS)做了强校验——upsert 模式与未配置主键二者不能共存;schema_save_mode = "CREATE_SCHEMA_WHEN_NOT_EXIST":目标表不存在时自动建表(默认值);data_save_mode = "APPEND_DATA":追加写入(默认值);若需要先清理目标数据再写入,可配置CUSTOM_PROCESSING并提供custom_sql。
验证结果
当增量 SQL 提交、且下一个 Iceberg checkpoint 完成后,sales_analytics.customer_orders 应恰好包含以下行:
| id | customer_name | amount | status_name | sync_source |
|---|---|---|---|---|
| 1001 | Alice Zhang | 150.75 | PAID | postgresql_cdc |
| 1003 | Carol Wang | 42.00 | PENDING | postgresql_cdc |
查询 Iceberg 表并核对上述主键集合与变换后的字段:
- 行
1001已从pending更新为PAID(UPDATE 事件经 upsert 覆盖旧行),且customer_name的空格被清除; - 行
1003是新增的 INSERT 事件结果; - 行
1002必须不存在(DELETE 事件已被应用到 Iceberg 表)。
从 Iceberg sink 文档 可知,sink 完整支持 CDC 写入(cdc 能力标记为已支持),这也是本方案能以行级变更维护湖表一致性的基础。
运维检查要点
- 监控
pg_replication_slots:复制槽会保留消费进度之后的 WAL。若消费者停止,WAL 可能无限增长直至占满磁盘,需关注confirmed_flush_lsn是否持续前进; - 复制槽生命周期:只有 CDC 作业被永久下线后才应手工删除对应槽;绝不要在一个活动作业运行期间删除或让多个活动作业共享同一槽。从 PostgreSQL CDC FAQ 可知:
startup.mode = "committed-offset"要求槽预先存在,连接器直接使用其confirmed_flush_lsn作为启动偏移; - 主键一致性:
iceberg.table.primary-keys必须与源表稳定不变的键对齐,且 upsert 模式要求显式配置该选项; - checkpoint 持续成功:Iceberg 的变更仅在提交成功后可见,若 checkpoint 失败需排查下游写入问题;
- 共享存储:多 worker 集群中切勿使用节点本地 warehouse 路径,除非该路径由共享存储(HDFS/S3 等)支撑。
故障排查清单
对照 PostgreSQL CDC 文档 与 Iceberg sink 文档,常见问题如下:
wal_level不是logical:修改后未重启 PostgreSQL,或配置未写入正确实例;- CDC 账号权限不足:缺少
REPLICATION角色、CONNECT权限、schema 的USAGE权限或表的SELECT权限; - 复制槽冲突:其它作业已占用所配置的
slot.name,或两个作业用了相同槽名; REPLICA IDENTITY FULL未设置:默认安全校验(require-replica-identity-full = true)会拒绝该表,除非确认是 append-only 场景并显式关闭校验;- Iceberg warehouse 不可写或不可见:路径权限不足,或多 worker 场景下节点间不共享存储;
- upsert 模式缺少主键:开启
iceberg.table.upsert-mode-enabled却未配置iceberg.table.primary-keys,作业在启动校验阶段即失败。
延伸阅读
- PostgreSQL CDC source 连接器文档:完整参数表、数据类型映射、无主键表方案、schema evolution(
ADD COLUMN)与 Debezium heartbeat 配置; - Iceberg sink 连接器文档:多 Catalog 示例(Hadoop / Hive / Glue / S3 Tables REST)、多表写入、branch 提交与 Kerberos 认证;
- Sql transform 文档:SQL 引擎能力边界(不支持多表 JOIN 与聚合)与嵌套结构字段查询语法;
- CDC Production Cookbook:面向生产环境的全量 + 增量同步生命周期、2PC sink 配置、schema evolution 与故障排查完整指南。