2.4. Debezium 2.5.4 功能和改进

如果您希望保留原始行为，请通过在连接字符串中添加以下选项来自定义连接器配置：

&readPreference=secondaryPreferred

如果连接器从分片集群读取，mongodb.connection.mode 被设置为 replica_set，请使用新的 mongodb.connection.string.shard.params 属性来指定将读取首选项设置为 二级 的连接字符串。如需更多信息，请参阅 Debezium 用户指南中的 连接器文档。

升级连接器后，新的默认设置会导致现有偏移无效，并触发初始快照的静默重新执行(DBZ-7272)。为防止此行为，在重启会触发快照时，添加了检查会失败连接器。

如果您的连接器从分片集群读取，在升级后，检查连接器配置并根据需要调整连接模式。您可以明确设置 replica_set 连接模式，或者删除现有偏移。

如果您使用带有之前设置的连接器的 schema registry，如果 registry 强制执行严格的兼容性规则，这个更改可能会导致不兼容。升级连接器后，根据需要采取措施来确保输出值准确表示，且没有精度丢失，例如调整兼容性设置。

与其它供应商的实现不同，Debezium JDBC sink 连接器可以集中更改由 Debezium 源连接器发出的事件，而无需首先通过事件扁平化转换过程。Debezium JDBC 连接器可以减少管道的处理空间并简化其配置。连接器还可以利用 Debezium 源连接器功能，如列类型传播。如需更多信息，请参阅 Debezium 用户指南

现在，使用 MongoDB 连接器执行分片集群的增量快照多副本集群现在被完全支持。如需更多信息，请参阅 Debezium 用户指南。

在以前的版本中，当您在分片集群部署中将 Debezium 连接器用于 MongoDB 时，连接器会直接打开与每个分片副本集的连接。这不是推荐的方法，而 MongoDB 推荐连接器 使用 mongos 实例（路由器）打开连接。

此发行版本与推荐的策略一致。可能需要调整您的配置，将连接器指向 mongos 实例。

为了保持向后兼容，可以使用新的配置属性 mongodb.connection.mode。此属性的默认值 replica_set 保留当前行为，以便连接器将每个分片作为单个副本集处理。将值设为 sharded，以指示连接器内部使用名为 cluster 进行人工命名的 ReplicaSet 实例。此配置会导致连接器使用最初提供的连接字符串来处理与 ths shard 的所有成员的连接。

如需更多信息，请参阅 MongoDB 分片集群支持。

增量快照是处理各种快照用例的流行方法。但是，在某些情况下，快照读取事件与流事件（创建、更新和删除）进行干预，则增量快照的使用可能无法被消耗的应用程序表示甚至支持。在这些情况下，可以执行临时阻塞快照。

虽然您可以通过向 Debezium 发送信号来触发临时阻止快照和临时阻塞快照，但当连接器处理阻塞快照信号时，它会将一个保存在快照进程期间的流上。因此，快照会在快照读取事件和流创建、更新和删除事件之间保持隔离。换句话说，阻塞快照过程与进程以及传统的快照类似。因此，吞吐量通常高于增量快照。

启动临时阻塞快照的信号与用于启动临时增量快照的信号类似。以下示例显示了启动带有条件的特定表的阻塞快照的信号有效负载。此信号与增量快照的信号的唯一区别在于，信号 的类型 被设置为 BLOCKING 而不是 INCREMENTAL。

{
  "type": "execute-snapshot",
  "data": {
    "data-collections": ["public.my_table"],
    "type": "BLOCKING",
    "additional-condition": "last_update_date >= '2023-01-01'"
  }
}

如需更多信息，请参阅 Debezium 用户指南中为您的连接器类型 阻止快照。

客户通常会要求发出时区为 UTC 以外的值列的功能。在过去的版本中，您可以创建一个 CustomConverter，或编写自己的单个消息转换，以指定连接器如何发出临时列。

在本发行版本中，Debebe 提供一个新的时区转换，可让您在连接器发出的事件中修改临时列的时区。您可以根据管道的需求，将列从默认 UTC 时区转换为任何其他时区。要开始进行这个新转换，请在连接器中添加以下基本配置：

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York"
}

添加上述配置后，当连接器发出事件时，UTC 中的所有时列都会转换为' America/New_York' 时区。

您不仅可以更改 temporal 字段的时区，您也可以使用 include.fields 属性修改其他字段的时区设置，如下例所示：

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York",
  "transforms.tz.include.fields": "source:customers:created_at,customers:updated_at"
}

在前面的示例中，include.fields 中的第一个值会转换 源 表的 created_at 字段的时区，名称为 customer。下一个值将带有名称 customer 的主题的 updated_at 字段转换。

或者，如果要将转换应用到所有但字段子集，您可以设置 exclude.fields 属性，如下例所示：

{
  "transforms": "tz",
  "transforms.tz.type": "io.debezium.transforms.TimezoneConverter",
  "transforms.tz.converted.timezone": "America/New_York",
  "transforms.tz.exclude.fields": "source:customers:updated_at"
}

在前面的示例中，转换将所有临时字段转换为 America/New_York 时区，但 源 表名称 是客户，该字段为 updated_at。如需更多信息，请参阅 Debezium 用户指南中的 Debezium 事件记录中的转换时区值。

现在，您可以指定自定义标签来附加到连接器 MBean 对象名称的名称中。自定义标签允许您配置更可靠的连接器监控。

Debezium 连接器公开指标，提供有关快照、流和架构历史记录进程行为的数据。这些指标为每个连接器可用，并通过连接器的 MBean 名称公开。

默认情况下，当您部署正确配置的连接器时，Debebe 会为连接器生成一个唯一的 MBean。您可以配置可观察堆栈来监控与该 MBean 关联的指标。如果您稍后更改连接器配置，这些更改可以修改原始的 MBean 名称。如果 MBean 名称发生变化，连接器实例和 MBean 中断之间的链接，而监控工具将无法再检索连接器的指标数据，除非您重新配置可观察堆栈以使用新的 MBean 名称。

为了避免 MBean 名称更改的结果的潜在 churn，您可以通过将 custom.metric.tags 属性添加到连接器配置来将连接器配置为使用自定义指标标签。custom.metric.tags 属性接受键值对。每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。

为连接器配置 custom.metric.tags 属性后，将 observability 堆栈配置为检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是 mutable MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它构造 MBean 名称的方式，或者连接器配置更改中的 topic.prefix，指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。

使用自定义标签的进一步优点是，您可以使用标签来反映数据管道的架构，以便以适合您的操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。

以下示例演示了标签如何修改默认的 MBean 名称。

debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>

debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory

Debezium MongoDB 连接器现在支持 MongoDB 6 的大型文档处理。这个更改可防止连接器在试图捕获超过 16MB 的文档时返回 BSONObjectTooLarge 异常。要将连接器配置为利用此功能，请设置 oversize.handling.mode 选项。

Debezium 通知子系统提供了一种简单的方法，可以将第三方工具和应用程序与 Debezium 集成，以深入了解传统的 JMX 方法以外的持续更改数据捕获过程。在早期版本中，Debezium 通知子系统仅提供有关初始快照的基本信息，如快照启动时、每个表启动和结束快照时。notification 子系统现在包括告知您初始快照持续状态的功能。

初始快照通知使用 Initial Snapshot 的 aggregatetType 发送，包含公开快照当前状态的 type 字段。可能的值包括： STARTED、ABORTED、PAUSED、RESUMED、IN_PROGRESS、TABLE_SCAN_COMPLETED 和 COMPLETED。

DBZ-6878 扩展基本功能，以提供有关快照的增强详情。例如，IN_PROGRESS 通知现在提供有关捕获的表以及当前正在进行中的表的更多详情，如下例所示：

{
   "id":"6d82a3ec-ba86-4b36-9168-7423b0dd5c1d",
   "aggregate_type":"Initial Snapshot",
   "type":"IN_PROGRESS",
   "additional_data":{
      "connector_name":"my-connector",
      "data_collections":"table1, table2",
      "current_collection_in_progress":"table1"
   },
   "timestamp": "1695817046353"
}

此发行版本引入了属性 incremental.snapshot.watermarking.strategy，它允许您指定在增量快照期间使用的水位线策略。过去的版本使用 insert_insert 方法，Debezium 在各个块的快照期间在信号数据收集中创建了两个条目。第一个条目指出了快照窗口打开的，下一条目会标记其 closure。

新的 insert_delete 选项会在快照窗口开始时将单个条目写入每个块的信号数据收集。快照完成后，条目会被删除，且不会添加对应的条目来表示快照窗口的冲突。此方法提供对信号数据收集的更有效的管理。

由于某些源数据库功能的方式，当 Debezium 连接器发出更改事件时，事件可能会排除存储大量数据的列类型的值。例如，PostgreSQL 中的 TOAST 列的值、Oracle 中的 LOB 列或 Oracle Exadata 中的 扩展 String 列可能不包括在更改事件中。

Debezium 2.5.4 在 处理器后引入了 Reselect 列，它提供了一种机制来重新选择连接器从数据库表中捕获的一个或多个列，并获取这些列的当前状态。您可以将后处理器配置为重新选择以下列类型：

配置 PostProcessor 与配置自定义转换器或单一消息转换类似，但它适用于 mutable 有效负载的 Struct 而不是 SourceRecord。如需更多信息，请参阅 Debezium 用户指南中的 使用-the-reselect-columns-post-processor-to-add-source-fields-to-change-event-records。

当 MongoDB 的 Debezium 连接器发出更改事件时，您可以配置连接器，以便事件有效负载包括更新中更改的完整源文档。在过去的版本中，连接器不会在事件有效负载中一致地流传输完整的文档。

要显式控制连接器如何在更改流中查找完整的文档，请设置配置选项 capture.mode.full.update.type。此选项的默认值会查找完整的文档，这需要数据库执行单独的查找来获取完整文档。如果您将连接器与 MongoDB 6 或更高版本搭配使用，您可以将连接器配置为使用 post_image 来依赖 MongoDB 的 post-image 支持。

如需更多信息，请参阅 Debezium 用户指南中的 MongoDB 连接器部分中的 capture.mode.full.update.type。

从 Debezium 2.5.4 开始，您可以针对单个 MariaDB 数据库部署运行 MySQL 连接器。MySQL 和 MariaDB 都可以使用 全局事务标识符(GTID) 进行复制。GTID 有助于在集群中唯一标识事务。

要使 MySQL 连接器与 MariaDB GTID 一起使用，您必须将 supplemental 配置应用到连接器。如需更多信息，请参阅 Debezium 用户指南

使用 PostgreSQL 16，您现在可以在独立实例上定义复制插槽。根据对数据库的这一更改，在 Debezium 中，您现在可以连接到备用 PostgreSQL 16 服务器，并从其中流传输更改。通过从副本而不是生产系统执行数据捕获，您可以更好地分发服务器负载，特别是在非常活跃的数据库中。

CloudEvwents converter 会发出符合 CloudEvents 规格的更改事件记录。CloudEvents 更改事件 envelope 可以是 JSON 或 Avro，每个 envelope 类型都支持 JSON 或 Avro 作为 数据格式。如需更多信息，请参阅 CloudEvents 转换程序。

如果默认数据类型转换无法满足您的需要，您可以创建自定义转换器以用于连接器。如需更多信息，请参阅自定义开发的转换器。

如需更多信息，请参阅 Debezium 用户指南中的 Oracle 二进制字符 LOB 类型。

使用多个并行线程执行初始快照的功能作为 MySQL 以外的所有 Debezium SQL 连接器的技术预览功能提供。Debezium MySQL 连接器的并行初始快照 作为开发者预览功能提供。

要将连接器配置为使用并行初始快照，请将连接器配置中的 snapshot.max.threads 属性设置为大于 1 的值。

如需更多信息，请参阅 Debezium 用户指南文档中的 snapshot.max.threads 部分用于您的连接器。

要提高 MySQL 连接器的快照性能，实现并行快照更改事件和表的模式事件

这可减少捕获数据库中多个表的架构时的快照时间。

配置此属性后，连接器使用收集指标时基于这些键值对的 name 模式。这会建立一个稳定的名称，以便连接器始终收集相同的指标集合，无论您是否修改 topic.prefix，还是 MBean 名称更改。自定义每个连接器实例的 MBean 对象名称。通过添加这些自定义指标标签，您可以确保每个连接器都有唯一的 MBean 名称，防止多个实例间的冲突。

MySQL 的 Debezium 初始快照始终是单线程。这种限制主要源自确保多个交易间的数据一致性的复杂性。

在这个发行版本中，您可以将 MySQL 连接器配置为使用多个线程并行执行表级快照。

为了利用这个新功能，请将 snapshot.max.threads 属性添加到连接器配置中，并将属性设置为大于 1 的值。

snapshot.max.threads=4

在上例中，如果连接器需要快照超过 4 个表，则最多 4 个表可以并行快照。当一个线程完成处理表时，它将在队列中找到下一个表并开始执行快照。此过程将继续，直到连接器完成所有指定表的快照。

如需更多信息，请参阅 Debezium 用户指南中的 snapshot.max.threads。

当 Oracle 的 Debezium 连接器连接到生产环境或主数据库时，它使用内部清除表来管理 Oracle Log Writer Buffer (LGWR)进程的清除周期。flush 过程要求连接器访问数据库的用户帐户具有创建和写入此 flush 表的权限。但是，逻辑代表数据库通常具有限制性的数据操作规则，甚至是只读的。因此，对数据库的写入可能并不可行。

为了支持 Oracle 只读逻辑独立数据库，Debezium 引入了一个属性，用于禁用 flush 表的创建和管理。您可以将此功能用于 Oracle Standalone 和 Oracle RAC 安装。

要启用 Oracle 连接器使用只读逻辑，请添加以下连接器选项：

internal.log.mining.read.only=true

如需更多信息，请参阅 Debezium 用户指南中的 Oracle 连接器文档。

在本发行版本中，Debebe 支持 PostgreSQL 连接器的只一次语义。PostgreSQL 的一次交付仅适用于 streaming 阶段；完全发送不适用于快照。

Debezium 旨在通过确保连接器捕获受监控源中的所有更改事件为目标，提供 at-least-once 交付。在 KIP-618 中，Apache Kafka 社区建议一种解决生成者重试消息时发生的问题的解决方案。源连接器有时会将事件批处理重新发送到 Kafka 代理，即使之前提交了批处理的代理也是如此。这种情况可能会导致重复的事件发送到消费者（接收器连接器），这可能会导致无法轻松处理重复的用户出现问题。

不需要更改连接器才能启用精确发送。但是，必须在 Kafka Connect worker 配置中配置准确的发送。有关设置所需的 Kafka Connect 配置属性的详情，请参考 KIP-618。