Debezium配置snapshot.new.tables=parallel未生效 新增表直接读取binlog

问题现象 #

连接器初始化完成后运行状态正常，已在配置中写入snapshot.new.tables=parallel参数，但在向table.include.list中新增监控表时，连接器不对新增表执行全量快照，直接从当前最新binlog位点开始拉取增量数据。
现有连接器配置如下：

{
  "connector.class": "io.debezium.connector.mysql.MySqlConnector",
  "database.dbname": "db_name",
  "database.hostname": "host",
  "database.port": "3306",
  "database.user": "user",
  "database.password": "pass",
  "database.server.name": "server",
  "database.include.list": "db_name",
  "table.include.list": "table1,table2",
  "decimal.handling.mode": "double",
  "name": "server",
  "database.history.kafka.bootstrap.servers": "kafka",
  "database.history.kafka.topic": "stopic",
  "offset.flush.interval.ms": "5000",
  "offset.flush.timeout.ms": "60000",
  "slot.name": "slot_name",
  "snapshot.lock.timeout.ms": "99999999",
  "snapshot.mode": "when_needed",
  "tombstones.on.delete": "false",
  "snapshot.new.tables":"parallel",
  "sanitize.field.names": "true",
  "snapshot.fetch.size": 50000,
  "snapshot.locking.mode": "none",
  "database.initial.statements": "SET SESSION wait_timeout=28800;SET SESSION interactive_timeout=28800;"
}

参数不生效的核心原因 #

• 快照模式配置不匹配
  snapshot.new.tables=parallel 的并行新增表快照能力，不兼容snapshot.mode=when_needed的快照判定逻辑。when_needed模式的核心机制是仅在连接器整体缺失全局binlog位点、第一次启动时才触发全量快照，只要连接器已经持久化了有效offset，就会标记全局快照流程已完成，不会单独对新增表触发快照分支。该模式下即使写入了parallel参数，也不会进入新增表快照的处理流程。
• 版本兼容问题
  snapshot.new.tables 参数是Debezium 1.6版本才正式引入的能力，若当前运行版本低于1.6，配置项会被直接解析忽略，无任何生效逻辑。同时在2.0版本之前，该参数与snapshot.locking.mode=none存在已知兼容缺陷：并行快照逻辑默认需要获取表级MDL锁完成一致性快照，当锁模式配置为none时，前置校验不通过，会静默跳过新增表的快照流程，直接跳转到binlog拉取阶段。
• 配置未实际加载到运行时
  若修改配置后仅做了连接器的状态重平衡，没有触发完整的连接器重启流程，Kafka Connect运行时的配置缓存会保留旧的参数列表，snapshot.new.tables的配置不会被实际加载。需要从连接器启动日志中确认是否打印了该参数的加载记录，排除配置丢失问题。
• 权限不足导致快照被静默跳过
  若连接器使用的数据库账号对新增表没有全表SELECT权限，连接器会静默跳过该表的快照流程，直接将表的拉取位点设置为当前binlog的最新位置，全程无报错，仅输出权限不足的warn级日志。
• Schema历史元数据错位
  若用于存储表结构历史的Kafka topic（本配置中为stopic）中已存在新增表的schema记录（比如之前曾将该表加入监控列表、后移除），连接器启动时会判定该表的元数据已完成持久化，无需触发快照，直接从当前binlog位点开始拉取数据。

验证修正步骤 #

• 升级Debezium版本至1.6及以上的稳定版，规避低版本的兼容缺陷
• 将snapshot.mode从when_needed调整为initial，该模式不会触发已有老表的重复全量快照，仅会对没有快照记录的新增表触发并行快照流程
• 对连接器执行完整的停止-重启流程，确认启动日志中明确加载到snapshot.new.tables=parallel参数，无参数不识别的warn日志
• 校验数据库账号对所有table.include.list下的表都具备全表SELECT权限
• 排查schema历史topic中是否存在待新增表的旧元数据记录，如存在可清理对应记录后再重启连接器

内容的提问来源于stack exchange，提问作者Anmol Virmani