Debezium日常分享系列之：Debezium 3.3.0.Final发布

Debezium 核心功能

废弃的 snapshot 模式已被移除

在 Debezium 2.6 版本中，我们调整了 snapshot 模式的命名以更准确地反映其功能，具体包括：

• 废弃了 schema_only_recovery 模式，替换为 recovery 模式。
• 废弃了 schema_only 模式，替换为 no_data 模式。

从 Debezium 3.3 版本开始，schema_only_recovery 和 schema_only 模式已被完全移除。如果您的连接器配置仍然依赖这些废弃的模式，升级后会导致配置错误。因此，请务必相应地调整您的连接器配置。

Debezium Engine 类加载器变更

Debezium Engine 之前没有设置线程上下文类加载器，这可能会与 SpringBoot 等项目的集成带来问题。现在，线程上下文类加载器已被设置，并且 Debezium Engine 会使用提供的类加载器来加载所有类，而不仅仅是连接器相关的类。

Debezium JDBC Sink（JDBC 接收器）

数据类型精度变更说明

升级至 Hibernate 7.1.0.Final 版本后，对数据类型（尤其是时间类型和浮点类型）的处理精度进行了优化：

• 时间类型（Temporal Types）
  • time 和 timestamp 类型列现在默认采用更高精度。例如：
    Oracle 的 time 和 timestamp 列将使用 9 位小数精度（此前默认为 6 位）。
• 浮点类型（Floating-point Types）
  • Debezium 明确优先使用 float、real 和 double precision 表示浮点值。
    如果需要使用 Oracle 原生的 binary float 或 binary double 类型，需在连接器配置中设置：
    hibernate.dialect.oracle.use_binary_floats = true

Debezium 核心功能

Exactly-Once 语义支持

社区对 Debezium 支持 Exactly-Once（精确一次）语义 的呼声一直很高。通俗来说，Exactly-Once 语义意味着事件只会被投递并写入 Kafka 主题一次，从而避免重复数据的可能性。

我们很高兴地宣布，Debezium 3.3 版本已为所有核心连接器（包括 MariaDB、MongoDB、MySQL、Oracle、PostgreSQL 和 SQL Server）引入了 Exactly-Once 语义支持。

禁用上下文头信息

在 Debezium 3.2 中，我们引入了多个新的头信息，用于为 OpenLineage 提供上下文，这些头信息会自动添加到每个发出的事件中。一些用户反馈称，这些头信息无法禁用，这引发了他们的担忧，因为在某些环境中需要尽量精简事件负载。

基于社区反馈，我们引入了一个新的配置选项 extended.headers.enabled，可以将其设置为 false，从而禁用这些上下文事件头信息的添加。

心跳信号不再持续发送

在 Debezium 3.3.0.Alpha1 版本中，用户反馈在使用 heartbeat.action.query 时，Debezium 会无视配置的时间间隔，持续发送心跳事件。此问题已修复，heartbeat.action.query 现在会重新遵循 heartbeat.interval.ms 的配置间隔。

连接器启动失败并显示晦涩错误

我们已修复了一个问题：此前连接器会因误导性错误消息而启动失败，现已恢复平稳启动，同时保留了改进的偏移量验证功能。

问题背景

用户在某些极端情况下启动连接器时，会遇到如下令人困惑的异常：
org.apache.kafka.connect.errors.DataException: Invalid value: null used for required field: “schema”, schema type: STRING
该错误消息晦涩难懂，未提供实际问题的有效信息，导致排查几乎无法进行。

根本原因

此问题是我们近期对偏移量验证功能改进的意外副作用。我们优化了逻辑，以便在源数据库中偏移量位置不可用时提供更清晰的错误消息（这一功能有助于诊断常见运维问题）。
然而，新的验证逻辑假设某些偏移量属性在连接器启动时已可用。实际上，这些属性需在连接器生命周期后期才会被填充，导致验证过早失败并抛出无用的错误消息。

解决方案

我们更新了异常处理逻辑，具体改进包括：

• 避免假设：不再假设启动时偏移量属性已可用
• 保留验证：对真正无效的偏移量仍保持增强的验证
• 明确报错：当偏移量位置确实有问题时，提供有意义的错误消息
• 正常启动：避免误报，确保正常启动流程不受干扰

此修复确保您既能享受增强的错误报告功能，又不会因误判导致启动中断。

临时阻塞式快照失败可能导致数据丢失的问题已修复

我们解决了一个关键问题：当临时阻塞式快照（ad-hoc blocking snapshots）执行失败时可能导致数据丢失。现在即使快照失败，也能确保流式数据完整无缺。

问题描述

在运行临时阻塞式快照时，若表中存在无效数据会导致快照失败。此失败曾引发严重副作用：快照期间发生的流式事件会永久丢失。

这意味着，如果快照运行数小时后才遇到错误数据，连接器恢复正常流式操作时，会完全跳过这数小时内发生的所有实时变更。

解决方案

改进后的阻塞式快照通过以下方式优雅处理故障：

• 保留快照前的流式位置：记录快照开始前的精确位置
• 自动恢复正确位置：快照失败时从保存的位置继续处理
• 确保零数据丢失：无论快照何时或为何失败，数据完整性均不受影响
• 此改进显著提升了阻塞式快照在生产环境中的可靠性。

Debezium for MongoDB

从指定位置启动

Debezium 用户现在可以通过在连接器配置中指定新参数 capture.start.op.time，从 MongoDB oplog 的特定位置启动 MongoDB 源连接器。该参数需为表示 Bson 时间戳的 long 类型值。

若保留此配置参数，连接器重启时将尝试从指定位置恢复。

使用建议：当连接器开始流式传输变更后，应移除该参数，以确保后续重启遵循连接器偏移量中记录的恢复位置，而非固定时间戳。

MongoEventRouter 支持自定义追踪值

MongoEventRouter 现在支持将自定义的追踪配置值传递到路由器中，以便在事件负载中提供这些值。以下是可以提供的配置选项：

属性	描述
tracing.span.context.field	包含序列化跨度上下文（span context）的 java.util.Properties 表示的字段名称，默认为 tracingspancontext。
tracing.operation.name	表示 Debezium 处理跨度的运算名称，默认为 debezium-read。
tracing.with.context.field.only	当仅需追踪具有序列化上下文字段的事件时，设置为 true，默认为 false。

Debezium for MariaDB

支持 MariaDB 11.7+ 向量数据类型

MariaDB 11.7 引入了 VECTOR(n) 数据类型，使关系型数据库能够像向量数据库一样存储向量值。通过这一新类型，AI 模型生成的向量数据可直接存储于 MariaDB 中并支持检索。

Debezium 3.3 在以下场景中新增了对 MariaDB 向量数据类型的支持：

• 源连接器：捕获 MariaDB 中的向量数据变更
• JDBC Sink 连接器：向 MariaDB 目标数据库写入向量数据

模式历史记录改进

MariaDB 连接器使用模式历史记录主题（schema history topic）存储从二进制日志捕获的各种 DDL 操作，从而基于表结构变更的时间顺序构建关系模型。

在 Debezium 3.3 中，模式历史记录主题的过滤器已更新，不再存储与 Debezium 功能无关的语句，例如：

• 存储过程（procedure）
• 函数（function）
• 视图（view）
• 触发器（trigger）
• 权限操作（grant/revoke）

生效范围：

• 新连接器：直接应用改进后的过滤器，不存储上述无关语句。
• 现有连接器：仅过滤新增的、符合改进条件的 DDL 语句，已存储的历史事件不受影响。

Debezium for MySQL

模式历史记录改进

MySQL 连接器使用模式历史记录主题（schema history topic）存储从二进制日志捕获的各种 DDL 操作，从而基于表结构变更的时间顺序构建关系模型。

在 Debezium 3.3 中，模式历史记录主题的过滤器已更新，不再存储与 Debezium 功能无关的语句，例如：

• 存储过程（procedure）
• 函数（function）
• 视图（view）
• 触发器（trigger）
• 权限操作（grant/revoke）

生效范围：

• 新连接器：直接应用改进后的过滤器，不存储上述无关语句。
• 现有连接器：仅过滤新增的、符合改进条件的 DDL 语句，已存储的历史事件不受影响。

Debezium for PostgreSQL

支持文本搜索向量类型

PostgreSQL 13+ 引入了全文搜索数据类型。其中，tsvector 数据类型以优化文本搜索的形式表示文档，提供已排序的独立词元列表。

在 Debezium 3.3 中，现可捕获 tsvector 类型列的变更。这些列类型通过逻辑类型 io.debezium.data.Tsvector 输出，并在事件中以字符串类型表示。

JDBC Sink 连接器支持 TSVECTOR 数据类型

在 Debezium 3.3.0.Alpha1 中，我们为 PostgreSQL 源连接器引入了基于文本搜索的向量数据类型 TSVECTOR 支持。

本次更新进一步扩展了 JDBC Sink 连接器 对该类型的支持，使得 TSVECTOR 值可直接写入 PostgreSQL 目标数据库。

若目标为非 PostgreSQL 数据库，该值将被写入字符型列中。

发布DDL操作超时设置

虽然我们通常不会记录内部配置属性，但此前我们已为PostgreSQL连接器新增了一个内部配置参数internal.create.slot.command.timeout，用于在创建复制槽时设置默认的90秒超时。这一改进旨在解决因阻塞性事务导致复制槽无法创建的问题（活跃事务会阻止复制槽的创建）。

在Debezium 3.3中，我们将此超时机制扩展至PostgreSQL连接器的发布（publication）相关DDL操作。若您在创建/更新发布或复制槽时遇到超时问题，可以：

• 调高该参数值（默认90秒）
• 设为0以完全禁用超时功能
  （注：超时设置的单位为秒，适用于发布和复制槽的创建与修改操作。）

PostgreSQL的TOAST列性能优化

Debezium的PostgreSQL pgoutput解码器采用特定模式来判断TOAST列的值是否与预定义的标记对象匹配（这些标记对象表示该值在变更事件中不存在）。然而，当事件负载包含大量文本或二进制数据时，由于需要先计算哈希值，这种模式效率较低。

为了提升性能，新实现改用直接相等性检查，避免对大型TOAST列负载进行昂贵的哈希计算。这一优化显著降低了处理包含大文本或二进制数据事件时的开销。

按需修改发布

当Debezium PostgreSQL连接器配置为publication.autocreate.mode=filtered时，连接器会在每次重启时执行ALTER PUBLICATION语句，以确保发布内容与连接器配置保持一致。

在某些情况下，若底层表正在执行VACUUM操作或涉及长时间运行的DDL操作，连接器将被迫等待这些任务完成才能执行修改。为了优化流程并仅在必要时阻塞，连接器在filtered模式下会检查配置的表列表与当前发布的差异。仅当表列表存在差异时才会执行修改命令，否则跳过以避免潜在的阻塞调用。

Debezium for Oracle

遗留的十进制处理模式行为

在 Debezium 2.7 中，我们引入了一个错误修复，使 Oracle 连接器在使用 double 或 string 模式时的 decimal.handling.mode 行为与其他关系型数据库连接器保持一致。这一修复导致事件模式发生变化，给未预料到此类变更的升级用户带来了诸多问题。

我们考虑了多种方案（例如通过 CustomConverter 或 Transformation 提供旧版支持），但最终决定将兼容逻辑直接集成到连接器中，以提供更彻底的解决方案。

Debezium 3.3 的改进

新增配置项 legacy.decimal.handling.strategy，允许用户恢复旧版行为：
当数值的小数位数为零（即整数）且长度不超过 18 位时，不再自动转换为 double 或 string 类型，而是直接作为整数值输出。

升级建议

从 Debezium 2.7 之前版本升级：建议初始阶段启用此功能，以降低升级到 3.3 或更高版本的复杂度。

已升级至 Debezium 2.7-3.2：不建议启用旧版行为，否则会再次引入类似（但方向相反）的结构变更问题。

LogMiner实验性CTE查询支持

我们为Oracle LogMiner引入了一项新的内部实验性功能，该功能利用了称为CTE查询（Common Table Expression，公共表表达式）的概念。CTE查询是一种SQL构造，允许在另一个SQL操作的执行过程中定义临时的命名结果集，这种机制可基于多种原因提供便利。

在Debezium Oracle连接器中，新配置项internal.log.mining.use.cte.query会触发一个特殊的预处理步骤：

预过滤机制：检查所有事务，并仅对实际包含被捕获表DML操作的事务发送START、COMMIT和ROLLBACK事件。

性能优化：例如，若100个事务中仅有1个修改了目标表，则系统不仅会跳过其余99个事务的DML事件，还会省略这些事务的标记事件，从而显著减少冗余处理。
这项改进通过精准过滤无关事务，提升了日志挖掘效率。

最后批次处理吞吐量指标优化

我们提升了 Oracle LogMiner 适配器中 LastBatchProcessingThroughput JMX 指标的准确性，帮助您更清晰地监控连接器的性能表现。

旧版问题

此前，该指标基于每批次实际处理的表事件数量计算吞吐量。虽然看似合理，但在以下常见场景中会导致误导性结果：

• 数据库级过滤：即使连接器仍需读取和评估被过滤的记录，事件计数仍会减少；
• 事务标记干扰：事件流中的事务控制记录可能大幅拉低数值，低估实际处理负载；
• 配置影响：某些设置会扭曲指标，无法真实反映性能。

新版改进

现在，该指标基于从 LogMiner 数据集读取的 物理 JDBC 行数 计算吞吐量，无论这些行是否：

• 被 JVM 中的配置过滤；
• 属于事务控制记录；
• 与表或模式过滤器不匹配。

效果

您将获得更精确的原始处理能力视图，真实反映 Debezium 连接器在每批次处理窗口中的性能。

更智能的归档目标管理

针对特定Oracle连接器环境，现可采用基于优先级的归档目标策略。此前，用户需指定单一目标（如LOG_ARCHIVE_DEST_2），当主库切换后新主库使用不同目标名称时，需手动调整配置。

改进内容

多目标优先级配置：用户现可通过逗号分隔列表按优先级配置多个目标（DBZ-9041），例如：LOG_ARCHIVE_DEST_1,LOG_ARCHIVE_DEST_2。

自动适配故障转移：连接器会智能选择首个本地且有效的目标，无需人工干预配置变更。
示例场景

若主库使用LOG_ARCHIVE_DEST_1而备库使用LOG_ARCHIVE_DEST_2，启用此功能后，连接器将在主备切换时自动从LOG_ARCHIVE_DEST_1无缝切换至LOG_ARCHIVE_DEST_2。

XStream事件中提供的提交SCN

所有Debezium变更事件默认包含一个源信息块。对于Oracle，该信息块包含commit_scn字段，表示事务提交事件的系统变更号（SCN）。
此前，commit_scn仅在使用Oracle LogMiner时被填充。此版本中，我们将其支持扩展至Oracle XStream。

XStream不再刷新无效低水位标记

Debezium Oracle XStream实现需定期向Oracle Outbound Server刷新LCR位置。此刷新作为提示，告知Oracle该位置之前的所有变更已处理（类似于PostgreSQL向复制槽确认LSN的方式）。

此前由于偏移量刷新处理方式的问题，Oracle Outbound Server可能在尝试刷新低水位标记时误报失败，将有效位置视为无效。此问题现已修复，Outbound Server不再错误报告无效低水位位置。

Debezium for SQL Server

心跳机制改进

SQL Server 的心跳行为现在会在 CDC 表的捕获实例中没有变化的期间发出心跳事件（DBZ-9364）。这一改进有助于确保在数据库中由于非捕获表的变更导致 LSN（日志序列号）持续前进时，偏移量（offsets）仍能保持同步。

Debezium JDBC Sink

针对数据库错误的自我修复能力

JDBC Sink连接器现在能自动重试变更处理过程中发生的SQL异常，为自我修复场景提供关键缓冲，从而提升连接器的容错能力。

这一改进在多任务并发环境中尤为重要——当对同一表的并发写入导致锁冲突时，连接器不再完全失败或依赖运行时重启，而是能自行从这类临时性问题中恢复，显著提升了整体可靠性。