SeaTunnel 实战:PostgreSQL CDC 实时同步到 Iceberg(字段整形与 Upsert 完整指南)

原创2026-09-17 17:41:101,989 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

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 表的初始快照与后续变更;
  • Sql transform:对每一行做清洗与富化——去除客户姓名的首尾空格、将状态值规范化为大写、并补充 sync_source 字段标识数据来源;
  • Iceberg sink:以 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 与故障排查完整指南。
登录后查看全文
seatunnel