Kimserey Lam’s website, Software Development blog posts, videos and tutorials ·

Debezium PostgreSQL连接器——关键配置

💡 原文英文，约1400词，阅读约需5分钟。

📝

内容提要

本文介绍Debezium PostgreSQL连接器的关键配置：通过设置REPLICA IDENTITY FULL获取更新/删除前的数据；使用table.include/exclude.list过滤表；用publication.autocreate.mode控制发布模式；通过ByLogicalTableRouter将多表事件路由到单一Kafka主题；并提及快照模式、墓碑记录及生产配置示例，以优化CDC事件捕获。

🎯

关键要点

默认的Debezium PostgreSQL连接器配置在UPDATE和DELETE事件中缺少before值，因为PostgreSQL默认的replica identity只将主键写入WAL。
通过设置表的REPLICA IDENTITY FULL，可以让PostgreSQL将完整的旧行写入WAL，从而在UPDATE和DELETE事件中填充before值。
可以使用replica.identity.autoset.values配置自动为匹配的表设置REPLICA IDENTITY FULL。
如果只关心行的当前状态，使用默认的replica identity即可，因为FULL会增加WAL写入的开销。
使用table.include.list和table.exclude.list可以过滤要捕获的表，但两者不能同时使用。
publication.autocreate.mode可以设置为all_tables、filtered或disabled，其中disabled配合手动创建的publication提供最明确的控制。
ByLogicalTableRouter转换可以将多个表的事件路由到单个Kafka主题，简化主题管理和下游消费。
snapshot.mode控制连接器启动时的行为，initial是最常见的选择，它会先快照现有数据，然后流式捕获变更。
tombstones.on.delete设置为false可以避免在DELETE后产生额外的墓碑事件。
生产配置示例结合了表过滤、replica identity自动设置、单主题路由和显式publication管理，并包含SSL、重试和最大消息大小等设置。

🔎

延伸解读

REPLICA IDENTITY FULL 的代价

虽然设置 REPLICA IDENTITY FULL 能获取更新和删除前的完整行数据，但代价是每次 UPDATE 和 DELETE 都会在 WAL 中写入更多数据，增加磁盘 I/O 和复制开销。如果下游只关心行的最新状态（例如全量覆盖同步），默认的 replica identity 就足够，无需为所有表开启 FULL。建议仅对需要审计或变更追踪的关键表启用，并利用 replica.identity.autoset.values 按模式自动配置。

publication 管理的取舍

publication.autocreate.mode 设为 disabled 并手动创建 publication，能避免新表被意外捕获，但要求 DBA 在迁移脚本中显式维护 publication 的表列表。相比之下，all_tables 模式简单但会捕获所有表，filtered 模式则依赖 table.include.list。生产环境推荐 disabled，因为它将 schema 变更的控制权交给数据库迁移流程，减少连接器自动行为带来的不确定性。

单主题路由的适用场景

ByLogicalTableRouter 将所有表的事件路由到一个 Kafka 主题，简化了主题管理和下游订阅，但消费者需要根据 source.table 字段区分不同表的事件，并处理混合的事件类型。这种模式适合数据仓库或 S3 等统一目标，但若下游按表独立处理，多主题可能更清晰。此外，跨表事务的事件虽在同一主题，但不保证同一分区，因此全局顺序无法保证。

❓

延伸问答

为什么Debezium PostgreSQL连接器默认的UPDATE和DELETE事件中before字段是null？

因为PostgreSQL默认的replica identity只将主键写入WAL，不包含完整的旧行数据，所以Debezium无法获取更新或删除前的完整行状态。

如何让Debezium PostgreSQL连接器在UPDATE和DELETE事件中获取before值？

需要将表的replica identity设置为FULL，可以通过手动执行ALTER TABLE ... REPLICA IDENTITY FULL，或使用replica.identity.autoset.values配置自动设置。

设置REPLICA IDENTITY FULL有什么代价？什么时候不需要设置？

设置FULL会增加WAL写入的开销，因为每次UPDATE和DELETE都会写入完整旧行。如果只关心行的当前状态（例如复制到其他数据库并覆盖目标行），则不需要设置FULL，使用默认的replica identity即可。

Debezium PostgreSQL连接器如何过滤要捕获的表？

可以使用table.include.list指定要捕获的表（白名单），或使用table.exclude.list排除不需要的表（黑名单），但两者不能同时使用。

publication.autocreate.mode的各个选项有什么区别？生产环境推荐用哪个？

all_tables自动为所有表创建发布；filtered只为table.include.list中的表创建发布；disabled要求手动创建发布。生产环境推荐使用disabled，配合手动创建的publication，可以显式控制捕获的表，避免新表自动被捕获。

如何将多个表的Debezium事件路由到同一个Kafka主题？

使用ByLogicalTableRouter转换，配置topic.regex匹配所有表，topic.replacement指定目标主题，例如："transforms.route.type": "io.debezium.transforms.ByLogicalTableRouter", "transforms.route.topic.regex": ".*", "transforms.route.topic.replacement": "learn.v0.cdc"。

将多个表路由到单个Kafka主题有什么优缺点？

优点：简化主题管理，下游只需订阅一个主题；便于跨表排序（同一事务的事件可能在同一主题）。缺点：消费者需要处理混合事件类型，并根据source.table字段区分。

Debezium PostgreSQL连接器的snapshot.mode有哪些选项？各自适用什么场景？

initial：首次启动快照所有现有数据，然后流式捕获变更，是最常见的选择；never：不进行快照，只捕获启动后的变更，适用于历史数据已通过其他方式加载的场景；when_needed：在复制槽不存在或WAL位置不可用时进行快照；initial_only：只做快照，不进行流式捕获。

tombstones.on.delete设置为false有什么作用？

设置为false后，DELETE事件后不会产生额外的墓碑事件（值为null的Kafka消息）。如果下游不依赖Kafka日志压缩，可以避免多余事件。

生产环境中Debezium PostgreSQL连接器有哪些关键配置？

生产配置通常包括：使用publication.autocreate.mode=disabled手动管理发布；设置replica.identity.autoset.values以获取before值；使用table.include.list过滤表；使用ByLogicalTableRouter路由到单一主题；启用SSL（database.ssl.mode=require）；设置重试超时（errors.retry.timeout）和最大消息大小（producer.override.max.request.size）等。

🏷️