红帽全球峰会Debezium 用户指南
前言
Debezium 是一组分布式服务，用于捕获数据库中的行级更改，以便您的应用程序可以查看并响应这些更改。Debezium 记录所有行级更改提交到每个数据库表。每个应用程序读取所需的事务日志，以按照发生的顺序查看所有操作。
本指南提供有关使用以下 Debezium 主题的详细信息：
对红帽文档提供反馈
我们感谢您对我们文档的反馈。
要进行改进，请创建一个 Jira 问题，并描述您推荐的更改。尽可能提供更详细的信息，以便我们快速解决您的请求。
前提条件
-
您有一个红帽客户门户网站帐户。此帐户允许您登录到 Red Hat Jira Software 实例。
如果您没有帐户，系统会提示您创建一个帐户。
流程
- 单击以下链接： 创建问题。
- 在 Summary 文本框中，输入问题的简短描述。
在 Description 文本框中，提供以下信息：
- 找到此问题的页面的 URL。
-
有关此问题的详细描述。
您可以将信息保留在任何其他字段中，使其默认值。
- 点 Create 将 JIRA 问题提交到文档团队。
感谢您抽出时间提供反馈。
第 1 章 Debezium 的高级别概述
Debezium 是一组分布式服务，用于捕获数据库中的更改。您的应用程序可以使用并响应这些更改。Debezium 在更改事件记录中捕获每个数据库表中的每行级更改，并将这些记录流传输到 Kafka 主题。应用程序读取这些流，按生成的顺序提供更改事件记录。
以下部分中更多详情：
1.1. Debezium 功能
Debezium 是 Apache Kafka Connect 的一组源连接器。每个连接器使用该数据库的功能来更改数据捕获(CDC)，从不同的数据库进行最佳更改。和其它方法（如轮询或双写）不同，基于日志的 CDC 是由 Debezium 实施的：
- 确保捕获了所有数据更改。
- 生成更改事件，延迟非常低，同时避免增加频繁轮询所需的 CPU 用量。例如，对于 MySQL 或 PostgreSQL，延迟在 millisecond 范围内。
- 不需要更改数据模型，如"Last Updated"列。
- 可以捕获 删除。
- 可以捕获旧的记录状态和其他元数据，如事务 ID 并导致查询，具体取决于数据库的功能和配置。
基于日志的 Change Data Capture 的五个优势是提供更多详细信息的博客文章。
Debezium 连接器使用一组相关功能和选项捕获数据更改：
- 快照： 如果连接器启动且并非所有日志都存在，则可以执行数据库当前状态的初始快照。通常，当数据库在一段时间内运行并丢弃事务恢复或复制时不再需要的事务日志时，会出现这种情况。执行快照有不同的模式，包括对 增量 快照的支持，可在连接器运行时触发。如需了解更多详细信息，请参阅有关您使用的连接器的文档。
- 过滤器： 您可以使用 include/exclude 列表过滤器配置捕获的模式、表和列的集合。
- 屏蔽： 特定列中的值可以屏蔽，例如当包含敏感数据时。
- 监控： 大多数连接器都可使用 JMX 监控。
- 随时可用的 单消息转换(SMTs) 用于消息路由、过滤、事件扁平化等。有关 Debezium 提供的 SMTs 的更多信息，请参阅 应用转换来修改与 Apache Kafka 交换的消息。
每个连接器的文档提供有关连接器功能和配置选项的详细信息。
1.2. Debezium 架构的描述
您可以使用 Apache Kafka Connect 部署 Debezium。Kafka Connect 是一个用于实现和操作的框架和运行时：
- 源连接器，如将记录发送到 Kafka 的 Debezium
- 将记录从 Kafka 主题传播到其他系统的接收器连接器
下图显示了基于 Debezium 的更改数据捕获管道的架构：
如镜像所示，部署了 MySQL 和 PostgresSQL 的 Debezium 连接器，以捕获对这些两种类型的数据库的更改。每个 Debezium 连接器建立到其源数据库的连接：
-
MySQL 连接器使用客户端库来访问
binlog。 - PostgreSQL 连接器从逻辑复制流读取。
除了 Kafka 代理外，Kafka Connect 作为单独的服务运行。
默认情况下，从一个数据库表的更改写入一个 Kafka 主题，其名称与表名称对应。如果需要，您可以通过配置 Debezium 的主题 路由转换来调整目标主题名称。例如，您可以：
- 将记录路由到名称与表名称不同的主题
- 将多个表的流更改事件记录到一个主题中
在 Apache Kafka 中更改事件记录后，Kafka Connect 生态系统中的不同连接器可以将记录流传输到其他系统和数据库，如 Elasticsearch、数据仓库和分析系统或缓存，如 Infinispan。根据所选的接收器连接器，您可能需要配置 Debezium 新记录状态提取 转换。此 Kafka Connect SMT 将 Debezium 更改事件中的 after 结构传播到接收器连接器。修改的更改事件记录替换默认传播的原始、更详细记录。
Debezium Server
您还可以使用 Debezium Server 部署 Debezium。Debezium 服务器是一个可配置的可随时使用的应用程序，它将事件从源数据库改为各种消息传递基础架构。
Debezium Server 只是开发者预览软件。红帽不支持开发人员预览软件，且功能完整或生产就绪。不要将开发人员预览软件用于生产环境或关键业务工作负载。开发人员预览软件提供早期对即将推出的产品软件的访问权限，以将其包括在红帽产品产品中。客户可以使用此软件来测试功能并在开发过程中提供反馈。此软件可能没有任何文档，可以随时更改或删除，并且已获得有限的测试。红帽可能会提供在没有关联 SLA 的情况下对开发者预览软件提交反馈的方法。
有关 Red Hat Developer Preview 软件的支持范围的更多信息，请参阅 开发人员预览支持范围。
下图显示了使用 Debezium 服务器的更改数据捕获管道的架构：
您可以将 Debezium 服务器配置为使用一个 Debezium 源连接器来捕获源数据库中的更改。更改事件可以序列化为不同的格式，如 JSON 或 Apache Avro，然后发送到各种消息传递基础架构之一，如 Apache Kafka 或 Redis Streams。
第 2 章 源连接器
Debezium 提供了一个源连接器库，用于捕获来自各种数据库管理系统的更改。每个连接器都使用非常类似的结构生成更改事件，从而可以轻松地使用应用程序并响应事件，而不考虑其原始卷。
目前，Debebe 为以下数据库提供源连接器：
2.1. Db2 的 Debezium 连接器
Debezium 的 Db2 连接器可以捕获 Db2 数据库表中的行级更改。有关与此连接器兼容的 Db2 数据库版本的详情，请参考 Debezium 支持的配置 页面。
此连接器主要由 SQL Server 的 Debezium 实施实现，它使用基于 SQL 的轮询模型，将表置于"捕获模式"。当表处于捕获模式时，Debezium Db2 连接器会为表生成更改事件。
处于捕获模式的表有一个关联的更改数据表，Db2 创建。对于处于捕获模式的表的每个更改，Db2 将有关该更改的数据添加到表相关的更改表中。change-data 表包含一行的每个状态的条目。它还具有删除的特殊条目。Debezium Db2 连接器从 change-data 表读取更改事件，并将事件发送到 Kafka 主题。
当 Debezium Db2 连接器连接到 Db2 数据库时，连接器读取连接器配置为捕获更改的表的一致性快照。默认情况下，这是所有非系统表。有连接器配置属性，允许您指定将哪些表放入捕获模式，或者指定要从捕获模式中排除的表。
当快照完成后，连接器开始向处于捕获模式的表发出更改事件。默认情况下，更改特定表的事件会进入与表相同的 Kafka 主题。应用程序和服务消耗来自这些主题的更改事件。
连接器需要使用抽象语法表示法(ASN)库，该库作为 Linux 的 Db2 的标准部分提供。要使用 ASN 库，您必须有 IBM InfoSphere Data Replication (IIDR)的许可证。您不必安装 IIDR 来使用 ASN 库。
使用 Debezium Db2 连接器的信息和流程组织如下：
- 第 2.1.1 节 “Debezium Db2 连接器概述”
- 第 2.1.2 节 “Debezium Db2 连接器的工作方式”
- 第 2.1.3 节 “Debezium Db2 连接器数据更改事件的描述”
- 第 2.1.4 节 “Debezium Db2 连接器如何映射数据类型”
- 第 2.1.5 节 “设置 Db2 以运行 Debezium 连接器”
- 第 2.1.6 节 “部署 Debezium Db2 连接器”
- 第 2.1.7 节 “监控 Debezium Db2 连接器性能”
- 第 2.1.8 节 “管理 Debezium Db2 连接器”
- 第 2.1.9 节 “在 Debezium 连接器的捕获模式中更新 Db2 表的模式”
2.1.1. Debezium Db2 连接器概述
Debezium Db2 连接器基于 ASN Capture/Apply 代理，该代理在 Db2 中启用 SQL Replication。捕获代理：
- 为处于捕获模式的表生成 change-data 表。
- 以捕获模式监控表，并在对应的 change-data 表中存储对这些表的更新更改事件。
Debezium 连接器使用 SQL 接口来查询 change-data 表来更改事件。
数据库管理员必须将您要捕获更改的表放在捕获模式中。为了方便和进行自动测试，在 C 中提供了 Debezium 用户定义的功能(UDF)，您可以编译它们，然后使用 进行以下管理任务：
- 启动、停止和重新初始化 ASN 代理
- 将表置于捕获模式
- 创建复制(ASN)模式和更改数据表
- 从捕获模式中删除表
或者，您可以使用 Db2 控制命令来完成这些任务。
在感兴趣的表处于捕获模式后，连接器会读取对应的 change-data 表，以获取表更新的更改事件。连接器会向 Kafka 主题发出与更改表相同的行级插入、更新和删除操作的更改事件。这是您可以修改的默认行为。客户端应用程序读取与感兴趣的数据库表对应的 Kafka 主题，并可对每个行级更改事件做出反应。
通常，数据库管理员会在表的生命周期内将表置于捕获模式下。这意味着连接器没有对表所做的任何更改的完整历史记录。因此，当 Db2 连接器首先连接到特定的 Db2 数据库时，它会首先为处于捕获模式的每个表执行 一致的快照。连接器完成快照后，连接器流会从创建快照的时间点更改事件。这样，连接器从处于捕获模式的表的一致视图开始，且不会丢弃执行快照时所做的任何更改。
Debezium 连接器可以接受故障。当连接器读取并生成更改事件时，它会记录 change-data 表条目的日志序列号(LSN)。LSN 是数据库日志中更改事件的位置。如果连接器因任何原因而停止，包括通信失败、网络问题或崩溃，它会继续读取其关闭的 change-data 表。这包括快照。也就是说，如果快照在连接器停止时没有完成，重启连接器会启动新快照。
2.1.2. Debezium Db2 连接器的工作方式
要优化地配置和运行 Debezium Db2 连接器，了解连接器如何执行快照、流更改事件、决定 Kafka 主题名称以及处理 schema 更改非常有用。
详情包括在以下主题中：
2.1.2.1. Debezium Db2 连接器如何执行数据库快照
Db2 的复制功能不是旨在存储数据库更改的完整历史记录。因此，Debezium Db2 连接器无法从日志中检索数据库的完整历史记录。要让连接器为数据库的当前状态建立基准，连接器首次启动时，它会执行处于 捕获模式 的表的初始 一致快照。对于快照捕获的每个更改，连接器会向捕获的表发出 读取 事件。
您可以在以下部分中找到有关快照的更多信息：
2.1.2.1.1. Debezium Db2 连接器用于执行初始快照的默认工作流
以下工作流列出了 Debezium 创建快照的步骤。这些步骤描述了当 snapshot.mode 配置属性设置为默认值时快照的进程，这是 初始。您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。如果您配置不同的快照模式，连接器使用此工作流的修改版本完成快照。
- 建立与数据库的连接。
-
确定哪些表处于捕获模式，并且应包含在快照中。默认情况下，连接器捕获所有非系统表的数据。快照完成后，连接器将继续流传输指定表的数据。如果您希望连接器只从特定表捕获数据，您可以通过设置
table.include.list或table.exclude.list等属性来仅捕获表或表元素的子集的数据。 -
在捕获模式下的每个表上获取锁定。这个锁定可确保在快照完成前，这些表中不会发生架构更改。锁定的级别由
snapshot.isolation.mode连接器配置属性决定。 - 阅读服务器事务日志中的最大（最近）LSN 位置。
捕获所有表或指定用于捕获的所有表的模式。连接器在其内部数据库模式历史记录主题中保留 schema 信息。架构历史记录提供有关发生更改事件时所生效的结构的信息。
注意默认情况下，连接器捕获数据库中处于捕获模式的每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。
有关您在初始快照中没有包括快照持久模式信息的更多信息，请参阅 了解为什么初始快照捕获所有表的 schema。
- 释放第 3 步中获取的所有锁定。其他数据库客户端现在可以写入任何之前锁定的表。
在第 4 步读取的 LSN 位置，连接器会扫描指定为捕获的表。在扫描过程中，连接器完成以下任务：
- 确认表已在快照开始之前创建。如果在快照开始后创建了表，连接器会跳过该表。快照完成后，连接器过渡到 streaming，它会为快照开始后创建的任何表发出更改事件。
-
为从表中捕获的每行生成一个
读取事件。所有读取事件都包含相同的 LSN 位置，这是在第 4 步中获取的 LSN 位置。 -
向源表的 Kafka 主题发出每个
读取事件。 - 释放数据表锁定（如果适用）。
- 在连接器偏移中记录快照成功完成。
生成的初始快照会捕获捕获表中每行的当前状态。在这个基准状态中，连接器会捕获后续更改。
在快照过程开始后，如果进程因为连接器失败、重新平衡或其他原因而中断，进程会在连接器重启后重启。
连接器完成初始快照后，它会从第 4 步中读取的位置继续流传输，以便它不会丢失任何更新。
如果连接器因任何原因再次停止，它会在重启后恢复流更改，从之前离开的位置恢复流更改。
| 设置 | 描述 |
|---|---|
|
| 连接器在每次启动时都执行快照。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照，如用于创建初始快照的默认工作流 中所述。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照。快照完成后，连接器会停止，且不会为后续数据库更改流传输事件记录。 |
|
|
弃用，请参阅 |
|
|
连接器捕获所有相关表的结构，执行 默认快照工作流 中描述的所有步骤，但它没有创建 |
|
| 设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。 警告 如果在上次连接器关闭后将 schema 更改提交到数据库，则不要使用此模式执行快照。 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
如需更多信息，请参阅连接器配置属性表中的 snapshot.mode。
2.1.2.1.2. 有关初始快照捕获所有表的 schema 历史记录的描述
连接器运行的初始快照捕获两种类型的信息：
- 表数据
-
有关
INSERT、UPDATE和DELETE操作的信息，它们在连接器的table.include.list属性中命名。 - 模式数据
- 描述应用到表的结构更改的 DDL 语句。如果配置了 schema 数据，则 schema 数据会被保留到内部模式历史记录主题，以及连接器的 schema 更改主题。
运行初始快照后，您可能会注意到快照捕获了未指定用于捕获的表的模式信息。默认情况下，初始快照旨在捕获数据库中存在的每个表的模式信息，而不仅限于为捕获指定的表。连接器要求表的 schema 在捕获表之前存在于 schema 历史记录主题中。通过启用初始快照来捕获不属于原始捕获集的表，Debezium 准备连接器，以便稍后需要从这些表中读取事件数据。如果初始快照没有捕获表的模式，您必须将 schema 添加到历史记录主题，然后才能从表中捕获数据。
在某些情况下，您可能想要限制初始快照中的模式捕获。当您要减少完成快照所需的时间时，这非常有用。或者，当 Debezium 通过有权访问多个逻辑数据库的用户帐户连接到数据库实例时，但您希望连接器只从特定逻辑数据库中的表捕获更改。
其他信息
- 从初始快照未捕获的表中捕获数据（无模式更改）
- 从没有由初始快照捕获的表捕获数据(schema 更改)
-
设置
schema.history.internal.store.only.captured.tables.ddl属性，以指定要从中捕获模式信息的表。 -
设置
schema.history.internal.store.only.captured.databases.ddl属性，以指定捕获模式更改的逻辑数据库。
2.1.2.1.3. 从初始快照未捕获的表中捕获数据（无模式更改）
在某些情况下，您可能希望连接器从最初快照未捕获其 schema 的表中捕获数据。根据连接器配置，初始快照可能会只捕获数据库中特定表的表模式。如果历史记录主题中没有表模式，连接器无法捕获表，并报告缺少的 schema 错误。
您可能仍然能够从表中捕获数据，但您必须执行额外的步骤来添加表模式。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 在连接器读取的最新更改表条目的 LSNs 和最新的更改表条目之间的表中不会应用架构更改。有关从具有结构化更改的新表捕获数据的详情，请参考 第 2.1.2.1.4 节 “从没有由初始快照捕获的表捕获数据(schema 更改)”。
流程
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
将以下更改应用到连接器配置：
（可选）将
schema.history.internal.captured.tables.ddl的值设置为false。此设置会导致快照捕获所有表的模式，并保证将来，连接器可以重建所有表的 schema 历史记录。
注意捕获所有表的模式的快照需要更多时间完成。
-
添加您希望连接器捕获到
table.include.list的表。 将
snapshot.mode设置为以下值之一：Initial-
重启连接器时，它会获取获取表数据和表结构的完整数据库快照。
如果您选择这个选项，请考虑将schema.history.internal.captured.tables.ddl属性的值设置为false，以便连接器捕获所有表的 schema。 schema_only- 重启连接器时，它会使用一个只捕获表模式的快照。与完整数据快照不同，此选项不会捕获任何表数据。如果要比使用完整快照更快重启连接器，请使用这个选项。
-
重启连接器。连接器完成
snapshot.mode指定的快照类型。 （可选）如果连接器在快照完成后执行
schema_only快照，启动 增量快照 以从您添加的表中捕获数据。连接器在继续从表中实时更改时运行快照。运行增量快照会捕获以下数据更改：- 对于之前捕获的连接器的表，增量 snapsot 捕获连接器停机期间发生的更改，即连接器停止的时间和当前重启之间的间隔。
- 对于新添加的表，增量快照会捕获所有现有表行。
2.1.2.1.4. 从没有由初始快照捕获的表捕获数据(schema 更改)
如果将架构更改应用到表，则在架构更改前提交的记录与更改后提交的结构不同。当 Debezium 捕获表中的数据时，它会读取 schema 历史记录，以确保它将正确的模式应用到每个事件。如果 schema 历史记录主题中没有 schema，连接器将无法捕获表，并会产生错误结果。
如果要捕获初始快照未捕获的表中的数据，并修改了表的 schema，您必须将 schema 添加到历史记录主题（如果还没有可用）。您可以通过运行新的模式快照或运行表的初始快照来添加架构。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 对表应用了一个架构更改，因此要捕获的记录没有统一的结构。
流程
- 初始快照捕获了所有表的模式(
storage.only.captured.tables.ddl设置为false) -
编辑
table.include.list属性，以指定您要捕获的表。 - 重启连接器。
- 如果要从新添加的表中捕获现有数据，则启动 增量快照。
-
编辑
- 初始快照没有捕获所有表的模式(storage
.only.captured.tables.ddl设置为true) 如果初始快照没有保存您要捕获的表的模式，请完成以下步骤之一：
- 流程 1：Schema 快照，后跟增量快照
在此过程中，连接器首先执行 schema 快照。然后，您可以启动增量快照，使连接器能够同步数据。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为schema_only。 -
编辑
table.include.list以添加您要捕获的表。
-
将
- 重启连接器。
- 等待 Debezium 捕获新表和现有表的模式。连接器停止后发生的数据更改不会被捕获。
- 为确保没有数据丢失，可启动 增量快照。
- 流程 2：初始快照，后跟可选的增量快照
在此过程中，连接器执行数据库的完整初始快照。与任何初始快照一样，在具有许多大表的数据库中，运行初始快照可能是一个耗时的操作。快照完成后，您可以选择性地触发增量快照，以捕获连接器离线期间发生的任何更改。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
-
编辑
table.include.list以添加您要捕获的表。 为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为initial。 -
（可选）将
schema.history.internal.store.only.captured.tables.ddl设置为false。
-
将
- 重启连接器。连接器使用完整的数据库快照。快照完成后，连接器会过渡到 streaming。
- （可选）要捕获连接器脱机时更改的任何数据，请启动 增量快照。
2.1.2.2. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供总结表数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改为捕获不同的表集合。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号表。您可以通过向 Debezium 信号表发送信号请求来启动临时快照。
当您启动现有表的临时快照时，连接器会将内容附加到表已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的表。快照可以捕获数据库的全部内容，或者仅捕获数据库中表的子集。此外，快照也可捕获数据库中表的内容的子集。
您可以通过向信号表发送 execute-snapshot 消息来指定要捕获的表。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的表名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| 不适用 |
包含与快照中包含的表的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作表的主键的列名称。 |
触发临时增量快照
您可以通过向信号表添加带有 execute-snapshot 信号类型的条目，或者向 Kafka 信号发送信号消息 来启动临时增量快照。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个表的开始和端点。根据表中的条目数量以及配置的块大小，Debezium 会将表分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号表或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.1.2.3. 增量快照
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个表。您可以指定您希望快照捕获的表 以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debezium 使用水位线来跟踪其进度，维护其捕获的每个表行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获表。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，以将表添加到其
table.include.list属性中。
增量快照过程
当您运行增量快照时，Debezium 按主密钥对每个表进行排序，然后根据 配置的块大小 将表分成块。通过块工作的块，然后捕获块中的每个表行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改表记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获了包含该行的 READ 事件前修改表行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一表行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定表块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到表的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
Db2 的 Debezium 连接器不支持增量快照运行时的 schema 更改。
2.1.2.3.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号表。您可以提交快照信号，作为 SQL INSERT 查询。
在 Debezium 检测到信号表中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的表，并可选择性地指定快照操作的类型。Debezium 目前支持 增量 和 阻塞 快照类型。
要指定要包含在快照中的表，提供一个列出表的 data-collections 数组，或用于匹配表的正则表达式数组，例如：
{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会解释空数组，意味着不需要任何操作，且不会执行快照。
如果要包含在快照中的表的名称包含一个点(.)、空格或其它非字母数字字符，则必须使用双引号转义表名称。
例如，要包含 公共 模式中存在的表，并且名为 My.Table，请使用以下格式 ："public.\"My.Table\" "。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
发送 SQL 查询，将临时增量快照请求添加到信号表中：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、type和data参数的值 与信号表的字段 相对应。
下表描述了示例中的参数：Expand 表 2.3. SQL 命令中的字段描述，用于将增量快照信号发送到信号表 项 值 描述 1
schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshottype参数指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定表名称或正则表达式数组，以匹配快照中包含的表名称。
数组列出了使用格式schema.table的正则表达式，以匹配表的完全限定名称。此格式与您用来指定连接器 信号表的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
有效值为incremental和blocking值。
如果没有指定值，连接器默认为执行增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
每个额外条件都是带有data-collection和filter属性的对象。您可以为每个数据收集指定不同的过滤器。
请参阅data-collection属性是过滤器应用到的数据收集的完全限定域名。有关additional-conditions参数的详情，请参考 第 2.1.2.3.2 节 “使用附加条件运行临时增量快照”。
2.1.2.3.2. 使用附加 条件运行临时增量快照
如果您希望快照只在表中包括内容子集，您可以通过将 additional-conditions 参数附加到快照信号来修改信号请求。
对典型快照的 SQL 查询采用以下格式：
SELECT * FROM <tableName> ....
SELECT * FROM <tableName> ....
通过添加 additional-conditions 参数，您可以在 SQL 查询中附加 WHERE 条件，如下例所示：
SELECT * FROM <data-collection> WHERE <filter> ....
SELECT * FROM <data-collection> WHERE <filter> ....以下示例显示了向信号表发送带有额外条件的临时增量快照请求的 SQL 查询：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
例如，假设您有一个包含以下列的 products 表：
-
ID（主密钥） -
color -
quantity
如果您需要 product 表的增量快照，其中只包含 color=blue 的数据项，您可以使用以下 SQL 语句来触发快照：
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue"}]}');
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue"}]}');
additional-conditions 参数还允许您传递基于多个列的条件。例如，使用上例中的 product 表，您可以提交查询来触发增量快照，该快照仅包含 color=blue 和 quantity>10 的项数据：
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue AND quantity>10"}]}');
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue AND quantity>10"}]}');以下示例显示了连接器捕获的增量快照事件的 JSON。
例 2.1. 增量快照事件消息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.1.2.3.3. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.2. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择表内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果一个带有列 ID （主键）、颜色 和品牌 的 products 表，如果您希望快照只包含 color='blue' 的内容，当请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 product 表，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的 表中的内容，您可以发送以下请求：
products
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.1.2.3.4. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的信号发送信号来停止已经运行的快照。
您可以通过在 SQL INSERT 查询中发送停止快照信号，向信号表提交停止快照信号。stop-snapshot 信号将快照操作的类型指定为 增量，并选择性地指定要从当前运行的快照中省略的表。在 Debezium 检测到信号表中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
发送 SQL 查询以停止临时增量快照到信号表：
INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
INSERT INTO myschema.debezium_signal (id, type, data) values ('ad-hoc-1', 'stop-snapshot', '{"data-collections": ["schema1.table1", "schema1.table2"], "type":"incremental"}');INSERT INTO myschema.debezium_signal (id, type, data)1 values ('ad-hoc-1',2 'stop-snapshot',3 '{"data-collections": ["schema1.table1", "schema1.table2"],4 "type":"incremental"}');5 Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号表的字段相对应。
下表描述了示例中的参数：Expand 表 2.6. SQL 命令中的字段描述，用于将停止增量快照信号发送到信号表 项 值 描述 1
schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。3
stop-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定表名称或正则表达式数组，以匹配要从快照中删除的表名称。
数组以schema.table格式按完全限定名称匹配表的正则表达式如果您从
data字段省略这个组件，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.1.2.3.5. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，表名称或正则表达式，以匹配要从快照中删除的表名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["schema1.table1", "schema1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["schema1.table1", "schema1.table2"], "type": "INCREMENTAL"}}`2.1.2.4. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新表，并在连接器运行时完成快照。
- 您可以添加大表，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个表必须是快照
additional-conditions ：您可以为不同的表指定不同的过滤器。
-
data-collection属性是要应用过滤器的表的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.1.2.5. Debezium Db2 连接器如何读取更改数据表
完成快照后，当 Debezium Db2 连接器首次启动时，连接器会标识处于捕获模式的每个源表的 change-data 表。连接器会为每个 change-data 表执行以下操作：
- 读取在上一次存储、最高 LSN 和当前最高 LSN 之间创建的更改事件。
- 根据提交 LSN 和每个事件的更改 LSN 订购更改事件。这样可确保连接器按表更改的顺序发出更改事件。
- 将提交并更改 LSNs 作为偏移到 Kafka Connect。
- 存储连接器传递给 Kafka Connect 的最高 LSN。
重启后，连接器会从偏移（提交并更改其保留的 LSN）中恢复更改事件。虽然连接器正在运行并发出更改事件，如果您从捕获模式中删除表，或将表添加到捕获模式，连接器会检测到更改，并相应地修改其行为。
2.1.2.6. 接收 Debezium Db2 更改事件记录的 Kafka 主题的默认名称
默认情况下，Db2 连接器将所有 INSERT、UPDATE 和 DELETE 操作的更改事件写入一个特定于该表的单一 Apache Kafka 主题。连接器使用以下惯例命名更改事件主题：
topicPrefix.schemaName.tableName
以下列表提供了默认名称组件的定义：
- topicPrefix
-
由
topic.prefix连接器配置属性指定的主题前缀。 - schemaName
- 发生操作的模式的名称。
- tableName
- 操作发生的表的名称。
例如，一个使用 mydatabase 数据库的 Db2 安装，其中包含四个表：PRODUCTS, PRODUCTS_ON_HAND, CUSTOMERS, 和 ORDERS，它们包括在 MYSCHEMA schema 中。连接器会将事件发送到这四个 Kafka 主题：
-
mydatabase.MYSCHEMA.PRODUCTS -
mydatabase.MYSCHEMA.PRODUCTS_ON_HAND -
mydatabase.MYSCHEMA.CUSTOMERS -
mydatabase.MYSCHEMA.ORDERS
连接器应用类似的命名约定来标记其内部数据库架构历史记录主题、架构更改主题 和事务元数据主题。
如果默认主题名称不满足您的要求，您可以配置自定义主题名称。要配置自定义主题名称，您可以在逻辑主题路由 SMT 中指定正则表达式。有关使用逻辑主题路由 SMT 自定义主题命名的更多信息，请参阅 主题路由。
2.1.2.7. Debezium Db2 连接器如何处理数据库架构更改
当数据库客户端查询数据库时，客户端将使用数据库的当前架构。但是，可以随时更改数据库架构，这意味着连接器必须能够识别每次插入、更新或删除操作时的 schema。另外，连接器不一定将当前模式应用到每个事件。如果事件相对旧，则在应用当前模式之前记录这些事件。
为确保在 schema 更改后处理事件，Debezium Db2 连接器根据 Db2 更改数据表的结构存储新模式的快照，该表镜像其关联的数据表的结构。连接器在数据库 schema 历史记录 Kafka 主题中存储表 schema 信息，以及操作的 LSN。连接器使用存储的模式表示来生成更改事件，每次插入、更新或删除操作时都会正确镜像表结构。
当连接器在崩溃或安全停止后重启时，它会从读取的最后一个位置恢复 Db2 更改数据表中的条目。根据连接器从数据库模式历史记录主题读取的架构信息，连接器应用在连接器重启的位置中存在的表结构。
如果您更新处于捕获模式的 Db2 表的 schema，您也可以更新相应更改表的 schema。您必须是一个具有升级权限的 Db2 数据库管理员，才能更新数据库架构。有关如何在 Debezium 环境中更新 Db2 数据库模式的更多信息，请参阅 架构历史记录传递。
数据库架构历史记录主题仅用于内部连接器。另外，连接器也可以将 schema 更改事件发送到面向消费者应用程序的不同主题。
其他资源
- 接收 Debezium 事件记录 的主题的默认名称。
2.1.2.8. 关于 Debezium Db2 连接器模式更改主题
您可以配置 Debezium Db2 连接器来生成模式更改事件，以描述应用到数据库中表的 schema 更改。
在以下情况下，Debezium 会向 schema 更改主题发送一条消息：
- 新表进入捕获模式。
- 表已从捕获模式中删除。
- 在 数据库架构更新过程中，处于捕获模式的表的 schema 发生了变化。
连接器将 schema 更改事件写入 Kafka schema 更改主题，其名称为 < topicPrefix>，其中 < ;topicPrefix > 是 topic.prefix 连接器配置属性中指定的主题前缀。
模式更改事件的 schema 具有以下元素：
名称- 模式更改事件消息的名称。
type- 更改事件消息的类型。
version- 架构的版本。version 是一个整数，每次更改 schema 时都会递增。
fields- 更改事件消息中包含的字段。
示例： Db2 连接器架构更改主题的 Schema
以下示例显示了 JSON 格式的典型模式。
连接器发送到 schema 更改主题的消息包含一个有效负载，其中包含以下元素：
databaseName-
将语句应用到的数据库的名称。
databaseName的值充当 message 键。 pos- 声明出现在事务日志中的位置。
tableChanges-
架构更改后整个表模式的结构化表示。
tableChanges字段包含一个数组，其中包含表的每列条目。由于结构化表示以 JSON 或 Avro 格式显示数据，因此用户可以轻松地读取消息，而无需首先通过 DDL 解析器处理它们。
对于处于捕获模式的表，连接器不仅将模式更改的历史记录存储在 schema 更改主题中，还要存储在内部数据库架构历史记录主题中。内部数据库架构历史记录主题仅用于连接器，它不用于直接使用应用程序。确保需要针对 schema 更改通知的应用程序只消耗了来自 schema 更改主题的信息。
永不对数据库 schema 历史记录主题进行分区。要使数据库架构历史记录主题正常工作，它必须保持一致的全局顺序，连接器向其发送的事件记录。
要确保主题不在分区中分割，请使用以下方法之一为主题设置分区计数：
-
如果您手动创建数据库架构历史记录主题，请指定分区计数
1。 -
如果您使用 Apache Kafka 代理自动创建数据库模式历史记录主题，则会创建主题，将 Kafka
num.partitions配置选项 的值设置为1。
连接器发送到其 schema 更改主题的消息格式处于 inubating 状态，并可在不通知的情况下更改。
示例：向 Db2 连接器模式更改主题的消息发送
以下示例显示了 schema 更改主题中的消息。消息包含表 schema 的逻辑表示。
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 在源对象中，ts_ms 表示更改在数据库中的时间。通过将 payload.source.ts_ms 的值与 payload.ts_ms 的值进行比较，您可以确定源数据库更新和 Debezium 之间的滞后。 |
| 2 |
| 标识包含更改的数据库和模式。 |
| 3 |
|
对于 Db2 连接器，始终为 |
| 4 |
| 包含 DDL 命令生成的架构更改的一个或多个项目的数组。 |
| 5 |
| 描述更改类型。该值是以下之一：
|
| 6 |
| 创建、更改或丢弃的表的完整标识符。 |
| 7 |
| 代表应用的更改后的表元数据。 |
| 8 |
| 编写表主键的列列表。 |
| 9 |
| changed 表中每个列的元数据。 |
| 10 |
| 每个表更改的自定义属性元数据。 |
在连接器发送到 schema 更改主题的消息中，message 键是包含 schema 更改的数据库的名称。在以下示例中，payload 字段包含键：
2.1.2.9. Debezium Db2 连接器生成的事件代表事务边界
Debezium 可以生成代表事务边界的事件，以及丰富的更改数据事件消息。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
Debezium 为每个事务中的 BEGIN 和 END 分隔符生成事务边界事件。事务边界事件包含以下字段：
status-
BEGIN或END. id- 唯一事务标识符的字符串表示。
ts_ms-
数据源的事务边界事件(
BEGIN或END事件)的时间。如果数据源没有向 Debezium 提供事件时间，则字段代表 Debezium 处理事件的时间。 event_count（用于END事件）- 事务处理的事件总数。
data_collections（用于END事件）-
一组
data_collection和event_count元素，用于指示连接器为来自数据收集的更改发出的事件数。
示例
除非通过 topic.transaction 选项覆盖，否则连接器会将事务事件发送到 < topic.prefix>.transaction 主题。
数据更改事件增强
当启用事务元数据时，连接器使用新的 transaction 字段增强更改事件 Envelope。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示。
total_order- 事件在事务生成的所有事件间的绝对位置。
data_collection_order- 事件在事务发送的所有事件中的每个数据收集位置。
以下是消息示例：
2.1.3. Debezium Db2 连接器数据更改事件的描述
Debezium Db2 连接器为每个行级 INSERT、UPDATE 和 DELETE 操作生成数据更改事件。每个事件包含一个键和值。键和值的结构取决于更改的表。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，用户很难处理。要解决这个问题，每个事件都包含其内容的 schema，或者如果您使用 schema registry，消费者可以用来从 registry 获取 schema 的模式 ID。这使得每个事件自包含。
以下框架 JSON 显示了更改事件的基本四部分。但是，如何配置您选择在应用程序中使用的 Kafka Connect 转换器决定了更改事件中的这四个部分的表示。只有在将转换器配置为生成它时，schema 字段才会处于 change 事件中。同样，只有在将转换器配置为生成它时，事件键和事件有效负载才会处于更改事件中。如果您使用 JSON 转换程序，并将其配置为生成所有四个基本更改事件部分，则更改事件具有此结构：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
第一个 |
| 2 |
|
第一个 |
| 3 |
|
第二个 |
| 4 |
|
第二个 |
默认情况下，连接器流将事件记录改为带有与事件原始表相同的名称的主题。如需更多信息，请参阅 主题名称。
Debezium Db2 连接器确保所有 Kafka Connect 模式名称都遵循 Avro 模式名称格式。这意味着逻辑服务器名称必须以拉丁字母或下划线开头，即 a-z、A-Z 或 _。逻辑服务器名称和表名称中的每个字符都必须是拉丁字母、数字或下划线，即 a-z、A-Z、0-9 或 \_。如果存在无效的字符，它将被一个下划线字符替代。
如果逻辑服务器名称、数据库名称或表名称包含无效字符，则这可能会导致意外冲突，并且区分名称的唯一字符无效，因此用下划线替换。
另外，数据库、模式和表的 Db2 名称可能区分大小写。这意味着连接器可能会向同一 Kafka 主题发出多个表的事件记录。
详情包括在以下主题中：
2.1.3.1. 关于 Debezium db2 更改事件中的键
更改事件的密钥包含更改表键和更改行的实际键的 schema。在连接器创建事件时，schema 及其对应有效负载都包含更改表的 PRIMARY KEY （或唯一约束）中每个列的字段。
请考虑以下 customers 表，后面是此表的更改事件关键示例。
表示例
更改事件键示例
捕获 customer 表更改的每个更改事件都有相同的事件关键模式。只要 customers 表有以前的定义，可以捕获 customer 表更改的事件都有以下关键结构：在 JSON 中，类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
键的 schema 部分指定一个 Kafka Connect 模式，它描述了键的 |
| 2 |
|
指定 |
| 3 |
|
指明事件键是否在其 |
| 4 |
|
定义键有效负载结构的 schema 名称。这个模式描述了更改的表的主密钥的结构。Key 模式名称的格式是 connector-name.database-name.table-name.
|
| 5 |
|
包含生成此更改事件的行的密钥。在本例中，键包含一个 |
2.1.3.2. 关于 Debezium Db2 更改事件中的值
更改事件中的值比键复杂一些。与键一样，值也有一个 schema 部分和一个 payload 部分。schema 部分包含描述 payload 部分的 Envelope 结构的 schema，包括其嵌套字段。更改创建、更新或删除数据的操作的事件，它们都有带有 envelope 结构的值 payload。
考虑用于显示更改事件键示例相同的示例表：
表示例
customers 表的每个更改事件的 event value 部分指定相同的模式。事件值的有效负载因事件类型而异：
创建 事件
以下示例显示了一个更改事件的值部分，连接器为在 customer 表中创建数据的操作生成的更改事件的值部分：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 值的 schema，它描述了值有效负载的结构。在连接器为特定表生成的更改事件时，更改事件的值 schema 都相同。 |
| 2 |
|
在 |
| 3 |
|
|
| 4 |
|
|
| 5 |
|
值的实际数据。这是更改事件提供的信息。 |
| 6 |
|
指定事件发生前行状态的可选字段。当 |
| 7 |
|
指定事件发生后行状态的可选字段。在本例中， |
| 8 |
|
描述事件源元数据的强制字段。
|
| 9 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中，
|
| 10 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新 事件
示例 customers 表中一个更新的改变事件的值有与那个表的 create 事件相同的模式。同样，update 事件值的有效负载具有相同的结构。但是，事件值 payload 在更新 事件中包含不同的值。以下是当连接器在 customers 表中为更新生成的更改事件值的示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行状态的可选字段。在 update 事件值中， |
| 2 |
|
指定事件发生后行状态的可选字段。您可以比较 |
| 3 |
|
描述事件源元数据的强制字段。
|
| 4 |
|
描述操作类型的强制字符串。在 update 事件值中， |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新行主/唯一键的列会更改行键的值。当密钥更改时，Debezium 会输出 三个 事件：一个 DELETE 事件和一个带有行的旧键的 tombstone 事件，后跟一行的新键的事件。
删除 事件
delete 更改事件中的值与为同一表的 create 和 update 事件相同的 schema 部分。示例 customer 表的 delete 事件中的事件值 payload 类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行的状态的可选字段。在一个 delete 事件值中， |
| 2 |
|
可选字段，用于指定事件发生后行的状态。在一个 delete 事件值中， |
| 3 |
|
描述事件源元数据的强制字段。在一个 delete 事件值中，
|
| 4 |
|
描述操作类型的强制字符串。 |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
删除 更改事件记录为消费者提供处理删除此行所需的信息。包含了旧值，因为有些用户可能需要它们才能正确处理删除。
Db2 连接器事件设计为与 Kafka 日志压缩 一起工作。日志压缩支持删除一些旧的信息，只要至少保留每个密钥的最新消息。这可让 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
删除行时，delete 事件值仍可用于日志压缩，因为 Kafka 您可以删除具有相同键的所有之前信息。但是，为了使 Kafka 删除具有相同键的所有信息，消息值必须是 null。为了实现此目的，在 Debezium 的 Db2 连接器发出 delete 事件后，连接器会发出一个特殊的 tombstone 事件，它具有相同的键有一个 null 值 。
2.1.4. Debezium Db2 连接器如何映射数据类型
有关 Db2 支持的数据类型的完整描述，请参阅 Db2 文档中的 数据类型。
Db2 连接器代表对带有类似行表的事件行的更改。事件包含每个列值的一个字段。事件中的该值取决于列的 Db2 数据类型。本节描述了这些映射。如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。
详情包括在以下部分中：
基本类型
下表描述了连接器如何将每个 Db2 数据类型映射到事件 字段中的字面 类型和语义类型。
-
literal type 描述如何使用 Kafka Connect 模式类型来表示值：
INT8,INT16,INT32,INT64,FLOAT32,FLOAT64,BOOLEAN,STRING,BYTES,ARRAY, MAP ,MAP, 和STRUCT. - 语义类型 描述了 Kafka Connect 模式如何使用字段名称来捕获字段 的含义。
| Db2 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
| 只有具有 BOOLEAN 类型列的表才能获取快照。目前，Db2 上的 SQL Replication 不支持 BOOLEAN，因此 Debezium 无法在这些表中执行 CDC。考虑使用不同的类型。 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
|
|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
如果存在，则列的默认值将传播到对应的字段 Kafka Connect 模式。更改事件包含字段的默认值，除非给出了显式列值。因此，很少需要从 schema 获取默认值。
临时类型
除了 DATETIMEOFFSET 数据类型，其中包含时区信息，Db2 根据 time.precision.mode 连接器配置属性的值映射 temporal 类型。以下小节描述了这些映射：
time.precision.mode=adaptive
当 time.precision.mode 配置属性设置为 自适应 性时，默认连接器根据列的数据类型定义决定字面类型和语义类型。这样可确保事件 准确 表示数据库中的值。
| Db2 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
time.precision.mode=connect
当 time.precision.mode 配置属性设置为 connect 时，连接器使用 Kafka Connect 逻辑类型。当消费者只能处理内置的 Kafka Connect 逻辑类型，且无法处理变量精度时间值时，这很有用。但是，因为 Db2 支持十分之一微秒的精度，使用 connect 时间精度的连接器会在数据库列带有 fractional second precision 值大于 3 时，导致精度下降。
| Db2 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
时间戳类型
DATETIME 类型代表一个没有时区信息的时间戳。这些列根据 UTC 转换为等同的 Kafka Connect 值。例如，DATETIME 值 "2018-06-20 15:13:16.945104" 由一个带有值 "1529507596000" 的 io.debezium.time.Timestamp 代表。
运行 Kafka Connect 和 Debezium 的 JVM 时区不会影响此转换。
| Db2 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
2.1.5. 设置 Db2 以运行 Debezium 连接器
要使 Debezium 捕获提交 Db2 表的更改事件，具有所需特权的 Db2 数据库管理员必须在数据库中配置表以更改数据捕获。开始运行 Debezium 后，您可以调整捕获代理的配置以优化性能。
有关设置用于 Debezium 连接器的 Db2 的详情，请参考以下部分：
2.1.5.1. 为更改数据捕获配置 Db2 表
要将表置于捕获模式，Debezium 提供了一组用户定义的功能(UDF)。此处的步骤演示了如何安装和运行这些管理 UDF。或者，您可以运行 Db2 控制命令将表置于捕获模式中。然后，管理员必须为您希望 Debezium 捕获的每个表启用 CDC。
先决条件
-
以
db2instl用户身份登录 Db2。 - 在 Db2 主机上，Debezium 管理 UDF 在 $HOME/asncdctools/src 目录中提供。UDF 在 Debezium 示例存储库 中提供。
-
Db2 命令
bldrtn位于 PATH 上，例如，通过运行export PATH=$PATH:/opt/ibm/db2/V11.5.0.0/samples/c/with Db2 11.5
流程
使用 Db2 提供的
bldrtn命令在 Db2 服务器主机上编译 Debezium 管理 UDF：cd $HOME/asncdctools/src
cd $HOME/asncdctools/srcCopy to Clipboard Copied! Toggle word wrap Toggle overflow bldrtn asncdc
bldrtn asncdcCopy to Clipboard Copied! Toggle word wrap Toggle overflow 启动数据库（如果尚未运行）。将
DB_NAME替换为您要 Debezium 连接到的数据库的名称。db2 start db DB_NAME
db2 start db DB_NAMECopy to Clipboard Copied! Toggle word wrap Toggle overflow 确保 JDBC 可以读取 Db2 元数据目录：
cd $HOME/sqllib/bnd
cd $HOME/sqllib/bndCopy to Clipboard Copied! Toggle word wrap Toggle overflow db2 connect to DB_NAME db2 bind db2schema.bnd blocking all grant public sqlerror continue
db2 connect to DB_NAME db2 bind db2schema.bnd blocking all grant public sqlerror continueCopy to Clipboard Copied! Toggle word wrap Toggle overflow 确保数据库最近备份。ASN 代理必须具有要从中读取的最新起点。如果您需要执行备份，请运行以下命令来修剪数据，以便只有最新版本可用。如果您不需要保留旧版本数据，请为备份位置指定
dev/null。备份数据库。将
DB_NAME和BACK_UP_LOCATION替换为适当的值：db2 backup db DB_NAME to BACK_UP_LOCATION
db2 backup db DB_NAME to BACK_UP_LOCATIONCopy to Clipboard Copied! Toggle word wrap Toggle overflow 重启数据库：
db2 restart db DB_NAME
db2 restart db DB_NAMECopy to Clipboard Copied! Toggle word wrap Toggle overflow
连接到数据库，以安装 Debezium 管理 UDF。假设您以
db2instl用户身份登录，因此应在db2inst1用户上安装 UDF。db2 connect to DB_NAME
db2 connect to DB_NAMECopy to Clipboard Copied! Toggle word wrap Toggle overflow 复制 Debezium 管理 UDF 并为它们设置权限：
cp $HOME/asncdctools/src/asncdc $HOME/sqllib/function
cp $HOME/asncdctools/src/asncdc $HOME/sqllib/functionCopy to Clipboard Copied! Toggle word wrap Toggle overflow chmod 777 $HOME/sqllib/function
chmod 777 $HOME/sqllib/functionCopy to Clipboard Copied! Toggle word wrap Toggle overflow 启用 Debezium UDF，以启动和停止 ASN 捕获代理：
db2 -tvmf $HOME/asncdctools/src/asncdc_UDF.sql
db2 -tvmf $HOME/asncdctools/src/asncdc_UDF.sqlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建 ASN 控制表：
db2 -tvmf $HOME/asncdctools/src/asncdctables.sql
$ db2 -tvmf $HOME/asncdctools/src/asncdctables.sqlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 启用 Debezium UDF，添加表以捕获模式并从捕获模式中删除表：
db2 -tvmf $HOME/asncdctools/src/asncdcaddremove.sql
$ db2 -tvmf $HOME/asncdctools/src/asncdcaddremove.sqlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 设置 Db2 服务器后，使用 UDF 通过 SQL 命令控制 Db2 复制(ASN)。有些 UDF 期望一个返回值，当您使用 SQL
VALUE语句来调用它们时。对于其他 UDF，请使用 SQLCALL语句。从 SQL 客户端启动 ASN 代理：
VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 或者，从 shell 中：
db2 "VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');"db2 "VALUES ASNCDC.ASNCDCSERVICES('start','asncdc');"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的语句返回以下结果之一：
-
asncap 已在运行 start --><COMMAND>在这种情况下，在终端窗口中输入指定的
<COMMAND>，如下例所示：/database/config/db2inst1/sqllib/bin/asncap capture_schema=asncdc capture_server=SAMPLE &
/database/config/db2inst1/sqllib/bin/asncap capture_schema=asncdc capture_server=SAMPLE &Copy to Clipboard Copied! Toggle word wrap Toggle overflow
-
将表置于捕获模式。对您要放入捕获的每个表调用以下语句：将
MYSCHEMA替换为包含您要放入捕获模式的表的模式名称。同样，将MYTABLE替换为表的名称，以放入捕获模式：CALL ASNCDC.ADDTABLE('MYSCHEMA', 'MYTABLE');CALL ASNCDC.ADDTABLE('MYSCHEMA', 'MYTABLE');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 重新初始化 ASN 服务：
VALUES ASNCDC.ASNCDCSERVICES('reinit','asncdc');VALUES ASNCDC.ASNCDCSERVICES('reinit','asncdc');Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.1.5.2. Db2 捕获服务器负载和延迟的代理配置的影响
当数据库管理员为源表启用更改数据捕获时，捕获代理开始运行。代理从事务日志读取新的更改事件记录，并将事件记录复制到捕获表中。在源表中提交更改的时间，以及更改出现在相应更改表中的时间，始终有一个小的延迟间隔。这个延迟间隔代表源表中出现更改时的间隔，以及 Debezium 到 Apache Kafka 的流提供时的差距。
理想情况下，对于必须快速响应数据更改的应用程序，您希望在源和捕获表之间保持关闭同步。您可能会认为，运行捕获代理以尽可能迅速地处理更改事件，从而导致吞吐量增加，并减少带有新事件记录的更改表（接近实时发生）。然而，这不一定如此。对于更直接的同步，需要支付性能损失。每次更改代理查询数据库以获取新事件记录时，它会增加数据库主机上的 CPU 负载。服务器上的额外负载可能会对整体数据库性能产生负面影响，并可能会降低交易效率，特别是在数据库使用高峰时。
监控数据库指标非常重要，以便您知道数据库是否达到服务器不再支持捕获代理的活动级别。如果您在运行捕获代理时遇到性能问题，请调整捕获代理设置来减少 CPU 负载。
2.1.5.3. Db2 捕获代理配置参数
在 Db2 上，IBMSNAP_CAPPARMS 表包含控制捕获代理行为的参数。您可以调整这些参数的值，以平衡捕获进程的配置，以减少 CPU 负载，并仍然保持可接受的延迟级别。
有关如何配置 Db2 捕获代理参数的具体指导超出了本文档的范围。
在 IBMSNAP_CAPPARMS 表中，以下参数对减少 CPU 负载有最大的影响：
COMMIT_INTERVAL- 指定捕获代理等待将数据提交到更改数据的秒数。
- 数值越高，可以减少数据库主机上的负载并增加延迟。
-
默认值为
30。
SLEEP_INTERVAL- 指定捕获代理在到达活跃事务日志结束后等待启动新提交周期的秒数。
- 数值越高，可以降低服务器的负载并增加延迟。
-
默认值为
5。
其他资源
- 有关捕获代理参数的更多信息，请参阅 Db2 文档。
2.1.6. 部署 Debezium Db2 连接器
您可以使用以下任一方法部署 Debezium Db2 连接器：
由于许可证要求，Debezium Db2 连接器存档不包括 Debezium 连接到 Db2 数据库所需的 Db2 JDBC 驱动程序。要启用连接器访问数据库，您必须在连接器环境中添加驱动程序。有关如何获取驱动程序的详情，请参考 获取 Db2 JDBC 驱动程序。
2.1.6.1. 获取 Db2 JDBC 驱动程序
由于许可证的要求，Debezium 连接到一个 Db2 数据库所需的 Db2 JDBC 驱动程序文件没有包括在 Debezium Db2 连接器存档中。该驱动程序可从 Maven Central 下载。根据您使用的部署方法，您可以通过将命令添加到 Kafka Connect 自定义资源或用于构建连接器镜像的 Dockerfile 来检索驱动程序。
-
如果您使用 Streams for Apache Kafka 将连接器添加到 Kafka Connect 镜像，请将驱动程序的 Maven Central 位置添加到
KafkaConnect自定义资源中的builds.plugins.artifact.url中，如 第 2.1.6.3 节 “使用 Apache Kafka 的 Streams 部署 Debezium Db2 连接器” 所示。 -
如果您使用 Dockerfile 为连接器构建容器镜像，请在 Dockerfile 中插入
curl命令，以指定从 Maven Central 下载所需驱动程序文件的 URL。如需更多信息，请参阅 第 2.1.6.4 节 “通过从 Dockerfile 构建自定义 Kafka Connect 容器镜像来部署 Debezium Db2 连接器”。
2.1.6.2. 使用 Apache Kafka 的 Streams 部署 Db2 连接器
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
2.1.6.3. 使用 Apache Kafka 的 Streams 部署 Debezium Db2 连接器
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅在 OpenShift Container Platform 中管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.3. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium Db2 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关语言依赖项。SMT 归档和语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
- Db2 JDBC 驱动程序，该驱动程序需要连接到 Db2 数据库，但不包含在连接器存档中。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.18. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。JDBC 驱动程序文件采用.jar格式。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需脚本语言组件，则
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
11
指定 Maven Central 中 Db2 JDBC 驱动程序的位置。Debezium Db2 连接器存档中不包含所需的驱动程序。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为db2-inventory-connector.yaml例 2.4.
db2-inventory-connector.yaml文件，为 Debezium 连接器定义KafkaConnector自定义资源Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.19. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址。
6
数据库实例的端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
9
要从中捕获更改的数据库的名称。
10
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。11
连接器捕获更改事件的表列表。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f db2-inventory-connector.yaml
oc create -n debezium -f db2-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
您现在已准备好 验证 Debezium Db2 部署。
要部署 Debezium Db2 连接器，您必须构建包含 Debezium 连接器归档的自定义 Kafka Connect 容器镜像，然后将此容器镜像推送到容器 registry。然后，您需要创建以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium Db2 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- Db2 正在运行，您完成了 设置 Db2 的步骤，以使用 Debezium 连接器。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka 流。
- podman 或 Docker 已安装。
- Kafka Connect 服务器有权访问 Maven Central，以下载 Db2 所需的 JDBC 驱动程序。您还可以使用驱动程序的本地副本，或使用本地 Maven 存储库或其他 HTTP 服务器可用的副本。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。
流程
为 Kafka Connect 创建 Debezium Db2 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-db2.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-db2.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-db2:latest .
podman build -t debezium-container-for-db2:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-db2:latest .
docker build -t debezium-container-for-db2:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令使用名称
debezium-container-for-db2构建容器镜像。将自定义镜像推送到容器 registry，如 quay.io 或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：
podman push <myregistry.io>/debezium-container-for-db2:latest
podman push <myregistry.io>/debezium-container-for-db2:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-db2:latest
docker push <myregistry.io>/debezium-container-for-db2:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium Db2
KafkaConnect自定义资源(CR)。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。输入以下命令将
KafkaConnectCR 应用到 OpenShift Kafka Connect 环境：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令添加一个 Kafka Connect 实例，用于指定为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium Db2 连接器实例。您可以在
.yaml文件中配置 Debezium Db2 连接器，该文件指定连接器的配置属性。连接器配置可能会指示 Debezium 为模式和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略、掩码或截断指定列中的值，这些值是敏感、太大或不需要的。以下示例配置了在端口
50000上连接到 Db2 服务器主机192.168.99.100的 Debezium 连接器。此主机有一个名为mydatabase的数据库，名为inventory的表，inventory-connector-db2是服务器的逻辑名称。Db2
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.20. 连接器配置设置的描述 项 描述 1
在 Kafka Connect 集群中注册连接器的名称。
2
此 Db2 连接器类的名称。
3
只在任何时候只能运行一个任务。
4
连接器的配置。
5
数据库主机，即 Db2 实例的地址。
6
Db2 实例的端口号。
7
Db2 用户的名称。
8
Db2 用户的密码。
9
要从中捕获更改的数据库的名称。
10
Db2 实例/集群的逻辑名称，它组成一个命名空间，并在连接器写入的 Kafka 主题的名称、Kafka Connect 模式的名称以及使用 Avro Connector 时对应的 Avro 模式的命名空间使用。
11
连接器只捕获
public.inventory表中的更改。使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的mydatabase数据库运行。
有关您可以为 Debezium Db2 连接器设置的配置属性的完整列表，请参阅 Db2 连接器属性。
结果
连接器启动后，它会执行 Db2 数据库表的一致性快照，连接器被配置为捕获更改。然后，连接器开始为行级操作生成数据更改事件，并将更改事件记录流传输到 Kafka 主题。
2.1.6.5. 验证 Debezium Db2 连接器正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，点您要检查的连接器名称，如 inventory-connector-db2。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-db2 -n debezium
oc describe KafkaConnector inventory-connector-db2 -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.5.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，单击要检查的主题的名称，例如
inventory-connector-db2.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.6.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-db2.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-db2.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中返回
的格式相同，例如inventory-connector-db2.inventory.addresses。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.7. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-db2.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-db2.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-db2.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.db2.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-db2.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"db2","name":"inventory-connector-db2","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"db2-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-db2.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-db2.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-db2.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.db2.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-db2.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"db2","name":"inventory-connector-db2","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"db2-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
2.1.6.6. Debezium Db2 连接器配置属性的描述
Debezium Db2 连接器有许多配置属性，可用于为应用程序获得正确的连接器行为。许多属性具有默认值。有关属性的信息按如下方式进行组织：
- 所需的配置属性
- 高级配置属性
- 数据库架构历史记录连接器配置属性，用于控制 Debezium 如何处理从数据库架构历史记录主题读取的事件。
所需的 Debezium Db2 连接器配置属性
除非默认值可用 ， 否则需要以下配置属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器的唯一名称。尝试使用相同名称再次注册将失败。所有 Kafka Connect 连接器都需要此属性。 | |
| 没有默认值 |
连接器的 Java 类的名称。对于 Db2 连接器，始终使用 | |
|
| 应该为此连接器创建的最大任务数量。Db2 连接器始终使用单个任务，因此不使用这个值，因此始终可以接受默认值。 | |
| 没有默认值 | Db2 数据库服务器的 IP 地址或主机名。 | |
|
| Db2 数据库服务器的整数端口号。 | |
| 没有默认值 | 用于连接到 Db2 数据库服务器的 Db2 数据库用户的名称。 | |
| 没有默认值 | 连接到 Db2 数据库服务器时要使用的密码。 | |
| 没有默认值 | 从中流传输更改的 Db2 数据库的名称 | |
| 没有默认值 |
为托管 Debezium 正在捕获更改的数据库的特定 Db2 数据库服务器提供命名空间的前缀。必须在主题前缀名称中使用字母数字字符、连字符、点和下划线。主题前缀应该在所有其他连接器之间唯一，因为此主题前缀用于从这个连接器接收记录的所有 Kafka 主题。 警告 不要更改此属性的值。如果您更改了 name 值，重启后，而不是继续向原始主题发送事件，连接器会将后续事件发送到名称基于新值的主题。连接器也无法恢复其数据库架构历史记录主题。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，该表达式与您希望连接器捕获的表的完全限定表标识符匹配。当设置此属性时，连接器只从指定的表中捕获更改。每个标识符都是 schemaName.tableName 的形式。默认情况下，连接器捕获每个非系统表中的更改。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配，它与表名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，它匹配您不希望连接器捕获的表的完全限定表标识符。连接器捕获排除列表中未包含的每个非系统表中的更改。每个标识符都是 schemaName.tableName 的形式。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配，它与表名称中可能存在的子字符串不匹配。 | |
| 空字符串 |
可选的、以逗号分隔的正则表达式列表，与要包含在更改事件记录值中的列的完全限定域名匹配。列的完全限定域名格式为 schemaName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。如果您在配置中包含此属性，不要设置 | |
| 空字符串 |
可选的、以逗号分隔的正则表达式列表，与要从更改事件值中排除的列的完全限定域名匹配。列的完全限定域名格式为 schemaName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。主键列始终包含在事件的键中，即使它们被排除在值中。如果您在配置中包含此属性，请不要设置 | |
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。列的完全限定域名格式为 schemaName.tableName.columnName。
一个 pseudonym，它包括了通过应用指定的 hashAlgorithm 和 salt 的结果的哈希值。根据使用的 hash 功能，引用完整性会被维护，而列值则替换为 pseudonyms。Java 加密架构标准算法 文档的 MessageDigest 部分中 描述了支持的哈希功能。 column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName
如有必要，pseudonym 会自动缩短到列的长度。连接器配置可以包含多个属性，以指定不同的哈希算法和 salt。 | |
|
|
时间、日期和时间戳可以以不同的精度类型代表： | |
|
|
控制 删除 事件是否后跟 tombstone 事件。 | |
|
| 布尔值指定连接器是否应该将数据库模式中的更改发布到与数据库服务器 ID 名称相同的 Kafka 主题。每个架构更改都使用一个键记录，其中包含数据库名称和一个 JSON 结构，用于描述 schema 更新。这独立于连接器内部记录数据库架构历史记录。 | |
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果在列中的数据超过了在属性名中的 length 指定的字符长度时删节数据，设置此属性。将 列的完全限定域名观察以下格式： schemaName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。 您可以在单个配置中指定多个长度不同的属性。 | |
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果您希望连接器屏蔽一组列的值，例如，如果它们包含敏感数据，则设置此属性。将
列的完全限定域名观察以下格式： schemaName.tableName.columnName。 您可以在单个配置中指定多个长度不同的属性。 | |
| 不适用 | 可选的、以逗号分隔的正则表达式列表，与您希望连接器发送代表列元数据的额外参数匹配。当设置此属性时，连接器将以下字段添加到事件记录的 schema 中：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
列的完全限定域名观察以下格式之一： databaseName.tableName.columnName, 或 databaseName.schemaName.tableName.columnName。 | |
| 不适用 | 可选的、以逗号分隔的正则表达式列表，用于指定为数据库中列定义的数据类型的完全限定名称。当设置此属性时，对于带有匹配数据类型的列，连接器会发出事件记录，该记录在其 schema 中包含以下额外字段：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
列的完全限定域名观察以下格式之一： databaseName.tableName.typeName, 或 databaseName.schemaName.tableName.typeName。 有关特定于 Db2 数据类型名称的列表，请参阅 Db2 数据类型映射。 | |
| 空字符串 | 一个表达式列表，用于指定连接器用来组成自定义消息键的表达式列表，用于更改它发布到指定表的 Kafka 主题。
默认情况下，Debebe 使用表的主键列作为发出的记录的消息键。使用默认键，或者为缺少主密钥的表指定一个键，您可以根据一个或多个列配置自定义消息密钥。
属性可以列出多个表的条目。使用分号分隔列表中不同表的条目。 | |
| none |
指定应该如何调整模式名称，以便与连接器使用的消息转换器兼容。可能的设置：
| |
| none |
指定应如何调整字段名称，以便与连接器使用的消息转换器兼容。可能的设置：
如需了解更多详细信息，请参阅 Avro 命名。 |
高级连接器配置属性
以下 高级配置 属性在大多数情况下可以正常工作，因此很少需要在连接器配置中指定。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
枚举连接器可以使用的 自定义转换器 实例的符号链接名称列表。例如，
您必须设置
对于您为连接器配置的每个转换器，还必须添加一个
例如， isbn.type: io.debezium.test.IsbnConverter
如果要进一步控制配置的转换器的行为，您可以添加一个或多个配置参数来将值传递给转换器。要将任何其他配置参数与转换器关联，请为参数名称添加转换器符号名称作为前缀。 isbn.schema.name: io.debezium.db2.type.Isbn | |
| Initial |
指定在连接器启动时执行快照的条件：
| |
| exclusive | 控制连接器保存表锁定的时长。表锁定可防止其他数据库客户端在快照期间执行某些表操作。您可以设置以下值：
| |
|
|
指定连接器在执行快照时如何查询数据。
与使用 | |
|
|
在快照过程中，控制事务隔离级别，以及连接器锁定处于捕获模式的表的时间。可能的值有： | |
|
|
指定连接器在处理事件过程中如何处理异常。可能的值有： | |
|
| 正整数值指定连接器在开始处理一系列事件前应等待新的更改事件数。默认值为 500 毫秒，或 0.5 秒。 | |
|
| 正整数值，用于指定连接器进程的每个批处理事件的最大大小。 | |
|
|
正整数值，用于指定阻塞队列可以保存的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将 | |
|
|
指定阻塞队列的最大卷的长整数值，以字节为单位。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。 | |
|
|
控制连接器将心跳信息发送到 Kafka 主题的频率。默认行为是连接器不发送心跳消息。 | |
| 没有默认值 | 连接器在连接器启动时执行快照前应等待的时间（以毫秒为单位）。如果您要在集群中启动多个连接器，此属性可用于避免快照中断，这可能会导致连接器重新平衡。 | |
| 0 |
指定连接器在完成快照后延迟流过程启动的时间（以毫秒为单位）。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的 | |
|
|
可选的、以逗号分隔的正则表达式列表，与表的完全限定名称(< 要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
|
| 在快照过程中，连接器在行的批处理中读取表内容。此属性指定批处理中的最大行数。 | |
|
|
正整数值，用于指定在执行快照时等待获取表锁定的最大时间（以毫秒为单位）。如果连接器无法获取此间隔中的表锁定，则快照会失败。连接器如何执行快照 提供详细信息。其他可能的设置是： | |
| 没有默认值 | 指定要包含在快照中的表行。如果您希望快照只包括表中的行的子集，请使用该属性。此属性仅影响快照。它不适用于连接器从日志读取的事件。
属性包含以逗号分隔的完全限定表名称列表，格式为 <
从包括软删除列 "snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM customers.orders WHERE delete_flag = 0 ORDER BY id DESC"
在生成的快照中，连接器只包含 | |
|
|
决定连接器是否生成带有事务边界的事件，并使用事务元数据增强更改事件。如果您希望连接器进行此操作，请指定 | |
|
|
在流过程中跳过的操作类型的逗号分隔列表。操作包括： | |
| 没有默认值 |
用于向连接器发送信号的数据收集的完全限定名称。https://docs.redhat.com/documentation/en/red_hat_build_of_debezium/2.7.3/html-single/debezium_user_guide/index#debezium-signaling-enabling-source-signaling-channel使用以下格式指定集合名称： | |
| source | 为连接器启用的信号通道名称列表。默认情况下，以下频道可用：
| |
| 没有默认值 | 为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
| |
|
| 连接器在增量快照块期间获取并读取的最大行数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。 | |
|
|
指定连接器在增量快照中使用的水位线机制，以重复数据删除事件，这些事件可能会被增量快照捕获，然后在流恢复后重新捕获。
| |
|
|
应用于确定数据更改的主题名称、模式更改、事务、心跳事件等主题名称，默认为 | |
|
|
指定主题名称的分隔符，默认为 | |
|
| 在绑定的并发散列映射中保存主题名称的大小。此缓存将有助于确定与给定数据收集对应的主题名称。 | |
|
|
控制连接器发送心跳消息的主题名称。主题名称具有此模式： | |
|
|
控制连接器发送事务元数据消息的主题名称。主题名称具有此模式： | |
|
| 指定连接器在执行初始快照时使用的线程数量。要启用并行初始快照，请将 属性设置为大于 1 的值。在并行初始快照中，连接器同时处理多个表。 重要 并行初始快照只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。 | |
|
|
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如 连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。 | |
|
|
指定连接器如何在生成 Retriable 错误的操作后响应，如连接错误。
| |
|
|
指定连接器等待查询完成的时间（以毫秒为单位）。将值设为 |
Debezium Db2 连接器数据库模式历史记录配置属性
Debezium 提供了一组 schema.history.internal.* 属性，用于控制连接器如何与 schema 历史记录主题进行交互。
下表描述了用于配置 Debezium 连接器的 schema.history.internal 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器存储数据库 schema 历史记录的 Kafka 主题的完整名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机/端口对列表。此连接用于检索之前由连接器存储的数据库架构历史记录，以及写入从源数据库读取的每个 DDL 语句。每个对都应该指向 Kafka Connect 进程使用的相同 Kafka 集群。 | |
|
| 整数值，指定连接器在启动/恢复期间应等待的最大毫秒数，同时轮询持久数据。默认值为 100ms。 | |
|
| 指定连接器在使用 Kafka admin 客户端获取集群信息时应等待的最大毫秒数。 | |
|
| 指定连接器在使用 Kafka admin 客户端创建 kafka 历史记录主题时应等待的最大毫秒数。 | |
|
|
连接器在连接器恢复失败前尝试读取持久性历史记录数据的次数上限，并显示错误。没有数据后等待的最长时间是 | |
|
|
指定连接器是否应该忽略不正确的或未知数据库语句的布尔值，或停止处理，以便用户可以解决这个问题。安全默认为 | |
|
|
指定连接器是否记录模式或数据库中所有表的布尔值，或者仅从指定为捕获的表记录。
| |
|
|
指定连接器是否从数据库实例中的所有逻辑数据库记录模式结构的布尔值。
|
透传 Db2 连接器配置属性
连接器支持 通过传递 属性，使 Debezium 指定自定义配置选项来微调 Apache Kafka producer 和消费者的行为。有关 Kafka 生成者和消费者的完整配置属性范围的详情，请参考 Kafka 文档。
直通属性，用于配置生成者和消费者客户端如何与 schema 历史记录主题交互
Debezium 依赖于 Apache Kafka producer 将 schema 更改写入数据库 schema 历史记录主题。同样，它依赖于 Kafka 使用者在连接器启动时从数据库 schema 历史记录主题中读取。您可以通过将值分配给一组以 schema.history.internal.producer和 schema.history.internal.consumerPromQL 前缀开头的 pass-through 配置属性来定义 Kafka producer 和 消费者 客户端的配置。pass-through producer 和 consumer 数据库模式历史记录属性控制一系列行为，如这些客户端如何与 Kafka 代理安全连接，如下例所示：
Debezium 在将属性传递给 Kafka 客户端前从属性名称中剥离前缀。
有关 Kafka producer 配置属性和 Kafka 使用者配置属性的更多信息，请参阅 Apache Kafka 文档。
直通属性，用于配置 Db2 连接器如何与 Kafka 信号主题交互
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
为信号频道配置 Kafka 消费者客户端的属性
Debezium 连接器提供信号 Kafka 使用者的直通配置。透传信号属性以 signals.consumer.* 前缀开始。例如，连接器将 signal.consumer.security.protocol=SSL 等属性传递给 Kafka 使用者。
Debezium 在将属性传递给 Kafka 信号消费者前从属性中剥离前缀。
用于配置 Db2 连接器接收器通知频道的直通属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
Debezium 连接器传递数据库驱动程序配置属性
Debezium 连接器提供数据库驱动程序的直通配置。透传数据库属性以前缀 driverPROFILE 开头。例如，连接器将 driver.foobar=false 等属性传递给 JDBC URL。
Debezium 在将属性传递给数据库驱动程序前从属性中剥离前缀。
2.1.7. 监控 Debezium Db2 连接器性能
Debezium Db2 连接器提供三种类型的指标，除了 Apache ZooKeeper、Apache Kafka 和 Kafka Connect 提供的 JMX 指标外。
Debezium 监控文档 提供了如何使用 JMX 公开这些指标的详细信息。
2.1.7.1. Db2 连接器快照和流 MBean 对象的自定义名称
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.8. 自定义标签如何修改连接器 MBean 名称
默认情况下，Db2 连接器使用以下 MBean 名称进行流传输指标：
debezium.db2:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.db2:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.db2:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.db2:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.1.7.2. 在 Db2 数据库快照期间监控 Debezium
MBean 为 debezium.db2:type=connector-metrics,context=snapshot,server= <topic.prefix>。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
连接器还会在执行增量快照时提供以下附加快照指标：
2.1.7.3. 监控 Debezium Db2 连接器记录流
MBean 为 debezium.db2:type=connector-metrics,context=streaming,server= <topic.prefix>。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
2.1.7.4. 监控 Debezium Db2 连接器模式历史记录
MBean 为 debezium.db2:type=connector-metrics,context=schema-history,server= <topic.prefix>。
下表列出了可用的模式历史记录指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
|
| |
|
| 恢复开始的时间（以 epoch 秒为单位）。 | |
|
| 在恢复阶段读取的更改数量。 | |
|
| 恢复和运行时应用的模式更改总数。 | |
|
| 自上次更改从历史记录存储中恢复后经过的毫秒数。 | |
|
| 从上次更改被应用后经过的毫秒数。 | |
|
| 从历史记录存储中恢复最后一次更改的字符串表示。 | |
|
| 最后一次应用更改的字符串表示。 |
2.1.8. 管理 Debezium Db2 连接器
部署 Debezium Db2 连接器后，使用 Debezium 管理 UDFs 来控制带有 SQL 命令的 Db2 复制(ASN)。有些 UDF 期望一个返回值，当您使用 SQL VALUE 语句来调用它们时。对于其他 UDF，请使用 SQL CALL 语句。
| 任务 | 命令和备注 |
|---|---|
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
2.1.9. 在 Debezium 连接器的捕获模式中更新 Db2 表的模式
虽然 Debezium Db2 连接器可以捕获模式更改，要更新 schema，但您必须与数据库管理员合作，以确保连接器继续生成更改事件。Db2 实施复制的方式需要这样做。
对于捕获模式中的每个表，Db2 中的复制功能会创建一个 change-data 表，其中包含该源表的所有更改。但是，change-data 表模式是静态的。如果您以捕获模式更新表的 schema，则还必须更新其对应的 change-data 表的 schema。Debezium Db2 连接器无法做到这一点。具有升级特权的数据库管理员必须为处于捕获模式的表更新模式。
在同一表中有新的架构更新前，完全执行架构更新过程非常重要。因此，建议在单个批处理中执行所有 DDL，因此仅执行一次模式更新过程。
通常有两个更新表模式的步骤：
每种方法都有优缺点。
2.1.9.1. 为 Debezium Db2 连接器执行离线 schema 更新
在执行离线 schema 更新前，您可以停止 Debezium Db2 连接器。虽然这是更安全的模式更新过程，但对于具有高可用性要求的应用程序可能并不可行。
先决条件
- 处于捕获模式的一个或多个表需要 schema 更新。
流程
- 暂停更新数据库的应用程序。
- 等待 Debezium 连接器流所有未流的更改事件记录。
- 停止 Debezium 连接器。
- 将所有更改应用到源表模式。
-
在 ASN 注册表中，将更新的模式标记为
INACTIVE。 - 重新初始化 ASN 捕获服务。
- 通过运行 Debezium UDF 从捕获模式中删除表，从捕获模式中删除带有旧模式 的源表。
- 通过运行 Debezium UDF 来添加源表以捕获模式，将源表添加到捕获模式。
-
在 ASN 注册表中，将更新的源表标记为
ACTIVE。 - 重新初始化 ASN 捕获服务。
- 恢复更新数据库的应用程序。
- 重启 Debezium 连接器。
2.1.9.2. 为 Debezium Db2 连接器执行在线 schema 更新
在线 schema 更新不会导致应用程序和数据处理的停机时间。也就是说，在执行在线 schema 更新前，您不会停止 Debezium Db2 连接器。另外，在线架构更新过程比离线 schema 更新的步骤简单。
但是，当表处于捕获模式时，在更改列名称后，Db2 复制功能将继续使用旧的列名称。新列名称不会出现在 Debezium 更改事件中。您必须重启连接器，才能在更改事件中看到新列名称。
先决条件
- 处于捕获模式的一个或多个表需要 schema 更新。
在表末尾添加列的步骤
- 锁定您要更改其模式的源表。
-
在 ASN 注册表中，将锁定的表标记为
INACTIVE。 - 重新初始化 ASN 捕获服务。
- 将所有更改应用到源表的 schema。
- 将所有更改应用到架构，以对应的 change-data 表。
-
在 ASN 注册表中，将源表标记为
ACTIVE。 - 重新初始化 ASN 捕获服务。
- 可选。重启连接器，以查看更改事件中的更新列名称。
在表的中间添加列的步骤
- 锁定要更改的源表。
-
在 ASN 注册表中，将锁定的表标记为
INACTIVE。 - 重新初始化 ASN 捕获服务。
对于每个源表，需要更改：
- 在 source 表中导出数据。
- 截断源表。
- 更改源表并添加列。
- 将导出的数据加载到更改的源表中。
- 在源表对应的 change-data 表中导出数据。
- 截断 change-data 表。
- 更改 change-data 表并添加列。
- 将导出的数据加载到更改的 change-data 表中。
-
在 ASN 注册表中，将表标记为
INACTIVE。这会将旧的 change-data 表标记为 inactive，它允许它们中的数据保留，但不再更新它们。 - 重新初始化 ASN 捕获服务。
- 可选。重启连接器，以查看更改事件中的更新列名称。
2.2. MariaDB 的 Debezium 连接器（技术预览）
MariaDB 的 Debezium 连接器只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。
有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。
MariaDB 有一个二进制日志(binlog)，可按照提交至数据库的顺序记录所有操作。这包括对表模式的更改，以及表中的数据更改。MariaDB 使用 binlog 进行复制和恢复。
Debezium MariaDB 连接器读取 binlog，为行级 INSERT、UPDATE 和 DELETE 操作生成更改事件，并将更改事件发送到 Kafka 主题。客户端应用程序读取这些 Kafka 主题。
由于 MariaDB 通常会在指定时间段内设置为清除 binlogs，因此 MariaDB 连接器会为每个数据库执行初始 一致的快照。MariaDB 连接器从创建快照的时间点读取 binlog。
有关与此连接器兼容的 MariaDB 数据库版本的详情，请参考 Debezium 支持的配置 页面。
使用 Debezium MariaDB 连接器的信息和流程组织如下：
- 第 2.2.1 节 “Debezium MariaDB 连接器如何工作”
- 第 2.2.2 节 “Debezium MariaDB 连接器数据更改事件的描述”
- 第 2.2.3 节 “Debezium MariaDB 连接器如何映射数据类型”
- 第 2.2.4 节 “将 MariaDB 数据映射到替代数据类型的自定义转换器”
- 第 2.2.5 节 “设置 MariaDB 以运行 Debezium 连接器”
- 第 2.2.6 节 “部署 Debezium MariaDB 连接器”
- 第 2.2.7 节 “监控 Debezium MariaDB 连接器性能”
- 第 2.2.8 节 “Debezium MariaDB 连接器如何处理错误和问题”
2.2.1. Debezium MariaDB 连接器如何工作
连接器支持的 MariaDB 拓扑概述对规划应用程序非常有用。要优化地配置和运行 Debezium MariaDB 连接器，了解连接器如何跟踪表的结构、公开模式更改、执行快照并确定 Kafka 主题名称。
详情包括在以下主题中：
2.2.1.1. Debezium 连接器支持的 MariaDB 拓扑
Debezium MariaDB 连接器支持以下 MariaDB 拓扑：
- Standalone
- 当使用单个 MariaDB 服务器时，服务器必须启用 binlog，以便 Debezium MariaDB 连接器可以监控服务器。这通常可以接受，因为二进制日志也可以用作增量 [backup]。在这种情况下，MariaDB 连接器始终连接到并遵循此独立 MariaDB 服务器实例。
- 主(primary)和副本
Debezium MariaDB 连接器可遵循其中一个主服务器，或者其中一个副本(如果该副本启用了 binlog)，但连接器仅检测对该服务器可见的集群中的更改。通常，除了多主拓扑外，这并不是一个问题。
连接器在服务器的 binlog 中记录其位置，该位置在集群中的每个服务器上都有所不同。因此，连接器必须只遵循一个 MariaDB 服务器实例。如果该服务器失败，则必须重启或恢复该服务器，然后才能继续连接器。
- 高可用性集群
- MariaDB 存在各种 [高可用性] 解决方案，它们能够更容易容忍并几乎从问题和故障中恢复。因为 HA MariaDB 集群使用 GTID，副本可以跟踪任何主服务器中发生的所有更改。
- 多主要
使用每个从多个主服务器复制的一个或多个 MariaDB 副本节点。集群复制提供了一种强大的方法来聚合多个 MariaDB 集群的复制。
Debezium MariaDB 连接器可以使用这些多主 MariaDB 副本作为源，只要新副本被捕获到旧副本，就可以切换到不同的多主 MariaDB 副本。也就是说，新副本具有第一个副本上看到的所有事务。即使连接器只使用数据库和/或表的子集，因为在尝试重新连接到新的多主 MariaDB 副本时，也可以将连接器配置为包含或排除特定的 GTID 源。
- 托管
Debezium MariaDB 连接器可以使用托管数据库选项，如 Amazon RDS 和 Amazon Aurora。
由于这些托管的选项不允许使用全局读取锁定，因此连接器在创建一致的快照时会使用表级锁定。
2.2.1.2. Debezium MariaDB 连接器如何处理数据库架构更改
当数据库客户端查询数据库时，客户端将使用数据库的当前架构。但是，可以随时更改数据库架构，这意味着连接器必须能够识别每次插入、更新或删除操作时的 schema。另外，连接器不一定将当前模式应用到每个事件。如果事件相对旧，则在应用当前模式之前记录这些事件。
为确保在架构更改后处理发生的正确事件，MariaDB 在事务日志中包括影响数据的行级更改，以及应用到数据库的 DDL 语句。当连接器在 binlog 中遇到这些 DDL 语句时，它会解析它们并更新每个表的 schema 的内存表示。连接器使用此架构表示在每次插入、更新或删除操作时标识表的结构，并生成适当的更改事件。在单独的数据库架构历史记录 Kafka 主题中，连接器记录了所有 DDL 语句，以及显示每个 DDL 语句的 binlog 中的位置。
当连接器在崩溃或安全停止后重启时，它开始从特定位置读取 binlog，即从特定时间点读取 binlog。连接器通过读取数据库模式历史记录 Kafka 主题来重建在此时存在的表结构，并将所有 DDL 语句解析到连接器启动的 binlog 中的点。
此数据库架构历史记录主题仅用于内部连接器。另外，连接器也可以将 schema 更改事件发送到面向消费者应用程序的不同主题。
当 MariaDB 连接器捕获在应用模式更改工具（如 gh-ost 或 pt-online-schema-change ）的表中的更改时，会在迁移过程中创建帮助程序表。您必须配置连接器来捕获这些帮助程序表中发生的更改。如果消费者不需要记录连接器为帮助程序表生成的记录，请将单个消息转换(SMT) 配置为从连接器发出的消息中删除这些记录。
其他资源
- 接收 Debezium 事件记录 的主题的默认名称。
2.2.1.3. Debezium MariaDB 连接器如何公开数据库架构更改
您可以配置 Debezium MariaDB 连接器来生成模式更改事件，以描述应用到数据库中表的 schema 更改。连接器将模式更改事件写入名为 < topicPrefix> 的 Kafka 主题，其中 topicPrefix 是 topic.prefix 连接器配置属性中指定的命名空间。连接器发送到 schema 更改主题的消息包含一个有效负载，并可以选择包含更改事件消息的 schema。
模式更改事件的 schema 具有以下元素：
名称- 模式更改事件消息的名称。
type- 更改事件消息的类型。
version- 架构的版本。version 是一个整数，每次更改 schema 时都会递增。
fields- 更改事件消息中包含的字段。
示例：MariaDB 连接器模式更改主题的 Schema
以下示例显示了 JSON 格式的典型模式。
模式更改事件消息的有效负载包括以下元素：
ddl-
提供导致 schema 的 SQL
CREATE、ALTER或DROP语句。 databaseName-
DDL 语句应用到的数据库名称。
databaseName的值充当 message 键。 pos- 语句的 binlog 中的位置。
tableChanges-
架构更改后整个表模式的结构化表示。
tableChanges字段包含一个数组，其中包含表的每列条目。由于结构化表示以 JSON 或 Avro 格式显示数据，因此用户可以轻松地读取消息，而无需首先通过 DDL 解析器处理它们。
对于处于捕获模式的表，连接器不仅将模式更改的历史记录存储在 schema 更改主题中，还要存储在内部数据库架构历史记录主题中。内部数据库架构历史记录主题仅用于连接器，它不用于直接使用应用程序。确保需要针对 schema 更改通知的应用程序只消耗了来自 schema 更改主题的信息。
永不对数据库 schema 历史记录主题进行分区。要使数据库架构历史记录主题正常工作，它必须保持一致的全局顺序，连接器向其发送的事件记录。
要确保主题不在分区中分割，请使用以下方法之一为主题设置分区计数：
-
如果您手动创建数据库架构历史记录主题，请指定分区计数
1。 -
如果您使用 Apache Kafka 代理自动创建数据库模式历史记录主题，则会创建主题，将 Kafka
num.partitions配置选项 的值设置为1。
连接器发送到其 schema 更改主题的消息格式处于 inubating 状态，并可能会在不通知的情况下更改。
示例：向 MariaDB 连接器模式更改主题的消息发送
以下示例显示了 JSON 格式的典型的模式更改消息。消息包含表 schema 的逻辑表示。
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
|
| 2 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 3 |
|
标识包含更改的数据库和模式。 |
| 4 |
|
此字段包含负责 schema 更改的 DDL。 |
| 5 |
| 包含 DDL 命令生成的架构更改的一个或多个项目的数组。 |
| 6 |
| 描述更改类型。该值是以下之一：
|
| 7 |
|
创建、更改或丢弃的表的完整标识符。对于表重命名，此标识符是 < |
| 8 |
| 代表应用的更改后的表元数据。 |
| 9 |
| 编写表主键的列列表。 |
| 10 |
| changed 表中每个列的元数据。 |
| 11 |
| 每个表更改的自定义属性元数据。 |
如需更多信息，请参阅 模式历史记录主题。
2.2.1.4. Debezium MariaDB 连接器如何执行数据库快照
当 Debezium MariaDB 连接器首次启动时，它会执行数据库的初始 一致快照。此快照可让连接器为数据库的当前状态建立基准。
Debezium 在运行快照时可以使用不同的模式。快照模式由 snapshot.mode 配置属性决定。属性的默认值为 initial。您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。
您可以在以下部分中找到有关快照的更多信息：
连接器在执行快照时完成一系列任务。确切的步骤因快照模式以及对数据库的影响的表锁定策略而有所不同。当 Debezium MariaDB 连接器执行 使用全局读取锁定或 表级锁定 的初始快照时，它会完成不同的步骤。
2.2.1.4.1. 使用全局读取锁定的初始快照
您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。如果您配置不同的快照模式，连接器使用此工作流的修改版本完成快照。有关不允许全局读取锁定的环境中的快照进程的详情，请查看 表级锁定的快照工作流。
Debezium MariaDB 连接器用来执行带有全局读取锁定的初始快照的默认工作流
下表显示了 Debezium 遵循的工作流中的步骤，以创建具有全局读取锁定的快照。
| 步骤 | 操作 |
|---|---|
| 1 | 建立与数据库的连接。 |
| 2 |
确定要捕获的表。默认情况下，连接器捕获所有非系统表的数据。快照完成后，连接器将继续流传输指定表的数据。如果您希望连接器只从特定表捕获数据，您可以通过设置 |
| 3 |
获取表上要捕获的全局读取锁定，以阻止其他数据库客户端 写入。 |
|
4 注意 使用这些隔离语义可能会减慢快照的进度。如果快照需要很长时间才能完成，请考虑使用不同的隔离配置，或者跳过初始快照并运行 增量快照。 | 5 |
| 阅读当前的 binlog 位置。 | 6 |
|
捕获数据库中所有表的结构或指定用于捕获的所有表。连接器在其内部数据库模式历史记录主题中保留模式信息，包括所有必要的 注意
默认情况下，连接器捕获数据库中每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。 | 7 |
| 释放在第 3 步中获得的全局读锁定。其他数据库客户端现在可以写入数据库。 | 8 |
| 在步骤 5 中连接器读取的 binlog 位置，连接器开始扫描指定为捕获的表。在扫描过程中，连接器完成以下任务：
| 9 |
| 提交事务。 | 10 |
生成的初始快照会捕获捕获表中每行的当前状态。在这个基准状态中，连接器会捕获后续更改。
在快照过程开始后，如果进程因为连接器失败、重新平衡或其他原因而中断，进程会在连接器重启后重启。
连接器完成初始快照后，它会继续从第 5 步中读取的位置流，使其不会丢失任何更新。
如果连接器因任何原因再次停止，它会在重启后恢复流更改，从之前离开的位置恢复流更改。
连接器重启后，如果修剪日志，则日志中的连接器位置可能不再可用。然后，连接器会失败，并返回表示需要新快照的错误。要将连接器配置为在这种情况下自动启动快照，请将 snapshot.mode 属性的值设置为 when_needed。有关对 Debezium MariaDB 连接器进行故障排除的更多提示，请参阅 当出现问题时的行为。
2.2.1.4.2. 使用表级别锁定的初始快照
在某些数据库环境中，管理员不允许全局读取锁定。如果 Debezium MariaDB 连接器检测到不允许全局读取锁定，则连接器会在执行快照时使用表级锁定。要使连接器执行使用表级锁定的快照，Debezium 连接器用来连接到 MariaDB 的数据库帐户必须具有 LOCK TABLES 权限。
Debezium MariaDB 连接器用来执行带有表级锁定的初始快照的默认工作流
下表显示了 Debezium 遵循的工作流中的步骤，以使用表级读取锁定创建快照。有关不允许全局读取锁定的环境中的快照进程的详情，请查看 全局读取锁定的快照工作流。
| 步骤 | 操作 |
|---|---|
| 1 | 建立与数据库的连接。 |
| 2 |
确定要捕获的表。默认情况下，连接器会捕获所有非系统表。要让连接器捕获表或表元素的子集，您可以设置多个 |
| 3 | 获取表级锁定。 |
| 4 | 5 |
| 阅读当前的 binlog 位置。 | 6 |
|
读取将连接器配置为捕获更改的数据库和表的 schema。连接器在其内部数据库模式历史记录主题中保留模式信息，包括所有必要的 注意 默认情况下，连接器捕获数据库中每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。 有关您在初始快照中没有包括快照持久模式信息的更多信息，请参阅 了解为什么初始快照捕获所有表的 schema。 | 7 |
| 在步骤 5 中连接器读取的 binlog 位置，连接器开始扫描指定为捕获的表。在扫描过程中，连接器完成以下任务：
| 8 |
| 提交事务。 | 9 |
| 释放表级锁定。其他数据库客户端现在可以写入任何之前锁定的表。 | 10 |
| 设置 | 描述 |
|---|---|
|
| 连接器在每次启动时都执行快照。快照包括捕获的表的结构和数据。指定此值，每次连接器启动时，使用从捕获的表中数据的完整表示来填充主题。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照，如用于创建初始快照的默认工作流 中所述。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照。快照完成后，连接器会停止，且不会为后续数据库更改流传输事件记录。 |
|
|
弃用，请参阅 |
|
|
连接器捕获所有相关表的结构，执行 创建初始快照的默认工作流 中描述的所有步骤，但不创建 |
|
|
当连接器启动时，而不是执行快照时，它会立即开始为后续数据库更改流事件记录。这个选项考虑将来弃用，而是使用 |
|
|
弃用， |
|
|
设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
如需更多信息，请参阅连接器配置属性表中的 snapshot.mode。
2.2.1.4.3. 有关初始快照捕获所有表的 schema 历史记录的描述
连接器运行的初始快照捕获两种类型的信息：
- 表数据
-
有关
INSERT、UPDATE和DELETE操作的信息，它们在连接器的table.include.list属性中命名。 - 模式数据
- 描述应用到表的结构更改的 DDL 语句。如果配置了 schema 数据，则 schema 数据会被保留到内部模式历史记录主题，以及连接器的 schema 更改主题。
运行初始快照后，您可能会注意到快照捕获了未指定用于捕获的表的模式信息。默认情况下，初始快照旨在捕获数据库中存在的每个表的模式信息，而不仅限于为捕获指定的表。连接器要求表的 schema 在捕获表之前存在于 schema 历史记录主题中。通过启用初始快照来捕获不属于原始捕获集的表，Debezium 准备连接器，以便稍后需要从这些表中读取事件数据。如果初始快照没有捕获表的模式，您必须将 schema 添加到历史记录主题，然后才能从表中捕获数据。
在某些情况下，您可能想要限制初始快照中的模式捕获。当您要减少完成快照所需的时间时，这非常有用。或者，当 Debezium 通过有权访问多个逻辑数据库的用户帐户连接到数据库实例时，但您希望连接器只从特定逻辑数据库中的表捕获更改。
其他信息
- 从初始快照未捕获的表中捕获数据（无模式更改）
- 从没有由初始快照捕获的表捕获数据(schema 更改)
-
设置
schema.history.internal.store.only.captured.tables.ddl属性，以指定要从中捕获模式信息的表。 -
设置
schema.history.internal.store.only.captured.databases.ddl属性，以指定捕获模式更改的逻辑数据库。
2.2.1.4.4. 从初始快照未捕获的表中捕获数据（无模式更改）
在某些情况下，您可能希望连接器从最初快照未捕获其 schema 的表中捕获数据。根据连接器配置，初始快照可能会只捕获数据库中特定表的表模式。如果历史记录主题中没有表模式，连接器无法捕获表，并报告缺少的 schema 错误。
您可能仍然能够从表中捕获数据，但您必须执行额外的步骤来添加表模式。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 在事务日志中，表的所有条目都使用相同的模式。有关从具有结构化更改的新表捕获数据的详情，请参考 从初始快照(schema 更改)中未捕获的表 捕获数据。
流程
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 将以下更改应用到连接器配置：
-
将
snapshot.mode设置为schema_only_recovery。 -
将
schema.history.internal.store.only.captured.tables.ddl的值设置为false。 -
添加您希望连接器捕获到
table.include.list的表。这样可保证以后，连接器可以重建所有表的 schema 历史记录。
-
将
- 重启连接器。快照恢复过程会根据表的当前结构重建模式历史记录。
- （可选）在快照完成后，启动 增量快照 来捕获新添加的表的现有数据，以及该连接器离线时发生的其他表的更改。
-
（可选）将
snapshot.mode重置为schema_only，以防止连接器在以后的重启后启动恢复。
2.2.1.4.5. 从没有由初始快照捕获的表捕获数据(schema 更改)
如果将架构更改应用到表，则在架构更改前提交的记录与更改后提交的结构不同。当 Debezium 捕获表中的数据时，它会读取 schema 历史记录，以确保它将正确的模式应用到每个事件。如果 schema 历史记录主题中没有 schema，连接器将无法捕获表，并会产生错误结果。
如果要捕获初始快照未捕获的表中的数据，并修改了表的 schema，您必须将 schema 添加到历史记录主题（如果还没有可用）。您可以通过运行新的模式快照或运行表的初始快照来添加架构。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 对表应用了一个架构更改，因此要捕获的记录没有统一的结构。
流程
- 初始快照捕获了所有表的模式(
storage.only.captured.tables.ddl设置为false) -
编辑
table.include.list属性，以指定您要捕获的表。 - 重启连接器。
- 如果要从新添加的表中捕获现有数据，则启动 增量快照。
-
编辑
- 初始快照没有捕获所有表的模式(storage
.only.captured.tables.ddl设置为true) 如果初始快照没有保存您要捕获的表的模式，请完成以下步骤之一：
- 流程 1：Schema 快照，后跟增量快照
在此过程中，连接器首先执行 schema 快照。然后，您可以启动增量快照，使连接器能够同步数据。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为schema_only。 -
编辑
table.include.list以添加您要捕获的表。
-
将
- 重启连接器。
- 等待 Debezium 捕获新表和现有表的模式。连接器停止后发生的数据更改不会被捕获。
- 为确保没有数据丢失，可启动 增量快照。
- 流程 2：初始快照，后跟可选的增量快照
在此过程中，连接器执行数据库的完整初始快照。与任何初始快照一样，在具有许多大表的数据库中，运行初始快照可能是一个耗时的操作。快照完成后，您可以选择性地触发增量快照，以捕获连接器离线期间发生的任何更改。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
-
编辑
table.include.list以添加您要捕获的表。 为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为initial。 -
（可选）将
schema.history.internal.store.only.captured.tables.ddl设置为false。
-
将
- 重启连接器。连接器使用完整的数据库快照。快照完成后，连接器会过渡到 streaming。
- （可选）要捕获连接器脱机时更改的任何数据，请启动 增量快照。
2.2.1.5. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供总结表数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改为捕获不同的表集合。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号表。您可以通过向 Debezium 信号表发送信号请求来启动临时快照。
当您启动现有表的临时快照时，连接器会将内容附加到表已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的表。快照可以捕获数据库的全部内容，或者仅捕获数据库中表的子集。此外，快照也可捕获数据库中表的内容的子集。
您可以通过向信号表发送 execute-snapshot 消息来指定要捕获的表。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的表名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| N/A |
包含与快照中包含的表的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作表的主键的列名称。 |
触发临时增量快照
您可以通过向信号表添加带有 execute-snapshot 信号类型的条目，或者向 Kafka 信号发送信号消息 来启动临时增量快照。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个表的开始和端点。根据表中的条目数量以及配置的块大小，Debezium 会将表分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号表或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.2.1.6. 增量快照
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个表。您可以指定您希望快照捕获的表 以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debezium 使用水位线来跟踪其进度，维护其捕获的每个表行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获表。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，以将表添加到其
table.include.list属性中。
增量快照过程
当您运行增量快照时，Debezium 按主密钥对每个表进行排序，然后根据 配置的块大小 将表分成块。通过块工作的块，然后捕获块中的每个表行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改表记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获了包含该行的 READ 事件前修改表行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一表行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定表块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到表的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
2.2.1.6.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号表。您可以提交快照信号，作为 SQL INSERT 查询。
在 Debezium 检测到信号表中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的表，并可选择性地指定快照操作的类型。Debezium 目前支持 增量 和 阻塞 快照类型。
要指定要包含在快照中的表，提供一个列出表的 data-collections 数组，或用于匹配表的正则表达式数组，例如：
{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会解释空数组，意味着不需要任何操作，且不会执行快照。
如果要包含在快照中的表的名称包含一个点(.)、空格或其它非字母数字字符，则必须使用双引号转义表名称。
例如，要包含 db1 数据库中存在的表，并且名为 My.Table，请使用以下格式 ："db1.\"My.Table\" "。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
发送 SQL 查询，将临时增量快照请求添加到信号表中：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、type和data参数的值 与信号表的字段 相对应。
下表描述了示例中的参数：Expand 表 2.28. SQL 命令中的字段描述，用于将增量快照信号发送到信号表 项 值 描述 1
database.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshottype参数指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定表名称或正则表达式数组，以匹配快照中包含的表名称。
数组列出了使用格式database.table的正则表达式，以匹配表的完全限定名称。此格式与您用来指定连接器 信号表的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
有效值为incremental和blocking值。
如果没有指定值，连接器默认为执行增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
每个额外条件都是带有data-collection和filter属性的对象。您可以为每个数据收集指定不同的过滤器。
请参阅data-collection属性是过滤器应用到的数据收集的完全限定域名。有关additional-conditions参数的详情，请参考 使用附加条件运行临时增量快照。
使用附加 条件运行临时增量快照
如果您希望快照只在表中包括内容子集，您可以通过将 additional-conditions 参数附加到快照信号来修改信号请求。
对典型快照的 SQL 查询采用以下格式：
SELECT * FROM <tableName> ....
SELECT * FROM <tableName> ....
通过添加 additional-conditions 参数，您可以在 SQL 查询中附加 WHERE 条件，如下例所示：
SELECT * FROM <data-collection> WHERE <filter> ....
SELECT * FROM <data-collection> WHERE <filter> ....以下示例显示了向信号表发送带有额外条件的临时增量快照请求的 SQL 查询：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
例如，假设您有一个包含以下列的 products 表：
-
ID（主密钥） -
color -
quantity
如果您需要 product 表的增量快照，其中只包含 color=blue 的数据项，您可以使用以下 SQL 语句来触发快照：
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue"}]}');
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue"}]}');
additional-conditions 参数还允许您传递基于多个列的条件。例如，使用上例中的 product 表，您可以提交查询来触发增量快照，该快照仅包含 color=blue 和 quantity>10 的项数据：
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue AND quantity>10"}]}');
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue AND quantity>10"}]}');以下示例显示了连接器捕获的增量快照事件的 JSON。
例 2.9. 增量快照事件消息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.2.1.6.2. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.10. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择表内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果一个带有列 ID （主键）、颜色 和品牌 的 products 表，如果您希望快照只包含 color='blue' 的内容，当请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 product 表，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的 表中的内容，您可以发送以下请求：
products
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.2.1.6.3. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的信号发送信号来停止已经运行的快照。
您可以通过在 SQL INSERT 查询中发送停止快照信号，向信号表提交停止快照信号。stop-snapshot 信号将快照操作的类型指定为 增量，并选择性地指定要从当前运行的快照中省略的表。在 Debezium 检测到信号表中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
发送 SQL 查询以停止临时增量快照到信号表：
INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
INSERT INTO db1.debezium_signal (id, type, data) values ('ad-hoc-1', 'stop-snapshot', '{"data-collections": ["db1.table1", "db1.table2"], "type":"incremental"}');INSERT INTO db1.debezium_signal (id, type, data)1 values ('ad-hoc-1',2 'stop-snapshot',3 '{"data-collections": ["db1.table1", "db1.table2"],4 "type":"incremental"}');5 Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号表的字段相对应。
下表描述了示例中的参数：Expand 表 2.31. SQL 命令中的字段描述，用于将停止增量快照信号发送到信号表 项 值 描述 1
database.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。3
stop-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定表名称或正则表达式数组，以匹配要从快照中删除的表名称。
数组以database.table格式按完全限定名称匹配表的正则表达式。如果您从
data字段省略这个组件，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.2.1.6.4. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，表名称或正则表达式，以匹配要从快照中删除的表名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.table1", "db1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.table1", "db1.table2"], "type": "INCREMENTAL"}}`2.2.1.7. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新表，并在连接器运行时完成快照。
- 您可以添加大表，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个表必须是快照
additional-conditions ：您可以为不同的表指定不同的过滤器。
-
data-collection属性是要应用过滤器的表的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.2.1.8. 接收 Debezium MariaDB 更改事件记录的 Kafka 主题的默认名称
默认情况下，MariaDB 连接器将所有 INSERT、UPDATE 和 DELETE 操作的更改事件写入表中的单个 Apache Kafka 主题，该事件特定于该表。
连接器使用以下惯例命名更改事件主题：
topicPrefix.databaseName.tableName
假设 fulfillment 是主题前缀，inventory 是数据库名称，数据库包含名为 orders, customers, 和 products 的表。Debezium MariaDB 连接器将事件发送到三个 Kafka 主题，一个用于数据库中的每个表：
fulfillment.inventory.orders fulfillment.inventory.customers fulfillment.inventory.products
fulfillment.inventory.orders
fulfillment.inventory.customers
fulfillment.inventory.products以下列表提供了默认名称组件的定义：
- topicPrefix
-
由
topic.prefix连接器配置属性指定的主题前缀。 - schemaName
- 发生操作的模式的名称。
- tableName
- 操作发生的表的名称。
连接器应用类似的命名约定来标记其内部数据库架构历史记录主题、架构更改主题 和事务元数据主题。
如果默认主题名称不满足您的要求，您可以配置自定义主题名称。要配置自定义主题名称，您可以在逻辑主题路由 SMT 中指定正则表达式。有关使用逻辑主题路由 SMT 自定义主题命名的更多信息，请参阅 主题路由。
事务元数据
Debezium 可以生成代表事务边界的事件，以及丰富的数据更改事件消息。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
Debezium 为每个事务中的 BEGIN 和 END 分隔符生成事务边界事件。事务边界事件包含以下字段：
status-
BEGIN或END. id- 唯一事务标识符的字符串表示。
ts_ms-
数据源的事务边界事件(
BEGIN或END事件)的时间。如果数据源没有向 Debezium 提供事件时间，则字段代表 Debezium 处理事件的时间。 event_count（用于END事件）- 事务发出的事件总数。
data_collections（用于END事件）-
一组
data_collection和event_count元素，用于指示连接器为来自数据收集的更改发出的事件数。
示例
除非通过 topic.transaction 选项覆盖，否则连接器会将事务事件发送到 < topic.prefix>.transaction 主题。
更改数据事件增强
当启用事务元数据时，数据消息 Envelope 会增加新的 transaction 字段。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示。
total_order- 事件在事务生成的所有事件间的绝对位置。
data_collection_order- 事件在事务发送的所有事件中的每个数据收集位置。
以下是消息示例：
2.2.2. Debezium MariaDB 连接器数据更改事件的描述
Debezium MariaDB 连接器为每个行级 INSERT、UPDATE 和 DELETE 操作生成数据更改事件。每个事件包含一个键和值。键和值的结构取决于更改的表。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，用户很难处理。要解决这个问题，每个事件都包含其内容的 schema，或者如果您使用 schema registry，消费者可以用来从 registry 获取 schema 的模式 ID。这使得每个事件自包含。
以下框架 JSON 显示了更改事件的基本四部分。但是，如何配置您选择在应用程序中使用的 Kafka Connect 转换器决定了更改事件中的这四个部分的表示。只有在将转换器配置为生成它时，schema 字段才会处于 change 事件中。同样，只有在将转换器配置为生成它时，事件键和事件有效负载才会处于更改事件中。如果您使用 JSON 转换程序，并将其配置为生成所有四个基本更改事件部分，则更改事件具有此结构：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
第一个 |
| 2 |
|
第一个 |
| 3 |
|
第二个 |
| 4 |
|
第二个 |
默认情况下，连接器流将事件记录改为带有与事件原始表相同的名称的主题。请参阅 主题名称。
MariaDB 连接器确保所有 Kafka Connect 模式名称都遵循 Avro 模式名称格式。这意味着逻辑服务器名称必须以拉丁字母或下划线开头，即 a-z、A-Z 或 _。逻辑服务器名称和表名称中的每个字符都必须是拉丁字母、数字或下划线，即 a-z、A-Z、0-9 或 _。如果存在无效的字符，它将被一个下划线字符替代。
如果逻辑服务器名称、数据库名称或表名称包含无效字符，则这可能会导致意外冲突，并且区分名称的唯一字符无效，因此用下划线替换。
更多详情位于以下主题中：
2.2.2.1. 关于 Debezium MariaDB 更改事件中的键
更改事件的密钥包含更改表键和更改行的实际键的 schema。在连接器创建事件时，schema 及其对应有效负载都包含更改表的 PRIMARY KEY （或唯一约束）中每个列的字段。
请考虑以下 customers 表，后面是此表的更改事件关键示例。
捕获 customer 表更改的每个更改事件都有相同的事件关键模式。只要 customers 表有以前的定义，可以捕获 customer 表更改的事件都有以下关键结构：在 JSON 中，类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
键的 schema 部分指定一个 Kafka Connect 模式，它描述了键的 |
| 2 |
|
定义键有效负载结构的 schema 名称。这个模式描述了更改的表的主密钥的结构。Key 模式名称的格式是 connector-name.database-name.table-name.
|
| 3 |
|
指明事件键是否在其 |
| 4 |
|
指定 |
| 5 |
|
包含生成此更改事件的行的密钥。在本例中，键包含一个 |
2.2.2.2. 关于 Debezium MariaDB 更改事件中的值
更改事件中的值比键复杂一些。与键一样，值也有一个 schema 部分和一个 payload 部分。schema 部分包含描述 payload 部分的 Envelope 结构的 schema，包括其嵌套字段。更改创建、更新或删除数据的操作的事件，它们都有带有 envelope 结构的值 payload。
考虑用于显示更改事件键示例相同的示例表：
此表更改更改事件的值部分描述如下：
创建 事件
以下示例显示了一个更改事件的值部分，连接器为在 customer 表中创建数据的操作生成的更改事件的值部分：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 值的 schema，它描述了值有效负载的结构。在连接器为特定表生成的更改事件时，更改事件的值 schema 都相同。 |
| 2 |
|
在 |
| 3 |
|
|
| 4 |
|
|
| 5 |
|
值的实际数据。这是更改事件提供的信息。 |
| 6 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中，
|
| 7 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 8 |
|
指定事件发生前行状态的可选字段。当 |
| 9 |
|
指定事件发生后行状态的可选字段。在本例中， |
| 10 |
| 描述事件源元数据的强制字段。此字段包含可用于将此事件与其他事件进行比较的信息，以及事件的来源、发生事件的顺序以及事件是否是同一事务的一部分。源元数据包括：
|
更新 事件
示例 customers 表中一个更新的改变事件的值有与那个表的 create 事件相同的模式。同样，事件值的有效负载具有相同的结构。但是，事件值 payload 在更新 事件中包含不同的值。以下是当连接器在 customers 表中为更新生成的更改事件值的示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行状态的可选字段。在 update 事件值中， |
| 2 |
|
指定事件发生后行状态的可选字段。您可以比较 |
| 3 |
|
描述事件源元数据的强制字段。
|
| 4 |
|
描述操作类型的强制字符串。在 update 事件值中， |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 6 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 7 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新行主/唯一键的列会更改行键的值。当密钥更改时，Debezium 会输出 三个 事件：一个 DELETE 事件和一个带有行的旧键的 tombstone 事件，后跟一行的新键的事件。详情位于下一节中。
主密钥更新
更改行的主键字段的 UPDATE 操作被称为主键更改。对于主键更改，在 UPDATE 事件记录中，连接器为旧键发出 DELETE 事件记录，并为新(updated)键发出 CREATE 事件记录。这些事件具有常见的结构和内容，另外，每个事件都有一个与主键更改相关的消息标头：
-
DELETE事件记录具有__debezium.newkey作为消息标头。此标头的值是更新行的新主键。 -
CREATE事件记录具有__debezium.oldkey作为消息标头。此标头的值是更新行具有的上一个（折叠）主键。
删除 事件
delete 更改事件中的值与为同一表的 create 和 update 事件相同的 schema 部分。示例 customer 表的 delete 事件中 payload 部分类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行的状态的可选字段。在一个 delete 事件值中， |
| 2 |
|
可选字段，用于指定事件发生后行的状态。在一个 delete 事件值中， |
| 3 |
|
描述事件源元数据的强制字段。在一个 delete 事件值中，
|
| 4 |
|
描述操作类型的强制字符串。 |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 6 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 7 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
删除 更改事件记录为消费者提供处理删除此行所需的信息。包含了旧值，因为有些用户可能需要它们才能正确处理删除。
MariaDB 连接器事件设计为使用 Kafka 日志压缩。日志压缩支持删除一些旧的信息，只要至少保留每个密钥的最新消息。这可让 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
tombstone 事件
删除行时，delete 事件值仍可用于日志压缩，因为 Kafka 您可以删除具有相同键的所有之前信息。但是，为了使 Kafka 删除具有相同键的所有信息，消息值必须是 null。为了实现此目的，在 Debezium MariaDB 连接器发出 delete 事件后，连接器会发出一个特殊的 tombstone 事件，它具有相同的键但一个 null 值。
截断 事件
truncate 更改事件信号，提示表已被截断。truncate 事件的消息键为 null。message 值类似以下示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述事件源元数据的强制字段。在 truncate 事件值中，
|
| 2 |
|
描述操作类型的强制字符串。 |
| 3 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 4 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 5 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
如果单个 TRUNCATE 语句应用到多个表，则会为每个删节的表发出一个 truncate 更改事件记录。
truncate 事件表示应用到整个表的更改，它没有消息键。在跨越多个分区的主题中，无法保证应用到整个表的更改事件的顺序。也就是说，没有对 的排序保证(创建、更新 等等)，或者针对该表的 truncate 事件。当消费者从不同分区读取事件时，它只能在从第二个分区读取同一表后从一个分区读取表 的更新 事件。
2.2.3. Debezium MariaDB 连接器如何映射数据类型
Debezium MariaDB 连接器代表对带有类似行表的事件行的更改。事件包含每个列值的一个字段。该列的 MariaDB 数据类型指定 Debezium 如何代表事件中的值。
将字符串存储在 MariaDB 中带有字符集和 collation 的列。在读取 binlog 事件中的列值的二进制表示时，MariaDB 连接器使用列的字符集。
连接器可以将 MariaDB 数据类型映射到 字面 和 语义 类型。
- literal type ：如何使用 Kafka Connect 模式类型来表示值。
- 语义类型 ： Kafka Connect 模式如何捕获字段的含义（架构名称）。
如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。
详情包括在以下部分中：
基本类型
下表显示了连接器如何映射基本 MariaDB 数据类型。
| MariaDB 类型 | 字面类型 | 语义类型 |
|---|---|---|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
精度仅用于确定存储大小。精度 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/a |
|
|
|
N/a |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/A |
|
|
|
N/a |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/A |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
临时类型
排除 TIMESTAMP 数据类型，MariaDB temporal 类型取决于 time.precision.mode 连接器配置属性的值。对于 TIMESTAMP 列，它的默认值被指定为 CURRENT_TIMESTAMP 或 NOW，值 1970-01-01 00:00:00 被用于 Kafka Connect schema 中的默认值。
MariaDB 允许 DATE、DATETIME 和 TIMESTAMP 列为零值，因为有时首选使用零值而不是 null 值。当列定义允许 null 值时，MariaDB 连接器代表零值作为 null 值，或者在列不允许 null 值时作为 epoch 天。
没有时区的临时值
DATETIME 类型代表本地日期和时间，如 "2018-01-13 09:48:27"。正如您所见，没有时区信息。这些列使用 UTC 根据列的精度转换为 epoch 毫秒或微秒。TIMESTAMP 类型代表一个没有时区信息的时间戳。当从 UTC 写入服务器（或会话）到当前时区时，它由 MariaDB 转换，在读取该值时从 UTC 写入服务器（或会话）当前时区。例如：
-
DATETIME，值为2018-06-20 06:37:03变为1529476623000。 -
TIMESTAMP的值2018-06-20 06:37:03变为2018-06-20T13:37:03Z。
这些列根据服务器（或会话）当前时区，在 UTC 中转换为对应的 io.debezium.time.ZonedTimestamp。默认情况下，将从服务器查询时区。
运行 Kafka Connect 和 Debezium 的 JVM 的时区不会影响这些转换。
有关与临时值相关的属性的更多详细信息，请参阅 MariaDB 连接器配置属性的 文档。
- time.precision.mode=adaptive_time_microseconds(default)
MariaDB 连接器根据列的数据类型定义决定字面类型和语义类型，以便事件准确表示数据库中的值。所有时间字段都以微秒为单位。只有
00:00:00.000000到23:59:59.999999范围内的正TIME字段值才能正确捕获。Expand 表 2.40. Mappings when time.precision.mode=adaptive_time_microseconds MariaDB 类型 字面类型 语义类型 DATEINT32io.debezium.time.Date
代表自时期起的天数。TIME[(M)]INT64io.debezium.time.MicroTime
代表时间值（微秒），且不包括时区信息。MariaDB 允许M在0-6范围内。DATETIME, DATETIME(0), DATETIME(1), DATETIME(2), DATETIME(3)INT64io.debezium.time.Timestamp
代表超过 epoch 的毫秒数，不包括时区信息。DATETIME(4), DATETIME(5), DATETIME(6)INT64io.debezium.time.MicroTimestamp
代表过去 epoch 的微秒数，不包括时区信息。- time.precision.mode=connect
MariaDB 连接器使用定义的 Kafka Connect 逻辑类型。这种方法的精确度低于默认方法，如果数据库列的比例大于
3，则事件可能不太 精确。只能处理00:00:00.000到23:59:59.999范围的值。只有在确保表中的TIME值永远不会超过支持的范围时，才设置time.precision.mode=connect。预计在以后的 Debezium 版本中会删除connect设置。Expand 表 2.41. time.precision.mode=connect时的映射 MariaDB 类型 字面类型 语义类型 DATEINT32org.apache.kafka.connect.data.Date
代表自 epoch 起的天数。TIME[(M)]INT64org.apache.kafka.connect.data.Time
代表以微秒为单位的时间值，且不包含时区信息。DATETIME[(M)]INT64org.apache.kafka.connect.data.Timestamp
代表自 epoch 起的毫秒数，且不包含时区信息。
十进制类型
Debezium 连接器根据 decimal.handling.mode 连接器配置属性的设置来处理十进制。
- decimal.handling.mode=precise
Expand 表 2.42. 当 decimal.handling.mode=precise时映射 MariaDB 类型 字面类型 语义类型 NUMERIC[(M[,D])]BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。DECIMAL[(M[,D])]BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。- decimal.handling.mode=double
Expand 表 2.43. Mappings when decimal.handling.mode=double MariaDB 类型 字面类型 语义类型 NUMERIC[(M[,D])]FLOAT64不适用
DECIMAL[(M[,D])]FLOAT64不适用
- decimal.handling.mode=string
Expand 表 2.44. 当 decimal.handling.mode=string时映射 MariaDB 类型 字面类型 语义类型 NUMERIC[(M[,D])]字符串不适用
DECIMAL[(M[,D])]字符串不适用
布尔值
MariaDB 以特定的方式在内部处理 BOOLEAN 值。BOOLEAN 列内部映射到 TINYINT (1) 数据类型。在流过程中创建表时，它使用正确的 BOOLEAN 映射，因为 Debezium 接收原始 DDL。在快照过程中，Debebe 执行 SHOW CREATE TABLE 以获取为 BOOLEAN 和 TINYINT (1) 返回 TINYINT (1) 栏的表定义。然后 Debezium 无法获取原始类型映射，因此映射到 TINYINT (1)。
为了允许您将源列转换为布尔值数据类型，Debebe 提供了一个 TinyIntOneTo BooleanConverter 自定义转换器，您可使用以下方法之一使用：
-
将所有
TINYINT (1)或TINYINT (1) UNSIGNED列映射到BOOLEAN类型。 使用以逗号分隔的正则表达式列表枚举列的子集。
要使用这种类型的转换，您必须使用selector参数设置转换器配置属性，如下例所示：converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.selector=db1.table1.*, db1.table2.column1
converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.selector=db1.table1.*, db1.table2.column1Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意：在某些情况下，当快照执行
SHOW CREATE TABLE时，数据库可能不会显示tinyint的长度，这意味着此转换器不起作用。新选项length.checker可以解决这个问题，默认值为true。禁用length.checker，并指定需要转换为所选属性的列，而不是根据类型转换所有列，如下例所示：converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.length.checker=false boolean.selector=db1.table1.*, db1.table2.column1
converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.length.checker=false boolean.selector=db1.table1.*, db1.table2.column1Copy to Clipboard Copied! Toggle word wrap Toggle overflow
空间类型
目前，Debezium MariaDB 连接器支持以下空间数据类型。
| MariaDB 类型 | 字面类型 | 语义类型 |
|---|---|---|
|
|
|
|
2.2.4. 将 MariaDB 数据映射到替代数据类型的自定义转换器
默认情况下，Debezium MariaDB 连接器为 MariaDB 数据类型提供多个 CustomConverter 实现。这些自定义转换器根据连接器配置为特定数据类型提供替代映射。要在连接器中添加 CustomConverter，请按照 Custom Converters 文档中的 说明进行操作。
TINYINT (1) 用于布尔值
默认情况下，在连接器快照中，Debebe MariaDB 连接器从 JDBC 驱动程序获取列类型，它将 TINYINT (1) 类型分配给 BOOLEAN 列。然后 Debezium 使用这些 JDBC 列类型来定义快照事件的 schema。连接器从快照过渡到 streaming 阶段后，从默认映射中生成的更改事件模式可能会导致 BOOLEAN 列的映射不一致。为了帮助确保 MariaDB 以统一方式发出 BOOLEAN 列，您可以应用自定义 TinyIntOneToBooleanConverter，如以下配置示例所示。
示例： TinyIntOneToBooleanConverter 配置
converters=tinyint-one-to-boolean tinyint-one-to-boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter tinyint-one-to-boolean.selector=.*.MY_TABLE.DATA tinyint-one-to-boolean.length.checker=false
converters=tinyint-one-to-boolean
tinyint-one-to-boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter
tinyint-one-to-boolean.selector=.*.MY_TABLE.DATA
tinyint-one-to-boolean.length.checker=false
在前面的示例中，选择器和 length.checker 属性是可选的。默认情况下，转换器检查 TINYINT 数据类型是否符合 1 的长度。如果 length.checker 为 false，则不会明确地确认 TINYINT 数据类型符合 1 的长度。选择器 根据提供的正则表达式指定要转换的表或列。如果省略 selector 属性，则转换器将所有 TINYINT 列映射到逻辑 BOOL 字段类型。如果您没有配置 选择器 选项，并且您要将 TINYINT 列映射到 TINYINT (1)，请省略 length.checker 属性，或者将其值设为 true。
JDBC sink 数据类型
如果您将 Debezium JDBC sink 连接器与 Debezium MariaDB 源连接器集成，MariaDB 连接器会在快照和流阶段以不同的方式发出一些列属性。要使 JDBC sink 连接器一致消耗快照和流阶段的更改，您必须包含 JdbcSinkDataTypesConverter converter 作为 MariaDB 源连接器配置的一部分，如下例所示：
示例：J dbcSinkDataTypesConverter 配置
在前面的示例中，selectorSetConfiguration 和 treat.real.as.double 配置属性是可选的。
selector SetConfiguration 属性指定以逗号分隔的正则表达式列表，用于指定转换器应用到的表和列。默认情况下，转换器对所有表中的所有布尔值、真实和基于字符串的列数据类型应用以下规则：
-
BOOLEAN数据类型始终作为INT16逻辑类型发送，1代表true，0代表false -
REAL数据类型始终作为FLOAT64逻辑类型发送。 -
基于字符串的列始终包括
__debezium.source.column.character_setschema 参数，其中包含列的字符集。
对于每个数据类型，您可以配置选择器规则来覆盖默认范围，并仅将选择器应用到特定的表和列。例如，要设置布尔值转换器的范围，请将以下规则添加到连接器配置中，如上例中所示： converters.jdbc-sink.selector.boolean=pulpcore.MY_TABLE.BOOL_COL
2.2.5. 设置 MariaDB 以运行 Debezium 连接器
在安装和运行 Debezium 连接器前，需要一些 MariaDB 设置任务。
详情包括在以下部分中：
2.2.5.1. 为 Debezium 连接器创建 MariaDB 用户
Debezium MariaDB 连接器需要一个 MariaDB 用户帐户。这个 MariaDB 用户必须具有 Debezium MariaDB 连接器捕获更改的所有数据库的适当权限。
先决条件
- MariaDB 服务器。
- SQL 命令的基本知识。
流程
创建 MariaDB 用户：
mariadb> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
mariadb> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 为用户授予所需的权限：
mariadb> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';
mariadb> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 有关所需权限的描述，请参考 表 2.46 “用户权限的描述”。
重要如果使用 Amazon RDS 或 Amazon Aurora 等托管选项，不允许全局读取锁定，则使用表级锁定来创建 一致的快照。在这种情况下，您还需要为您创建的用户授予
LOCK TABLES权限。如需了解更多详细信息，请参阅 快照。完成用户权限：
mariadb> FLUSH PRIVILEGES;
mariadb> FLUSH PRIVILEGES;Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.46. 用户权限的描述 关键字 描述 选择启用连接器从数据库中的表选择行。这仅在执行快照时使用。
重新加载启用连接器使用
FLUSH语句来清除或重新载入内部缓存、清除表或获取锁定。这仅在执行快照时使用。显示数据库通过发出
SHOW DATABASE语句来启用连接器查看数据库名称。这仅在执行快照时使用。复制从设备启用连接器连接到并读取 MariaDB 服务器 binlog。
复制客户端启用连接器使用以下语句：
-
显示 MASTER 状态 -
显示从状态 -
SHOW BINARY LOGS
连接器始终需要它。
ON标识应用权限的数据库。
TO 'user'指定要授予权限的用户。
IDENTIFIED BY 'password'指定用户的 MariaDB 密码。
-
2.2.5.2. 为 Debezium 启用 MariaDB binlog
您必须为 MariaDB 复制启用二进制日志记录。二进制日志记录事务更新的方式，使副本能够传播这些更改。
先决条件
- MariaDB 服务器。
- 适当的 MariaDB 用户权限。
流程
-
检查是否启用了
log-bin选项： 如果 binlog 是
OFF，请将下表中的属性添加到 MariaDB 服务器的配置文件中：server-id = 223344 # Querying variable is called server_id, e.g. SELECT variable_value FROM information_schema.global_variables WHERE variable_name='server_id'; log_bin = mariadb-bin binlog_format = ROW binlog_row_image = FULL binlog_expire_logs_seconds = 864000
server-id = 223344 # Querying variable is called server_id, e.g. SELECT variable_value FROM information_schema.global_variables WHERE variable_name='server_id'; log_bin = mariadb-bin binlog_format = ROW binlog_row_image = FULL binlog_expire_logs_seconds = 864000Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 通过再次检查 binlog 状态来确认您的更改：
如果在 Amazon RDS 上运行 MariaDB，则必须为您的数据库实例启用自动备份，以便进行二进制日志记录。如果没有将数据库实例配置为执行自动备份，则禁用 binlog，即使您应用了前面步骤中描述的设置。
Expand 表 2.47. MariaDB binlog 配置属性的描述 属性 描述 server-idserver-id的值对于 MariaDB 集群中的每台服务器和复制客户端必须是唯一的。log_binlog_bin的值是 binlog 文件序列的基本名称。binlog_formatbinlog-format必须设为 ROW或行。binlog_row_imagebinlog_row_image必须设置为FULL或full。binlog_expire_logs_secondsbinlog_expire_logs_seconds对应于已弃用的系统变量expire_logs_days。这是自动 binlog 文件删除的秒数。默认值为2592000，它等于 30 天。设置该值以匹配您的环境需求。如需更多信息，请参阅 MariaDB 清除 binlog 文件。
2.2.5.3. 为 Debezium 启用 MariaDB 全局事务标识符
全局事务标识符(GTID)唯一标识集群中服务器上发生的事务。虽然 Debezium MariaDB 连接器不需要，但使用 GTID 简化了复制，但可让您更轻松地确认主和副本服务器是否一致。
对于 MariaDB，默认启用 GTID，不需要额外的配置。
2.2.5.4. 为 Debezium 配置 MariaDB 会话超时
当为大型数据库生成初始一致的快照时，您建立的连接可能会在读取表时超时。您可以通过在 MariaDB 配置文件中配置 interactive_timeout 和 wait_timeout 来防止此行为。
先决条件
- MariaDB 服务器。
- SQL 命令的基本知识。
- 访问 MariaDB 配置文件。
流程
配置
interactive_timeout：mariadb> interactive_timeout=<duration-in-seconds>
mariadb> interactive_timeout=<duration-in-seconds>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 配置
wait_timeout：mariadb> wait_timeout=<duration-in-seconds>
mariadb> wait_timeout=<duration-in-seconds>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.48. MariaDB 会话超时选项的描述 选项 描述 interactive_timeout服务器在关闭之前在互动连接上等待活动的秒数。如需更多信息，请参阅：
wait_timeout服务器在关闭之前在非互动连接上等待活动的秒数。
2.2.5.5. 为 Debezium MariaDB 连接器启用查询日志事件
您可能希望查看每个 binlog 事件的原始 SQL 语句。在 MariaDB 配置中启用 binlog_annotate_row_events 选项允许您执行此操作。
先决条件
- MariaDB 服务器。
- SQL 命令的基本知识。
- 访问 MariaDB 配置文件。
流程
在 MariaDB 中启用
binlog_annotate_row_events：mariadb> binlog_annotate_row_events=ON
mariadb> binlog_annotate_row_events=ONCopy to Clipboard Copied! Toggle word wrap Toggle overflow binlog_annotate_row_events设置为一个值，它启用对在 binlog 条目中包括原始SQL语句的支持。-
ON= enabled -
OFF= disabled
-
2.2.5.6. 验证 Debezium MariaDB 连接器的 binlog 行值选项
验证数据库中 binlog_row_value_options 变量的设置。要让连接器消耗 UPDATE 事件，此变量必须设置为 PARTIAL_JSON 以外的值。
先决条件
- MariaDB 服务器。
- SQL 命令的基本知识。
- 访问 MariaDB 配置文件。
流程
检查当前变量值
mariadb> show global variables where variable_name = 'binlog_row_value_options';
mariadb> show global variables where variable_name = 'binlog_row_value_options';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 结果
+--------------------------+-------+ | Variable_name | Value | +--------------------------+-------+ | binlog_row_value_options | | +--------------------------+-------+
+--------------------------+-------+ | Variable_name | Value | +--------------------------+-------+ | binlog_row_value_options | | +--------------------------+-------+Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果 变量的值被设置为
PARTIAL_JSON，请运行以下命令来取消设置它：mariadb> set @@global.binlog_row_value_options="" ;
mariadb> set @@global.binlog_row_value_options="" ;Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.2.6. 部署 Debezium MariaDB 连接器
您可以使用以下任一方法部署 Debezium MariaDB 连接器：
2.2.6.1. 使用 Apache Kafka 的 Streams 部署 MariaDB 连接器
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅 OpenShift Container Platform 文档中的管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.11. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium MariaDB 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关脚本引擎。SMT 归档和脚本语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.49. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Red Hat Maven 存储库中提供了 Debezium 连接器工件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需的脚本语言组件
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
作为替代方案，Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为mariadb-inventory-connector.yaml例 2.12.
mariadb-inventory-connector.yaml文件，为 Debezium 连接器定义KafkaConnector自定义资源Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.50. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址。
6
数据库实例的端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
9
连接器的唯一数字 ID。
10
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。11
连接器捕获更改事件的表列表。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f mariadb-inventory-connector.yaml
oc create -n debezium -f mariadb-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
您现在已准备好 验证 Debezium MariaDB 部署。
要部署 Debezium MariaDB 连接器，您必须构建包含 Debezium 连接器存档的自定义 Kafka Connect 容器镜像，然后将此容器镜像推送到容器 registry。然后，您需要创建以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium MariaDB 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- MariaDB 正在运行，您完成了 设置 MariaDB 以使用 Debezium 连接器 的步骤。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka 流。
- podman 或 Docker 已安装。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。
流程
为 Kafka Connect 创建 Debezium MariaDB 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-mariadb.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-mariadb.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-mariadb:latest .
podman build -t debezium-container-for-mariadb:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-mariadb:latest .
docker build -t debezium-container-for-mariadb:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令使用名称
debezium-container-for-mariadb构建容器镜像。将自定义镜像推送到容器 registry，如
quay.io或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：podman push <myregistry.io>/debezium-container-for-mariadb:latest
podman push <myregistry.io>/debezium-container-for-mariadb:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-mariadb:latest
docker push <myregistry.io>/debezium-container-for-mariadb:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium MariaDB
KafkaConnect自定义资源(CR)。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。输入以下命令将
KafkaConnectCR 应用到 OpenShift Kafka Connect 环境：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令添加一个 Kafka Connect 实例，用于指定为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium MariaDB 连接器实例。您可以在
.yaml文件中配置 Debezium MariaDB 连接器，该文件指定连接器的配置属性。连接器配置可能会指示 Debezium 为模式和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略、掩码或截断指定列中的值，这些值是敏感、太大或不需要的。以下示例配置了一个 Debezium 连接器，它连接到 MariaDB 主机
192.168.99.100，在端口3306上，并捕获对inventory数据库的更改。dbserver1是服务器的逻辑名称。MariaDB
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.51. 连接器配置设置的描述 项 描述 1
连接器的名称。
2
只在任何时候只能运行一个任务。由于 MariaDB 连接器读取 MariaDB 服务器的
binlog，因此使用单一连接器任务来确保正确顺序和事件处理。Kafka Connect 服务使用连接器启动一个或多个完成工作的任务，并在 Kafka Connect 服务集群中自动分发正在运行的任务。如果有任何服务停止或崩溃，则这些任务将重新分发到运行的服务。3
连接器的配置。
4
数据库主机，这是运行 MariaDB 服务器的容器的名称(
mariadb)。5
连接器的唯一 ID。
6
MariaDB 服务器或集群的主题前缀。此名称用作接收更改事件记录的所有 Kafka 主题的前缀。
7
连接器只捕获
inventory表中的更改。8
此连接器将用于写入和恢复 DDL 语句的 Kafka 代理列表到数据库 schema 历史记录主题。重启后，当连接器应开始读取时，连接器会在 binlog 中一次恢复存在的数据库模式。
9
数据库架构历史记录主题的名称。本主题仅用于内部使用，不应供消费者使用。
使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的inventory数据库运行。
有关您可以为 Debezium MariaDB 连接器设置的配置属性的完整列表，请参阅 MariaDB 连接器配置属性。
结果
连接器启动后，它会对配置了连接器的 MariaDB 数据库 执行一致的快照。然后，连接器开始为行级操作生成数据更改事件，并将更改事件记录流传输到 Kafka 主题。
2.2.6.4. 验证 Debezium MariaDB 连接器是否正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，点您要检查的连接器名称，如 inventory-connector-mariadb。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-mariadb -n debezium
oc describe KafkaConnector inventory-connector-mariadb -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.13.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，单击要检查的主题的名称，例如
inventory-connector-mariadb.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.14.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-mariadb.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-mariadb.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中返回
的格式相同，如inventory-connector-mariadb.inventory.addresses。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.15. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-mariadb.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mariadb.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mariadb.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.mariadb.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-mariadb.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"mariadb","name":"inventory-connector-mariadb","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"mariadb-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-mariadb.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mariadb.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mariadb.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.mariadb.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-mariadb.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"mariadb","name":"inventory-connector-mariadb","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"mariadb-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
2.2.6.5. Debezium MariaDB 连接器配置属性的描述
Debezium MariaDB 连接器有许多配置属性，可用于为应用程序获得正确的连接器行为。许多属性具有默认值。有关属性的信息按如下方式进行组织：
- 所需的连接器配置属性
- 高级连接器配置属性
- 数据库架构历史记录连接器配置属性，用于控制 Debezium 如何处理从数据库架构历史记录主题读取的事件。
所需的 Debezium MariaDB 连接器配置属性
除非默认值可用 ， 否则需要以下配置属性。
bigint.unsigned.handling.mode
默认值 ：
指定连接器如何代表更改事件中的 BIGINT UNSIGNED 列。设置以下选项之一：long-
使用 Java
长数据类型来代表 BIGINT UNSIGNED 列值。虽然长类型不提供最大精度，但在大多数消费者中很容易实现。在大多数环境中，这是首选设置。 precise-
使用
java.math.BigDecimal数据类型来表示值。连接器使用 Kafka Connectorg.apache.kafka.connect.data.Decimal数据类型来代表编码的二进制格式的值。如果连接器通常与大于 2^63 的值一起使用，则设置这个选项。长数据类型无法传递该大小的值。
binary.handling.mode默认值：
bytes
指定连接器如何代表二进制列的值，如blob、二进制、varbinary、更改事件。
设置以下选项之一：bytes- 将二进制数据表示为字节数组。
base64- 将二进制数据表示为 base64 编码的字符串。
base64-url-safe- 将二进制数据表示为 base64-url-safe-encoded String。
hex- 将二进制数据表示为十六进制编码(base16)字符串。
column.exclude.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与要从更改事件记录值中排除的列的完全限定名称匹配。源记录中的其他列会正常捕获。列的完全限定域名格式为 databaseName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。如果您在配置中包含此属性，不要设置
column.include.list属性。
column.include.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，该表达式与要包含在更改事件记录值中的列的完全限定名称匹配。事件记录中省略了其他列。列的完全限定域名格式为 databaseName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。
如果您在配置中包含此属性，请不要设置column.exclude.list属性。
column.mask.hash.v2.hashAlgorithm.with.salt.salt默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与基于字符的列的完全限定域名匹配。列的完全限定域名格式为 <databaseName> . <tableName & gt; . <columnName>。
要匹配 Debezium 的名称，请使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。在生成的更改事件记录中，指定列的值将被 pseudonyms 替代。
pseudonym 由一个散列值组成，结果是应用指定的 hashAlgorithm 和 salt 的结果。根据使用的 hash 功能，引用完整性会被维护，而列值则替换为 pseudonyms。Java 加密架构标准算法 文档的 MessageDigest 部分中 描述了支持的哈希功能。
在以下示例中，
CzQMA0cB5K是一个随机选择的 salt。column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName
column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerNameCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如有必要，pseudonym 会自动缩短到列的长度。连接器配置可以包含多个属性，以指定不同的哈希算法和 salt。
根据使用的 hashAlgorithm，所选的 salt 和实际数据集，可能无法完全屏蔽。
哈希策略版本 2 可确保在不同位置或系统中哈希的值。
column.mask.with.length.chars默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与基于字符的列的完全限定域名匹配。如果您希望连接器屏蔽一组列的值，例如，如果它们包含敏感数据，则设置此属性。将length设置为一个正整数，替换在属性名称中的 length 指定的星号（*）的数量列中的数据。将 length 设置为0(zero)，将指定列中的数据替换为空字符串。列的完全限定域名观察以下格式： databaseName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。
您可以在单个配置中指定多个长度不同的属性。
column.propagate.source.type默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与您希望连接器发送代表列元数据的额外参数匹配。当设置此属性时，连接器将以下字段添加到事件记录的 schema 中：-
__debezium.source.column.type -
__debezium.source.column.length -
__debezium.source.column.scale
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
启用连接器来发送此额外数据有助于在 sink 数据库中正确调整特定数字或基于字符的列。
列的完全限定域名观察以下格式之一： databaseName.tableName.columnName, 或 databaseName.schemaName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。
-
column.truncate.to.length.chars默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与基于字符的列的完全限定域名匹配。如果在列中的数据超过了在属性名中的 length 指定的字符长度时删节数据，设置此属性。将length设置为正整数值，例如column.truncate.to.20.chars。列的完全限定域名观察以下格式： databaseName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。
您可以在单个配置中指定多个长度不同的属性。
connect.timeout.ms-
默认值 ：
30000(30 秒)
一个正整数值，用于指定连接器在连接请求超时前等待与 MariaDB 数据库服务器建立连接的最长时间，以毫秒为单位。
connector.class-
默认值： No default
连接器的 Java 类的名称。始终为 MariaDB 连接器指定。
database.exclude.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与您不想连接器捕获更改的数据库名称匹配。连接器捕获任何没有在database.exclude.list中命名的数据库中的更改。
要匹配数据库的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与数据库的整个名称字符串匹配；它不匹配数据库名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置database.include.list属性。
database.hostname-
默认值 ：没有默认值
MariaDB 数据库服务器的 IP 地址或主机名。
database.include.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与连接器捕获更改的数据库名称匹配。连接器不会捕获名称不在database.include.list的任何数据库中的更改。默认情况下，连接器捕获所有数据库中的更改。
要匹配数据库的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与数据库的整个名称字符串匹配；它不匹配数据库名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置database.exclude.list属性。
database.password-
默认值 ：没有默认值
连接器用来连接到 MariaDB 数据库服务器的 MariaDB 用户的密码。
database.port-
默认值：
3306
整数 MariaDB 数据库服务器的端口号。
database.server.id-
默认值 ：没有默认值
此数据库客户端的数字 ID。指定 ID 必须在 MariaDB 集群中所有当前运行的数据库进程之间唯一。要让它读取 binlog，连接器使用此唯一 ID 将 MariaDB 数据库集群作为其他服务器加入。
database.user-
默认值 ：没有默认值
连接器用来连接到 MariaDB 数据库服务器的 MariaDB 用户的名称。
decimal.handling.mode默认值 ：
精确
指定连接器如何处理更改事件中的DECIMAL和NUMERIC字段的值。
设置以下选项之一：precise（默认）-
以二进制形式使用
java.math.BigDecimal值来精确表示值。 double-
使用
双数据类型表示值。这个选项可能会导致精度丢失，但大多数消费者更易于使用。 string- 将值编码为格式化字符串。这个选项易于使用，但可能会导致实际类型丢失语义信息。
event.deserialization.failure.handling.mode默认值 ：
fail
指定连接器在 binlog 事件反序列化过程中如何响应异常。这个选项已弃用，请使用event.processing.failure.handling.mode选项。fail- 传播异常，表示有问题的事件及其 binlog 偏移，并导致连接器停止。
warn- 记录有问题的事件及其 binlog 偏移，然后跳过事件。
ignore- 传递有问题的事件，不会记录任何内容。
field.name.adjustment.mode默认值： No default
指定应该如何调整字段名称，以便与连接器使用的消息转换器兼容。设置以下选项之一：none- 无调整。
avro- 使用下划线字符替换在 Avro 名称中无效的字符。
avro_unicode将 Avro 名称中无法使用的下划线字符或字符替换为对应的 unicode，如
_uxxxx。
注意`_` is an escape sequence, similar to a backslash in Java
`_` is an escape sequence, similar to a backslash in JavaCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如需更多信息，请参阅： Avro 命名。
gtid.source.excludes-
默认值 ：没有默认值
以逗号分隔的正则表达式列表，该表达式与 GTID 集中的源域 ID 匹配，连接器用来查找 MariaDB 服务器上的 binlog 位置。当设置此属性时，连接器只使用具有与任何指定排除模式不匹配的源 UUID 的 GTID 范围。
要匹配 GTID 的值，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 GTID 的域标识符匹配。
如果您在配置中包含此属性，不要同时设置gtid.source.includes属性。
gtid.source.includes-
默认值 ：没有默认值
以逗号分隔的正则表达式列表，该表达式与用于连接器用来查找 MariaDB 服务器上的 binlog 集合中的源域 ID 匹配。当设置此属性时，连接器只使用具有与其中一个包括模式匹配的源 UUID 的 GTID 范围。
要匹配 GTID 的值，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 GTID 的域标识符匹配。
如果您在配置中包含此属性，不要同时设置gtid.source.excludes属性。
include.query-
默认值：
false
布尔值指定连接器是否应该包含生成更改事件的原始 SQL 查询。
如果将此选项设置为true，那么您还必须将 MariaDB 设置为 true，并将binlog_annotate_row_events选项设置为ON。当include.query为true时，对快照进程生成的事件不存在查询。
将include.query设置为true可能会公开通过在更改事件中包含原始 SQL 语句来明确排除或屏蔽的表或字段。因此，默认设置为false。
有关配置数据库为每个日志事件返回原始SQL语句的更多信息，请参阅启用查询日志事件。
include.schema.changes-
默认值：
true
布尔值指定连接器是否将数据库 schema 发生的更改发布到带有数据库服务器 ID 名称的 Kafka 主题。连接器捕获的每个架构更改事件都使用一个键，其中包含数据库名称和一个包括描述更改的 DDL 语句的值。此设置不会影响连接器记录其内部数据库架构历史记录中的模式更改的方式。
include.schema.comments默认值：
false
布尔值指定连接器是否解析并发布元数据对象上的表和列注释。
注意当您将这个选项设置为
true时，连接器包含的 schema 注释可为每个 schema 对象添加大量字符串数据。增加逻辑模式对象的数量和大小会增加连接器使用的内存量。
inconsistent.schema.handling.mode默认值 ：
fail
指定连接器如何响应 binlog 事件，这些事件引用内部模式表示中不存在的表。也就是说，内部表示与数据库不一致。
设置以下选项之一：fail- 连接器会抛出一个报告有问题的事件及其 binlog 偏移的异常。然后，连接器会停止。
warn- 连接器会记录有问题的事件及其 binlog 偏移，然后跳过事件。
skip- 连接器跳过有问题的事件，且不会在日志中报告它。
message.key.columns-
默认值 ：没有默认值
一个表达式列表，用于指定连接器用来组成自定义消息键，用于更改它发布到指定表的 Kafka 主题的事件记录。
默认情况下，Debebe 使用表的主键列作为发出的记录的消息键。使用默认键，或者为缺少主密钥的表指定一个键，您可以根据一个或多个列配置自定义消息密钥。
要为表建立自定义消息密钥，请列出表，后跟要用作消息键的列。每个列表条目都采用以下格式：
<fully-qualified_tableName> : & lt;keyColumn>, <keyColumn>
To base a table key on multiple column name, insert commas between the column name.
每个完全限定表名称都是以下格式的正则表达式：
<databaseName> . & lt;tableName>
属性可以包含多个表的条目。使用分号分隔列表中的表条目。
以下示例为表inventory.customers和purchase.orders设置了消息键：inventory.customers:pk1,pk2; (configured).purchaseorders:pk3,pk4
用于表inventory.customer，列pk1和pk2指定为消息键。对于任何数据库中的purchaseorders表，列pk3和pk4服务器作为消息键。
对用来创建自定义消息键的列数量没有限制。但是，最好使用指定唯一密钥所需的最小数量。
name-
默认值 ：连接器没有默认值
唯一名称。如果您试图使用相同的名称注册另一个连接器，注册会失败。所有 Kafka Connect 连接器都需要此属性。
schema.name.adjustment.mode默认值 ： No default
指定连接器如何调整 schema 名称，以便与连接器使用的消息转换器兼容。设置以下选项之一：none- 无调整。
avro- 使用下划线字符替换在 Avro 名称中无效的字符。
avro_unicode-
将 Avro 名称中无法使用的下划线字符或字符替换为对应的 unicode，如
_uxxxx。
注意：_是一个转义序列，类似于 Java 中的反斜杠
skip.messages.without.change-
默认值：
false
指定当连接器没有检测包含列中的更改时，连接器是否为记录发出信息。如果列.include.list 中列出了列，或者未列在column.exclude.list中，则这些列将被视为包含true以防止连接器在包含列中没有更改时捕获记录。
table.exclude.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与您不希望连接器捕获更改的表的完全限定表标识符匹配。连接器捕获table.exclude.list中没有包括的任何更改。每个标识符都是 databaseName.tableName 的形式。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置table.include.list属性。
table.include.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与您要捕获的表的完全限定表标识符匹配。连接器不会捕获表.include.list中不包含的任何表中的更改。每个标识符都是 databaseName.tableName 的形式。默认情况下，连接器捕获从其中配置为捕获更改的每个数据库中的所有非系统表中的更改。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置table.exclude.list属性。
tasks.max-
默认值：
1
为此连接器创建的最大任务数。由于 MariaDB 连接器始终使用单个任务，所以更改默认值无效。
time.precision.mode默认值 ：
adaptive_time_microseconds
指定连接器用来表示时间、日期和时间戳值的精度类型。设置以下选项之一：
adaptive_time_microseconds(default)-
连接器会捕获数据库中日期、日期时间和时间戳值，使用 millisecond、microsecond 或 nanosecond 精度值（基于数据库列的类型），但 TIME 类型字段除外，它们始终捕获为微秒。
connect- 连接器总是使用 Kafka Connect 的内置表示 Time, Date, 和 Timestamp 代表时间和时间戳的值，无论数据库列的精度是什么。
tombstones.on.delete默认值：
true
指定 delete 事件是否后跟一个 tombstone 事件。删除源记录后，连接器可以发出 tombstone 事件（默认行为），使 Kafka 能够完全删除与已删除行的密钥相关的所有事件，以防为主题启用了 日志压缩。设置以下选项之一：
true（默认）-
连接器通过发出 delete 事件和后续的 tombstone 事件来代表删除操作。
false-
连接器只发出 删除 事件。
topic.prefix默认值 ：没有 default
主题前缀，为 Debezium 捕获更改的特定 MariaDB 数据库服务器或集群提供命名空间。因为主题前缀用于命名接收此连接器发出的事件的所有 Kafka 主题，所以主题前缀在所有连接器中都是唯一的。值只能包含字母数字字符、连字符、句点和下划线。
警告设置此属性后，请勿更改其值。如果您更改了值，在连接器重启后，而不是继续向原始主题发送事件，连接器会向名称基于新值的主题发出后续事件。连接器也无法恢复其数据库架构历史记录主题。
高级 Debezium MariaDB 连接器配置属性
以下列表描述了高级 MariaDB 连接器配置属性。这些属性的默认值很少需要更改。因此，您不需要在连接器配置中指定它们。
connect.keep.alive-
默认值：
true
一个布尔值，用于指定是否应使用单独的线程来确保与 MariaDB 服务器或集群的连接保持活动状态。
转换器默认值 ：没有默认值
枚举连接器可以使用的 自定义转换器 实例的符号链接名称列表。
例如，布尔值。
需要此属性才能使连接器使用自定义转换器。
对于您为连接器配置的每个转换器，还必须添加一个.type属性，它指定实现转换器接口的类的完全限定域名。.type属性使用以下格式：
<converterSymbolicName>.type例如，
boolean.type: io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter
boolean.type: io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverterCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如果要进一步控制配置的转换器的行为，您可以添加一个或多个配置参数来将值传递给转换器。要将这些额外的配置参数与转换器关联，请为参数名称添加转换器符号名称作为前缀。
例如，要定义一个
selector参数，用于指定布尔值转换器进程的列子集，请添加以下属性：
boolean.selector=db1.table1.*, db1.table2.column1
boolean.selector=db1.table1.*, db1.table2.column1Copy to Clipboard Copied! Toggle word wrap Toggle overflow
custom.metric.tags-
默认值 ：没有默认值
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如k1=v1,k2=v2
。连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。
database.initial.statements默认值：没有默认值
当 JDBC 连接而不是读取事务日志的连接时要执行的 SQL 语句列表。要将分号指定为 SQL 语句中的字符而不是分隔符，请使用两个分号(;;)。
连接器可以自行决定建立 JDBC 连接，因此此属性是配置会话参数。它不执行 DML 语句。
database.query.timeout.ms-
默认值：
600000(10 分钟)
指定连接器等待查询完成的时间（以毫秒为单位）。将值设为0（零）以删除超时限制。
database.ssl.keystore-
默认值： No default
指定密钥存储文件的位置的可选设置。密钥存储文件可用于客户端和 MariaDB 服务器之间的双向身份验证。
database.ssl.keystore.password-
默认值 ：无默认值
密钥存储文件的密码。仅在配置了database.ssl.keystore时指定密码。
database.ssl.mode默认值 ：
首选
指定连接器是否使用加密连接。可用的设置如下：disabled- 指定使用未加密的连接。
preferred（默认）- 如果服务器支持安全连接，则连接器建立一个加密连接。如果服务器不支持安全连接，连接器会返回使用未加密的连接。
required- 连接器建立一个加密的连接。如果无法建立加密连接，连接器会失败。
verify_ca-
连接器的行为与设置
所需选项时的行为，但它也会根据配置的证书颁发机构(CA)证书验证服务器 TLS 证书。如果服务器 TLS 证书与任何有效的 CA 证书不匹配，则连接器会失败。
verify_identity-
当您设置
verify_ca选项时，连接器的行为与设置 verify_ca 选项一样，它还验证服务器证书是否与远程连接的主机匹配。
database.ssl.truststore-
默认值 ：无默认值
服务器证书验证的信任存储文件的位置。
database.ssl.truststore.password-
默认值 ：无默认值
信任存储文件的密码。用于检查信任存储的完整性，并解锁信任存储。
enable.time.adjuster默认值：
true
布尔值表示连接器是否将 2 位规格转换为 4 位。当转换完全委派给数据库时，将值设为false。
MariaDB 用户可以使用 2 位或 4 位数字插入年值。2 位值映射到970 到 2069 范围内的一年。默认情况下，连接器执行转换。
errors.max.retries默认值：
-1
指定连接器在操作后如何响应导致可重试错误，如连接错误。
设置以下选项之一：-1- 无限制。无论之前失败的数量如何，连接器总是自动重启，并重试操作。
0- disabled。连接器会立即失败，永远不会重试操作。重启连接器需要用户干预。
> 0- 连接器会自动重启，直到达到指定的最大重试次数。下一次失败后，连接器会停止，用户需要干预才能重启它。
event.converting.failure.handling.mode默认值 ：
警告
指定连接器无法转换表记录时如何响应，因为列的数据类型和 Debezium 内部模式指定的类型不匹配。
设置以下选项之一：fail-
一个异常报告，因为字段的数据类型与 schema 类型不匹配，并表示可能需要在
schema _only_recovery模式中重启连接器来启用成功转换。 warn-
连接器将
null值写入失败的列的 event 字段，将消息写入警告日志。
skip-
连接器将
null值写入失败的列的 event 字段，并将消息写入 debug 日志。
event.processing.failure.handling.mode默认值 ：
fail
指定连接器如何处理处理事件时出现的故障，例如，如果它遇到损坏的事件。可用的设置如下：fail- 连接器会引发一个报告有问题的事件及其位置的异常。然后，连接器会停止。
warn- 连接器不会引发异常。相反，它会记录有问题的事件及其位置，然后跳过事件。
ignore- 连接器忽略有问题的事件，且不会生成日志条目。
heartbeat.action.query默认值： No default
指定当连接器发送 heartbeat 信息时，连接器在源数据库上执行的查询。
例如，以下查询会定期捕获源数据库中设置的已执行 GTID 的状态。
INSERT INTO gtid_history_table （选择 @gtid_executed）
heartbeat.interval.ms默认值 ：
0
指定连接器将心跳消息发送到 Kafka 主题的频率。默认情况下，连接器不会发送 heartbeat 信息。
心跳消息可用于监控连接器是否接收来自数据库的更改事件。心跳消息可能会帮助减少连接器重启时需要重新更改事件的数量。要发送心跳消息，请将此属性设置为正整数，这表示心跳消息之间的毫秒数。
incremental.snapshot.allow.schema.changes-
默认值：
false
指定连接器是否允许增量快照中的模式更改。当值设为true时，连接器会在增量快照期间检测到 schema 变化，并重新选择当前块以避免锁定 DDL。
不支持对主密钥的更改。在增量快照期间更改主设备可能会导致结果不正确。另一个限制是，如果模式更改仅影响列的默认值，则不会检测到更改，直到从 binlog 流处理 DDL。这不会影响快照事件的值，但这些快照事件的 schema 可能具有过时的默认值。
incremental.snapshot.chunk.size-
默认值 ：
1024
，连接器在检索增量快照块时获取并读取的最大行数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。
incremental.snapshot.watermarking.strategy默认值：
insert_insert
指定连接器在增量快照期间使用的水位线机制，以重复数据删除可能被增量快照捕获的事件，然后在流恢复后重新捕获。
您可以指定以下选项之一：insert_insert(default)- 当您发送一个信号来启动增量快照时，对于 Debezium 在快照期间读取的每个块，它会将条目写入信号数据收集来记录信号，以打开快照窗口。快照完成后，Debezium 会插入第二个条目，记录信号以关闭窗口。
insert_delete- 当您发送一个信号来启动增量快照时，对于 Debezium 读取的每个块，它会将单个条目写入信号数据收集，以记录信号来打开快照窗口。快照完成后，会删除此条目。不会为关闭快照窗口的信号创建条目。设置这个选项以防止快速增长信号数据收集。
max.batch.size-
默认值：
2048
Positive 整数值，用于指定此连接器每次迭代过程中应该处理的每个批处理事件的最大大小。
max.queue.size-
默认值 ：
8192
一个正整数值，用于指定阻塞队列可以容纳的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将max.queue.size设置为大于max.batch.size的值。
max.queue.size.in.bytes-
默认值 ：
0
一个长整数值，用于指定阻塞队列的最大卷（以字节为单位）。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。
如果也设置了max.queue.size，当队列的大小达到由任一属性指定的限制时，写入队列会被阻断。例如，如果您设置了max.queue.size=1000和max.queue.size.in.bytes=5000，则在队列包含 1000 个记录后写入队列会被阻断，或者在队列中的记录卷达到 5000 字节。
min.row.count.to.stream.results默认值 ：
1000
在快照过程中，连接器会查询将连接器配置为捕获更改的每个表。连接器使用每个查询结果生成读取事件，其中包含该表中所有行的数据。此属性决定 MariaDB 连接器是否将表的结果放在内存中，但速度快，但需要大量内存或流结果，这可能会较慢，但适用于非常大的表。此属性的设置指定表在连接器流结果前必须包含的最小行数。
要跳过所有表大小检查，并且始终在快照中流出所有结果，请
将此属性设置为0。
notification.enabled.channels默认值 ：没有为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
-
sink -
log -
jmx
-
poll.interval.ms-
默认值：
500(0.5 秒)
Positive 整数值，用于指定连接器在开始处理一系列事件前等待新更改事件的毫秒数。
provide.transaction.metadata-
默认值：
false
确定连接器生成带有事务边界的事件，并增强了与事务元数据的更改事件。如果您希望连接器进行此操作，请指定true。如需更多信息，请参阅 事务元数据。
signal.data.collection-
默认值 ：用于向连接器发送信号的数据收集的完全限定名称。https://docs.redhat.com/documentation/en/red_hat_build_of_debezium/2.7.3/html-single/debezium_user_guide/index#debezium-signaling-enabling-source-signaling-channel
使用以下格式指定集合名称：
<databaseName> . < tableName>
signal.enabled.channels默认值 ：对于连接器启用的信号频道名称，没有默认值
列表。默认情况下，以下频道可用：-
source -
kafka -
file -
jmx
-
skipped.operations-
默认值 ：
t
以逗号分隔的操作类型列表，这些类型将在流过程中跳过。操作包括：c用于插入/创建，u用于更新，d表示删除，t代表截断，none不跳过任何操作。默认情况下会跳过截断操作。
snapshot.delay.ms- 默认值 ：在连接器启动时，连接器应在执行快照前等待的时间间隔（以毫秒为单位）。如果您要在集群中启动多个连接器，此属性可用于避免快照中断，这可能会导致连接器重新平衡。
snapshot.fetch.size-
默认值 ： Unset
默认情况下，在快照过程中，连接器会在行批处理中读取表内容。设置此属性以指定批处理中最大行数。
snapshot.include.collection.list-
默认值：
table.include.list中指定的所有表。
一个可选的、以逗号分隔的正则表达式列表，与表的完全限定域名(<databaseName>.<tableName>)匹配，包括在快照中。指定的项目必须在连接器的table.include.list属性中命名。只有在连接器的snapshot.mode属性设置为never以外的值时，此属性才会生效。
此属性不会影响增量快照的行为。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
snapshot.lock.timeout.ms-
默认值：
10000
Positive integer 指定执行快照时等待获取表锁定的最大时间（以毫秒为单位）。如果连接器无法在这个时间段内获取表锁定，则快照会失败。如需更多信息，请参阅
snapshot.locking.mode默认值 ：
最小
指定连接器保存全局 MariaDB 读取锁定的时长，这可防止在连接器执行快照时对数据库进行任何更新。可用的设置如下：Minimal-
连接器只保存全局读锁定，用于读取数据库模式和其他元数据的快照的初始阶段。在快照的下一阶段，连接器会释放锁定，因为它从每个表中选择所有行。要以一致的方式执行 SELECT 操作，连接器使用 REPEATABLE READ 事务。虽然全局读取锁定的发行版本允许其他 MariaDB 客户端更新数据库，但使用 REPEATABLE READ 隔离可确保快照的一致性，因为连接器在事务期间继续读取相同的数据。
extended-
阻止快照持续时间的所有写入操作。如果客户端提交与 MariaDB 中的 REPEATABLE READ 隔离级别不兼容的并发操作，则使用此设置。
none- 防止连接器在快照过程中获取任何表锁定。虽然对所有快照模式都允许这个选项，但只有在 快照运行时没有更改架构时才安全使用。使用 MyISAM 引擎定义的表始终获取表锁定。因此，即使您设置了这个选项，这些表也会被锁定。此行为与获得行级锁的 InnoDB 引擎定义的表不同。
snapshot.max.threads默认值 ：
1
指定连接器执行初始快照时使用的线程数量。要启用并行初始快照，请将 属性设置为大于 1 的值。在并行初始快照中，连接器同时处理多个表。
重要并行初始快照只是一个技术预览功能。红帽不支持开发人员预览软件，且功能完整或生产就绪。不要将开发人员预览软件用于生产环境或关键业务工作负载。开发人员预览软件提供早期对即将推出的产品软件的访问权限，以将其包括在红帽产品产品中。客户可以使用此软件来测试功能并在开发过程中提供反馈。此软件可能随时更改或删除，并且已获得有限的测试。红帽可能会提供在没有关联 SLA 的情况下对开发者预览软件提交反馈的方法。
有关 Red Hat Developer Preview 软件的支持范围的更多信息，请参阅 开发人员预览支持范围。
snapshot.mode默认值：
initial
指定在连接器启动时运行快照的条件。可用的设置如下：always- 连接器在每次启动时都执行快照。快照包括捕获的表的结构和数据。指定此值，每次连接器启动时，使用从捕获的表中数据的完整表示来填充主题。
Initial（默认）- 连接器仅在为逻辑服务器名称记录偏移时运行快照，或者如果它检测到早期快照无法完成。快照完成后，连接器将开始流传输后续数据库更改的事件记录。
initial_only- 只有在逻辑服务器名称没有记录偏移时，连接器才会运行快照。快照完成后，连接器会停止。它不会转换为从 binlog 读取更改事件。
schema_only-
弃用，请参阅
no_data。 no_data- 连接器运行只捕获 schema 的快照，但不运行任何表数据。如果您不需要主题包含数据的一致性快照，但您想要捕获最后一次连接器重启后应用的 schema 更改，则设置这个选项。
schema_only_recovery-
弃用，
请参阅恢复。 recovery设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。
警告如果在上次连接器关闭后将 schema 更改提交到数据库，则不要使用此模式执行快照。
never-
当连接器启动时，而不是执行快照时，它会立即开始为后续数据库更改流事件记录。这个选项考虑将来弃用，而是使用
no_data选项。 when_needed连接器启动后，只有在检测到以下情况之一时才执行快照：
- 它无法检测任何主题偏移。
- 之前记录的偏移量指定了服务器上不可用的 binlog 位置或 GTID。
snapshot.query.mode默认值：
select_all
指定在执行快照时连接器如何查询数据。
设置以下选项之一：select_all（默认）-
连接器使用
select allquery 从捕获的表中检索行，可以选择根据列包含和排除
与使用
snapshot.select.statement.overrides属性相比，此设置可让您以更灵活的方式管理快照内容。
snapshot.select.statement.overrides默认值： No default
指定要包含在快照中的表行。如果您希望快照只包括表中的行的子集，请使用该属性。此属性仅影响快照。它不适用于连接器从日志读取的事件。
属性包含以逗号分隔的完全限定表名称列表，格式为 <databaseName>.<tableName>。例如，
"snapshot.select.statement.overrides": "inventory.products,customers.orders"
对于列表中的每个表，添加一个进一步的配置属性，以指定在生成快照时在表上运行的
SELECT语句。指定的SELECT语句决定了快照中包含的表行子集。使用以下格式指定此SELECT语句属性的名称：
snapshot.select.statement.overrides. <databaseName > . <tableName> 例如：snapshot.select.statement.overrides.customers.orders
来自一个包括软删除栏的customers.orders表，delete_flag，如果您希望快照只包含不是软删除的记录，请添加以下属性："snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM [customers].[orders] WHERE delete_flag = 0 ORDER BY id DESC"
"snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM [customers].[orders] WHERE delete_flag = 0 ORDER BY id DESC"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在生成的快照中，连接器只包含
delete_flag = 0的记录。
snapshot.tables.order.by.row.count默认值 ：
禁用
指定连接器在执行初始快照时处理表的顺序。设置以下选项之一：降序- 连接器快照表按顺序，基于最高到最低的行数。
ascending- 连接器快照表基于从最低到最高的行数。
disabled- 在执行初始快照时，连接器忽略了行数。
streaming.delay.ms-
默认值 ：
0
指定时间（以毫秒为单位），连接器会在完成快照后延迟流过程的启动。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的offset.flush.interval.ms属性的值。
table.ignore.builtin-
默认值：
true
一个布尔值，用于指定是否应忽略内置系统表。无论表 include 和 exclude 列表是什么，都适用。默认情况下，系统表中的值更改不包括在捕获中，Debezium 不会为系统表更改生成事件。
topic.cache.size-
默认值 ：
10000
指定可在绑定的并发散列映射中存储在内存中的主题名称数量。连接器使用缓存来帮助确定与数据收集对应的主题名称。
topic.delimiter-
默认值：
指定连接器在主题名称组件间插入的分隔符。
topic.heartbeat.prefix默认值 ：
_debezium-heartbeat
指定连接器向哪些主题发送 heartbeat 信息的名称。主题名称采用以下格式：
topic.heartbeat.prefix.topic.prefix
例如，如果主题前缀是
fulfillment，则默认主题名称为__debezium-heartbeat.fulfill。
topic.naming.strategy-
默认值：
io.debezium.schema.DefaultTopicNamingStrategy
连接器使用的TopicNamingStrategy类的名称。指定策略决定了连接器如何为数据更改、架构更改、事务、心跳等存储事件记录的主题。
topic.transaction默认值 ：
事务
指定连接器发送事务元数据信息的主题名称。主题名称采用以下模式：
topic.prefix.topic.transaction
例如，如果主题前缀是
fulfillment，则默认主题名称为fulfillment.transaction。
use.nongraceful.disconnect-
默认值：false
一个布尔值，用于指定二进制日志客户端的 keepalive 线程是否将SO_LINGER套接字选项设置为0以立即关闭过时的 TCP 连接。
如果连接器在SSLSocketImpl.close中遇到死锁，请将值设为true。
Debezium 连接器数据库架构历史记录配置属性
Debezium 提供了一组 schema.history.internal.* 属性，用于控制连接器如何与 schema 历史记录主题进行交互。
下表描述了用于配置 Debezium 连接器的 schema.history.internal 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器存储数据库 schema 历史记录的 Kafka 主题的完整名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机/端口对列表。此连接用于检索之前由连接器存储的数据库架构历史记录，以及写入从源数据库读取的每个 DDL 语句。每个对都应该指向 Kafka Connect 进程使用的相同 Kafka 集群。 | |
|
| 整数值，指定连接器在启动/恢复期间应等待的最大毫秒数，同时轮询持久数据。默认值为 100ms。 | |
|
| 指定连接器在使用 Kafka admin 客户端获取集群信息时应等待的最大毫秒数。 | |
|
| 指定连接器在使用 Kafka admin 客户端创建 kafka 历史记录主题时应等待的最大毫秒数。 | |
|
|
连接器在连接器恢复失败前尝试读取持久性历史记录数据的次数上限，并显示错误。没有数据后等待的最长时间是 | |
|
|
指定连接器是否应该忽略不正确的或未知数据库语句的布尔值，或停止处理，以便用户可以解决这个问题。安全默认为 | |
|
|
指定连接器是否记录模式或数据库中所有表的布尔值，或者仅从指定为捕获的表记录。
| |
|
|
指定连接器是否从数据库实例中的所有逻辑数据库记录模式结构的布尔值。
|
直通 MariaDB 连接器配置属性
您可以在连接器配置中设置 pass-through 属性，以自定义 Apache Kafka producer 和 consumer 的行为。有关 Kafka 生成者和消费者的完整配置属性范围的详情，请参考 Kafka 文档。
直通属性，用于配置生成者和消费者客户端如何与 schema 历史记录主题交互
Debezium 依赖于 Apache Kafka producer 将 schema 更改写入数据库 schema 历史记录主题。同样，它依赖于 Kafka 使用者在连接器启动时从数据库 schema 历史记录主题中读取。您可以通过将值分配给一组以 schema.history.internal.producer和 schema.history.internal.consumerPromQL 前缀开头的 pass-through 配置属性来定义 Kafka producer 和 消费者 客户端的配置。pass-through producer 和 consumer 数据库模式历史记录属性控制一系列行为，如这些客户端如何与 Kafka 代理安全连接，如下例所示：
Debezium 在将属性传递给 Kafka 客户端前从属性名称中剥离前缀。
有关 Kafka producer 配置属性和 Kafka 使用者配置属性的更多信息，请参阅 Apache Kafka 文档。
直通属性来配置 MariaDB 连接器如何与 Kafka 信号主题交互
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
为信号频道配置 Kafka 消费者客户端的属性
Debezium 连接器提供信号 Kafka 使用者的直通配置。透传信号属性以 signals.consumer.* 前缀开始。例如，连接器将 signal.consumer.security.protocol=SSL 等属性传递给 Kafka 使用者。
Debezium 在将属性传递给 Kafka 信号消费者前从属性中剥离前缀。
配置 MariaDB 连接器接收器通知频道的直通属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
Debezium 连接器传递数据库驱动程序配置属性
Debezium 连接器提供数据库驱动程序的直通配置。透传数据库属性以前缀 driverPROFILE 开头。例如，连接器将 driver.foobar=false 等属性传递给 JDBC URL。
Debezium 在将属性传递给数据库驱动程序前从属性中剥离前缀。
2.2.7. 监控 Debezium MariaDB 连接器性能
Debezium MariaDB 连接器提供三种类型的指标，除了对 Zookeeper、Kafka 和 Kafka Connect 提供的 JMX 指标的支持外。
Debezium 监控文档 提供了如何使用 JMX 公开这些指标的详细信息。
2.2.7.1. MariaDB 连接器快照和流 MBean 对象的自定义名称
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.16. 自定义标签如何修改连接器 MBean 名称
默认情况下，MariaDB 连接器使用以下 MBean 名称进行流传输指标：
debezium.mariadb:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.mariadb:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.mariadb:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.mariadb:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.2.7.2. 在 MariaDB 数据库快照过程中监控 Debezium
MBean 为 debezium.mariadb:type=connector-metrics,context=snapshot,server= <topic.prefix>。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
连接器还会在执行增量快照时提供以下附加快照指标：
2.2.7.3. 监控 Debezium MariaDB 连接器记录流
Debezium MariaDB 连接器提供三种类型的指标，除了对 Zookeeper、Kafka 和 Kafka Connect 提供的 JMX 指标的支持外。
Debezium 监控文档 提供了如何使用 JMX 公开这些指标的详细信息。
MBean 为 debezium.mariadb:type=connector-metrics,context=streaming,server= <topic.prefix>。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
2.2.7.4. 监控 Debezium MariaDB 连接器模式历史记录
MBean 为 debezium.mariadb:type=connector-metrics,context=schema-history,server= <topic.prefix>。
下表列出了可用的模式历史记录指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
|
| |
|
| 恢复开始的时间（以 epoch 秒为单位）。 | |
|
| 在恢复阶段读取的更改数量。 | |
|
| 恢复和运行时应用的模式更改总数。 | |
|
| 自上次更改从历史记录存储中恢复后经过的毫秒数。 | |
|
| 从上次更改被应用后经过的毫秒数。 | |
|
| 从历史记录存储中恢复最后一次更改的字符串表示。 | |
|
| 最后一次应用更改的字符串表示。 |
2.2.8. Debezium MariaDB 连接器如何处理错误和问题
Debezium 是一个分布式系统，它捕获了多个上游数据库中的所有更改，永远不会丢失或丢失某个事件。当系统正常运行或被仔细管理时，Debezium 会在每次更改事件记录的发送 一次。
如果出现错误，系统不会丢失任何事件。但是，当 Debezium 从错误中恢复时，可能会重复一些更改事件。在这些常规情况下，Debezium （如 Kafka） 至少提供一次 更改事件。
详情包括在以下部分中：
- 配置和启动错误
在以下情况下，连接器会在尝试启动时失败，在日志中报告错误或异常，并停止运行：
- 连接器的配置无效。
- 连接器无法使用指定的连接参数成功连接到 MariaDB 服务器。
- 连接器尝试在 MariaDB 不再有历史记录的 binlog 中的位置重启。
在这些情况下，错误消息详细介绍了此问题，并可能是一个推荐的临时解决方案。在更正配置或解决 MariaDB 问题后，重启连接器。
但是，如果您连接到高度可用的 MariaDB 集群，您可以立即重启连接器。它将连接到集群中的不同 MariaDB 服务器，在服务器 binlog 中找到代表最后一个事务的位置，并开始从该特定位置读取新服务器的 binlog。
- Kafka Connect 正常停止
- 当 Kafka Connect 正常停止时，Debezium MariaDB 连接器任务会在新的 Kafka Connect 进程中停止并重启。
- Kafka Connect 进程崩溃
- 如果 Kafka Connect 崩溃，进程会停止，任何 Debezium MariaDB 连接器任务会终止，而不记录其最近处理的偏移。在分布式模式中，Kafka Connect 在其他进程中重启连接器任务。但是，MariaDB 连接器会从之前进程记录的最后偏移量中恢复。因此，替换任务可能会重新生成在崩溃前处理的一些事件，从而创建重复的事件。
每个更改事件消息都包含可用于识别重复事件的源特定信息，例如：
- 事件源
- MariaDB 服务器的事件时间
- binlog 文件名和位置
- GTID。
- MariaDB 清除 binlog 文件
- 如果 Debezium MariaDB 连接器停止太长，MariaDB 服务器清除旧的 binlog 文件，连接器的最后一个位置可能会丢失。当连接器重启时，MariaDB 服务器不再有起点，连接器会执行另一个初始快照。如果禁用了快照，连接器会失败并显示错误。
有关 MariaDB 连接器如何执行初始 快照的详情，请查看快照。
2.3. MongoDB 的 Debezium 连接器
Debezium 的 MongoDB 连接器跟踪 MongoDB 副本集或 MongoDB sharded 集群，用于记录数据库和集合的更改，将这些更改记录在 Kafka 主题中。连接器会自动处理分片集群中的分片的添加或删除，每个副本集的成员资格更改、每个副本集中的选举，以及等待通信问题的解析。
有关与此连接器兼容的 MongoDB 版本的详情，请参考 Debezium 支持的配置 页面。
使用 Debezium MongoDB 连接器的信息和流程组织如下：
2.3.1. Debezium MongoDB 连接器概述
MongoDB 的复制机制提供冗余和高可用性，是在生产环境中运行 MongoDB 的首选方法。MongoDB 连接器捕获副本集或分片集群中的更改。
MongoDB 副本集 由一组服务器组成，这些服务器都有相同数据的副本，并且复制确保客户端在副本集 主 上记录的所有更改都会正确应用到其他副本集的服务器，称为 secondaries。MongoDB 复制的工作原理是记录其 oplog （或操作日志）中的更改，然后每个第二项都会读取主的 oplog，并应用所有操作到他们自己的文档。当新服务器添加到副本集时，该服务器首先对主上所有数据库和集合执行快照，然后读取主的 oplog，以应用自开始快照后可能所做的所有更改。https://docs.mongodb.com/manual/core/replica-set-sync/当服务器捕获到主 oplog 的尾部时，这个新服务器将变为次要（并能够处理查询）。
2.3.1.1. MongoDB 连接器使用更改流捕获事件记录的描述
虽然 Debezium MongoDB 连接器不会成为副本集的一部分，但它使用类似的复制机制来获取 oplog 数据。主要区别在于连接器不会直接读取 oplog。相反，它会将 oplog 数据的捕获和解码到 MongoDB 更改流 功能。通过更改流，MongoDB 服务器会公开集合中更改作为事件流。Debezium 连接器监控流，然后提供下游更改。当连接器检测到副本集时，它会检查 oplog 以获取最后记录的事务，然后执行主数据库和集合的快照。连接器完成复制数据后，它会创建一个从之前读取的 oplog 位置开始的更改流。
当 MongoDB 连接器处理更改时，它会定期记录事件在 oplog 流中的位置。当连接器停止时，它会记录它处理的最后一个 oplog 流位置，以便重启后它可以从该位置恢复流。换句话说，连接器可以停止、升级或维护，并在以后重启，并始终在不丢失单个事件的情况下准确获取它的位置。当然，MongoDB oplogs 通常以最大大小上限，因此如果连接器长时间停止，则 oplog 中的操作可能会在连接器有机会读取它们前清除。在这种情况下，重启连接器检测到缺少的 oplog 操作，执行快照，然后继续流更改。
MongoDB 连接器也对副本集的成员资格和领导更改、在分片集群中添加或删除分片的改变，以及可能导致通信失败的网络问题。连接器始终使用副本集的主节点来流传输更改，因此当副本集进行选择时，不同的节点会立即停止流传输更改，连接到新的主节点，并使用新的主节点启动流更改。同样，如果连接器无法与副本集主通信，它会尝试重新连接（使用 exponential backoff，以便不破坏网络或副本集）。重新建立连接后，连接器将继续从它捕获的最后事件中更改。这样，连接器会动态调整副本集成员资格更改，并自动处理通信中断。
2.3.1.2. MongoDB 连接器如何使用 MongoDB 读取首选项的描述
您可以通过在 mongodb.connection.string 中设置 readPreference 参数来指定 MongoDB 连接的读取首选项。
2.3.2. Debezium MongoDB 连接器的工作方式
连接器支持的 MongoDB 拓扑概述对规划应用程序非常有用。
以下主题提供有关 Debezium MongoDB 连接器如何工作的详细信息：
- 第 2.3.2.1 节 “Debezium 连接器支持的 MongoDB 拓扑”
- 第 2.3.2.3 节 “Debezium MongoDB 连接器如何为副本集和分片集群使用逻辑名称”
- 第 2.3.2.5 节 “Debezium MongoDB 连接器如何执行快照”
- 第 2.3.2.6 节 “临时快照”
- 第 2.3.2.7 节 “增量快照”
- 第 2.3.2.9 节 “Debezium MongoDB 连接器流如何更改事件记录”
- 第 2.3.2.11 节 “接收 Debezium MongoDB 更改事件记录的 Kafka 主题的默认名称”
- 第 2.3.2.12 节 “Debezium MongoDB 连接器的事件键控制主题分区”
- 第 2.3.2.13 节 “Debezium MongoDB 连接器生成的事件代表事务边界”
2.3.2.1. Debezium 连接器支持的 MongoDB 拓扑
MongoDB 连接器支持以下 MongoDB 拓扑：
- MongoDB 副本集
Debezium MongoDB 连接器可以捕获来自单个 MongoDB 副本集 的更改。生产副本集 至少需要三个成员。
要将 MongoDB 连接器与副本集一起使用，您必须将连接器配置中的
mongodb.connection.string属性的值设置为 副本集连接字符串。当连接器准备好开始捕获来自 MongoDB 更改流的更改时，它会启动一个连接任务。然后，connection 任务使用指定的连接字符串来建立连接。
- MongoDB 分片集群
MongoDB 分片集群 包括：
- 一个或多个 分片，每个分片都部署为副本集；
- 充当 集群配置服务器的独立副本集
客户端需要连接到的一个或多个 routers (也称为
mongos)。它们会将请求路由到相关的分片。要将 MongoDB 连接器与分片集群中一起使用，在连接器配置中，将
mongodb.connection.string属性的值设置为 分片的集群连接字符串。
- MongoDB 独立服务器
- MongoDB 连接器无法监控独立 MongoDB 服务器的更改，因为单机服务器没有 oplog。如果单机服务器转换为一个成员的副本集，则连接器将正常工作。
MongoDB 不建议在生产环境中运行独立服务器。如需更多信息，请参阅 MongoDB 文档。
2.3.2.2. Debezium 连接器所需的用户权限
要从 MongoDB 捕获数据，Debezium 以 MongoDB 用户身份附加到数据库。为 Debezium 创建的 MongoDB 用户帐户需要特定的数据库权限才能从数据库读取。连接器用户需要以下权限：
- 从数据库读取。
-
运行
hello命令。
连接器用户可能还需要以下权限：
-
从
config.shards系统集合中读取。
数据库读取权限
连接器用户必须能够从所有数据库读取，或者是从特定数据库读取，具体取决于连接器的 capture.scope 属性的值。根据 capture.scope 设置，为用户分配以下权限之一：
capture.scope设置为deployment- 授予用户读取任何数据库的权限。
capture.scope设置为database-
授予用户权限来读取连接器的
capture.target属性指定的数据库。 capture.scope设置为collection-
授予用户权限来读取连接器的
capture.target属性指定的集合。
将 Debezium 集合 选项用于 capture.scope 属性是一个开发者技术预览功能。红帽不支持开发人员预览功能，且功能完整或生产就绪。不要将开发人员预览软件用于生产环境或关键业务工作负载。开发人员预览软件提供早期对即将推出的产品软件的访问权限，以将其包括在红帽产品产品中。客户可以使用此软件来测试功能并在开发过程中提供反馈。红帽可能会提供在没有关联 SLA 的情况下对开发者预览软件提交反馈的方法。
有关 Red Hat Developer Preview 软件的支持范围的更多信息，请参阅 开发人员预览支持范围。
使用 MongoDB hello 命令的权限
无论 capture.scope 设置是什么，用户都需要权限来运行 MongoDB hello 命令。
读取 config.shards 集合的权限
根据您的 Debezium 环境，要启用连接器来执行偏移整合，您必须授予连接器用户明确的权限来读取 config.shards 集合。以下连接器环境需要读取 config.shards 集合的权限：
- 从 Debezium 2.5 或更早版本升级的连接器。
- 配置为从分片 MongoDB 集群中捕获更改的连接器。
2.3.2.3. Debezium MongoDB 连接器如何为副本集和分片集群使用逻辑名称
连接器配置属性 topic.prefix 充当 MongoDB 副本集或分片集群的逻辑名称。连接器以多种方式使用逻辑名称： 作为所有主题名称的前缀，并在记录每个副本集的更改流位置时作为唯一标识符。
您应该为每个 MongoDB 连接器提供一个有意义的描述源 MongoDB 系统的唯一逻辑名称。我们建议逻辑名称以字母或下划线字符开头，剩余的字符为字母或下划线。
2.3.2.4. Debezium MongoDB 连接器如何执行偏移整合
Debezium MongoDB 连接器不再支持到分片 MongoDB 部署的 replica_set 连接。因此，使用 replica_set 连接模式的连接器版本记录的偏移量与当前版本不兼容。
为尽量减少连接模式更改的影响，并防止连接器在升级后运行不必要的快照，它会运行流程来整合偏移。在这个偏移合并过程中，连接器完成以下步骤协调早期连接器版本记录的偏移量：
- 由连接器版本超过 2.5 记录的偏移按原样使用。
-
在分片的 MongoDB 部署中捕获的分片连接模式或 MongoDB 副本集部署中的事件的偏移将原样使用。
如果满足以下任一条件，由连接器版本 2.5.x 及更早版本记录的特定于分片的偏移会被原样使用：
- 所有当前数据库分片的偏移量都存在。
-
启用 偏移无效。
如果禁用偏移无效，连接器无法启动。
-
在连接器处理前面步骤中的现有偏移后，它会恢复流更改，然后为它捕获的新事件提交偏移。
如果偏移整合过程没有检测到任何现有偏移，则 连接器将执行初始快照。
2.3.2.5. Debezium MongoDB 连接器如何执行快照
当 Debezium 任务开始使用副本集时，它会使用连接器的逻辑名称和副本集名称来查找用于描述之前停止读取更改的位置的偏移量。如果找到偏移，并且仍然存在于 oplog 中，则任务会立即进行 流传输更改，从记录的偏移位置开始。
但是，如果没有找到偏移量，或者 oplog 不再包含该位置，任务必须首先通过执行快照来获取副本集内容的当前状态。这个过程从记录 oplog 的当前位置并记录为偏移（以及表示快照已启动的标记）开始。然后，该任务会继续复制每个集合，尽可能生成尽可能多的线程（最多到 snapshot.max.threads 配置属性的值），以并行执行此工作。连接器为每个 文档记录一个单独的读取事件。每个读取事件都包含对象的标识符、对象的完整状态，以及查找对象的 MongoDB 副本集 的源 信息。源信息还包含一个标志，表示事件是在快照过程中生成的。
此快照将继续，直到复制了与连接器过滤器匹配的所有集合。如果在任务快照完成前停止连接器，重启连接器后会再次开始快照。
当连接器执行任何副本集的快照时，尝试避免任务重新分配和重新配置。连接器生成日志消息来报告快照的进度。要提供最大的控制，请为每个连接器运行单独的 Kafka Connect 集群。
您可以在以下部分中找到有关快照的更多信息：
| 设置 | 描述 |
|---|---|
|
| 连接器在每次启动时都执行快照。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器启动后，它会执行初始数据库快照。 |
|
| 连接器执行数据库快照。快照完成后，连接器会停止，且不会为后续数据库更改流传输事件记录。 |
|
|
弃用，请参阅 |
|
|
连接器捕获所有相关表的结构，但不创建 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
如需更多信息，请参阅连接器配置属性表中的 snapshot.mode。
2.3.2.6. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供重新捕获集合数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改来捕获不同的集合集。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号集合。您可以通过向 Debezium 信号集合发送信号请求来启动临时快照。
当您启动现有集合的临时快照时，连接器会将内容附加到集合已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的集合。快照可以捕获数据库的全部内容，或者仅捕获数据库中集合的子集。另外，快照也可以捕获数据库中集合的子集。
您可以通过向信号集合发送 execute-snapshot 消息来指定要捕获的集合。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的集合名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| N/A |
包含与快照中包含的集合的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作集合的主键的列名称。 |
触发临时增量快照
您可以通过在信号收集中添加带有 execute-snapshot 信号类型的条目来发起临时增量快照，或者向 Kafka 信号发送信号消息。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个集合的开始和端点。根据集合中条目数量以及配置的块大小，Debezium 会将集合分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号收集或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定集合的快照，遵循它在初始快照中使用的相同进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.3.2.7. 增量快照
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个集合。您可以指定您希望快照捕获 的集合以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debebe 使用水位线来跟踪其进度，维护它捕获的每个集合行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获集合。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，将集合添加到其
collection.include.list属性中。
增量快照过程
当您运行增量快照时，Debebe 会按主密钥对每个集合进行排序，然后根据 配置的块大小 将集合分成块。通过块工作的块，然后捕获块中的每个集合行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改集合记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获包含该行的 READ 事件前修改集合行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一集合行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定集合块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到集合的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
增量快照要求每个表的主键完全排序。因为 String 字段可以包含特殊字符，且受到不同编码的约束，所以基于字符串的主键无法以一致且可预测的顺序排序。在执行增量快照时，最好将主键设置为 String 以外的数据类型。
有关 MongoDB 中 BSON 字符串类型的更多信息，请参阅 MongoDB 文档。
分片集群的增量快照
要将增量快照与分片的 MongoDB 集群一起使用，您必须将 incremental.snapshot.chunk.size 设置为足够高的值，以便 增加更改流管道的复杂性。
2.3.2.7.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号集合。
您可以使用 MongoDB insert （） 方法向信号集合提交信号。
在 Debezium 检测到信号集合中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的集合，并可选择性地指定快照操作类型。目前，快照操作的唯一有效选项是 增量 和 阻止 的。
要指定要包含在快照中的集合，提供一个 data-collections 数组，列出用于匹配集合的集合或一组正则表达式，例如{"data-collections": ["public.Collection1", "public.Collection2"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会检测不需要任何操作，且不会执行快照。
如果要包含在快照中的集合名称在数据库、模式或表名称中包含点(.)，要将集合添加到 data-collections 数组中，您必须使用双引号转义名称的每个部分。
例如，要包含 公共 数据库中存在的数据收集，并且名称为 My.Collection，请使用以下格式：" public"."My.Collection"。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
在信号集合中插入快照信号文档：
<signalDataCollection>.insert({"id" : _<idNumber>,"type" : <snapshotType>, "data" : {"data-collections" ["<collectionName>", "<collectionName>"],"type": <snapshotType>, "additional-conditions" : [{"data-collections" : "<collectionName>", "filter" : "<additional-condition>"}] }});<signalDataCollection>.insert({"id" : _<idNumber>,"type" : <snapshotType>, "data" : {"data-collections" ["<collectionName>", "<collectionName>"],"type": <snapshotType>, "additional-conditions" : [{"data-collections" : "<collectionName>", "filter" : "<additional-condition>"}] }});Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、键入和data参数的值 与信号集合的字段 相对应。下表描述了示例中的参数：
Expand 表 2.57. MongoDB insert （）命令中的字段描述，用于将增量快照信号发送到信号集合 项 值 描述 1
db.debeziumSignal指定源数据库上信号集合的完全限定名称。
2
null
_id参数指定一个任意字符串，它被分配为信号请求的id标识符。
上例中的 insert 方法省略了可选_id参数的使用。由于文档没有为参数明确分配值，因此 MongoDB 自动分配给文档的任意 ID 将变为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号集合中的条目。Debezium 不使用此标识符字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定集合名称或正则表达式数组，以匹配快照中包含的集合名称。
数组列出了通过完全限定名称与集合匹配的正则表达式，其使用与您用来在signal.data.collection配置属性中指定连接器信号集合的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
目前支持incremental和blocking类型。
如果没有指定值，连接器将运行一个增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
additional-conditions数组中的每个元素都是包含以下键的对象：data-collection:: 将应用过滤器的数据收集的完全限定域名。过滤:: 指定必须存在于数据收集记录中的列值，以便快照包含它，例如"color='blue'"。
以下示例显示了连接器捕获的增量快照事件的 JSON。
示例：增加快照事件信息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.3.2.7.2. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.17. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择集合内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果某个 产品 集合带有列 ID （主键）、颜色 和品牌，如果您希望快照只包含 color='blue' 的内容，当您请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 产品 集合，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的产品集合中的内容，您可以发送以下请求：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.3.2.7.3. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的集合发送信号来停止已在运行的快照。
您可以通过将停止快照信号文档插入到信号集合中，向信号集合提交停止快照信号。您提交的 stop 快照信号将快照操作的类型指定为 增量，并且可选指定要从当前运行的快照中省略的集合。在 Debezium 检测到信号集合中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
在信号集合中插入停止快照信号文档：
<signalDataCollection>.insert({"id" : _<idNumber>,"type" : "stop-snapshot", "data" : {"data-collections" ["<collectionName>", "<collectionName>"],"type": "incremental"}});<signalDataCollection>.insert({"id" : _<idNumber>,"type" : "stop-snapshot", "data" : {"data-collections" ["<collectionName>", "<collectionName>"],"type": "incremental"}});Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号集合的字段相对应。下表描述了示例中的参数：
Expand 表 2.59. insert 命令中的字段描述，用于将停止增量快照文档发送到信号集合 项 值 描述 1
db.debeziumSignal指定源数据库上信号集合的完全限定名称。
2
null
上例中的 insert 方法省略了可选
_id参数的使用。由于文档没有为参数明确分配值，因此 MongoDB 自动分配给文档的任意 ID 将变为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号集合中的条目。Debezium 不使用此标识符字符串。3
stop-snapshottype参数指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定集合名称或正则表达式数组，以匹配要从快照中删除的集合名称。
数组列出了正则表达式，该表达式通过其完全限定名称匹配，格式为database.collection。如果您从
data字段中省略data-collections数组，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.3.2.7.4. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，该表数组是集合名称或正则表达式，以匹配要从快照中删除的集合名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.table1", "db1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.table1", "db1.table2"], "type": "INCREMENTAL"}}`2.3.2.8. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新集合，并在连接器运行时完成快照。
- 您可以添加大型集合，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定集合的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个集合必须是快照
additional-conditions ：您可以为不同的集合指定不同的过滤器。
-
data-collection属性是要应用过滤器的集合的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.3.2.9. Debezium MongoDB 连接器流如何更改事件记录
在副本集的连接器任务记录偏移后，它会使用偏移来决定 oplog 中应启动流更改的位置。然后，任务（取决于配置）连接到副本集的主节点，或连接到副本集的更改流，并从那个位置开始流流。它处理所有创建、插入和删除操作，并将它们转换为 Debezium 更改事件。每个更改事件都包含在找到操作的 oplog 中的位置，连接器会定期记录它作为其最新的偏移量。记录偏移的时间间隔由 offset.flush.interval.ms 管理，它是一个 Kafka Connect worker 配置属性。
当连接器安全停止时，会记录最后的偏移量，以便在重启时，连接器将继续完全关闭的位置。如果连接器的任务意外终止，则任务可能会在最后一次记录偏移后处理并生成的事件，但在记录最后一个偏移前；重启时，连接器从上次 记录 偏移开始，可能会生成之前在崩溃之前生成的相同事件。
当 Kafka 管道中的所有组件始终始终正常运行时，Kafka 用户会完全接收每个消息 一次。但是，当出现问题时，Kafka 只能保证消费者 至少接收一次 每个消息。为避免意外的结果，消费者必须能够处理重复的消息。
如前文所述，连接器任务总是使用副本集的主节点从 oplog 中流更改，确保连接器会尽可能看到最新的操作，并可以捕获延迟低于第二个节点的更改。当副本集选择新的主时，连接器会立即停止流更改，连接到新的主节点，并在同一位置开始从新主节点流更改。同样，如果连接器遇到与副本集成员通信的问题，它会尝试使用 exponential backoff 来重新连接，以便不造成副本集，并在连接后继续流传输更改。这样，连接器就可以动态调整副本集成员资格的更改，并自动处理通信失败。
总而言之，MongoDB 连接器可在大多数情况下继续运行。通信问题可能会导致连接器等待问题解决为止。
2.3.2.10. MongoDB 支持在 Debezium 更改事件中填充 before 字段
在 MongoDB 6.0 及更高版本中，您可以配置更改流，以发出文档的预镜像状态，以填充 MongoDB 更改事件的 before 字段。要在 MongoDB 中启用预镜像，您必须使用 db.createCollection(), create, 或 collMod 为集合设置 changeStreamPreAndPostImages。要启用 Debezium MongoDB 在更改事件中包含预镜像，请将连接器的 capture.mode 设置为一个 *_with_pre_image 选项之一。
MongoDB 更改流事件的大小限制为 16MB。因此，使用预镜像会增加超过这个阈值的可能性，这可能会导致失败。有关如何避免超过更改流限制的详情，请参考 MongoDB 文档。
2.3.2.11. 接收 Debezium MongoDB 更改事件记录的 Kafka 主题的默认名称
MongoDB 连接器将所有插入、更新和删除操作的事件写入每个集合中文档到单个 Kafka 主题。Kafka 主题的名称始终使用 logicalName.databaseName.collectionName 格式，其中 logicalName 是连接器的逻辑名称（使用 topic.prefix 配置属性指定），databaseName 是创建发生在的数据库的名称，collectionName 是受影响的文档所在的 MongoDB 集合的名称。
例如，假设一个 MongoDB 副本集有一个 inventory 数据库，其中包含四个集合：products, products_on_hand, customers, 和 orders。如果监控这个数据库的连接器有一个逻辑名称 fulfillment，则这个连接器会在这四个 Kafka 主题上生成事件：
-
fulfillment.inventory.products -
fulfillment.inventory.products_on_hand -
fulfillment.inventory.customers -
fulfillment.inventory.orders
请注意，主题名称不包含副本集名称或分片名称。因此，对分片集合的所有更改（每个分片包含集合文档的子集）都会进入同一 Kafka 主题。
您可以根据需要将 Kafka 设置为自动创建主题。如果没有，则必须在启动连接器前使用 Kafka 管理工具创建主题。
2.3.2.12. Debezium MongoDB 连接器的事件键控制主题分区
MongoDB 连接器不会明确决定如何对事件进行分区。相反，它允许 Kafka 根据事件键决定如何分区主题。您可以通过在 Kafka Connect worker 配置中定义 分区 实现来更改 Kafka 的分区逻辑。
Kafka 只为写入单个主题分区的事件维护总数。按键对事件进行分区意味着所有具有相同键的事件始终进入同一分区。这样可确保特定文档的所有事件始终完全排序。
2.3.2.13. Debezium MongoDB 连接器生成的事件代表事务边界
Debezium 可以生成代表事务元数据边界和丰富的更改数据事件消息的事件。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
对于每个事务 BEGIN 和 END，Debebe 会生成一个包含以下字段的事件：
status-
BEGIN或END id- 唯一事务标识符的字符串表示。
event_count（用于END事件）- 事务发出的事件总数。
data_collections（用于END事件）-
data_collection和event_count的数组，提供源自给定数据收集的更改发出的事件数。
以下示例显示了一个典型的信息：
除非通过 topic.transaction 选项覆盖，否则事务事件将写入名为 <topic. prefix>。
.transaction 的主题
更改数据事件增强
如果启用了事务元数据，数据消息 Envelope 会增加一个新的 transaction 字段。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示。
total_order- 事件在事务生成的所有事件间的绝对位置。
data_collection_order- 事件在事务发送的所有事件中的每个数据收集位置。
以下是消息的一个示例：
2.3.3. Debezium MongoDB 连接器数据更改事件的描述
Debezium MongoDB 连接器为每个文档级操作生成一个数据更改事件，用于插入、更新或删除数据。每个事件包含一个键和值。键的结构和值取决于更改的集合。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，用户很难处理。要解决这个问题，每个事件都包含其内容的 schema，或者如果您使用 schema registry，消费者可以用来从 registry 获取 schema 的模式 ID。这使得每个事件自包含。
以下框架 JSON 显示了更改事件的基本四部分。但是，如何配置您选择在应用程序中使用的 Kafka Connect 转换器决定了更改事件中的这四个部分的表示。只有在将转换器配置为生成它时，schema 字段才会处于 change 事件中。同样，只有在将转换器配置为生成它时，事件键和事件有效负载才会处于更改事件中。如果您使用 JSON 转换程序，并将其配置为生成所有四个基本更改事件部分，则更改事件具有此结构：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
第一个 |
| 2 |
|
第一个 |
| 3 |
|
第二个 |
| 4 |
|
第二个 |
默认情况下，连接器流将事件记录改为带有与事件原始集合相同的名称的主题。请参阅 主题名称。
MongoDB 连接器确保所有 Kafka Connect 模式名称都遵循 Avro 模式名称格式。这意味着逻辑服务器名称必须以拉丁字母或下划线开头，即 a-z、A-Z 或 _。逻辑服务器名称和数据库和集合名称中的每个字符都必须是拉丁字母、数字或下划线，即 a-z、A-Z、0-9 或 \_。如果存在无效的字符，它将被一个下划线字符替代。
如果逻辑服务器名称、数据库名称或集合名称包含无效字符，则这可能会导致意外冲突，并且区分名称的唯一字符无效，因此用下划线替换。
如需更多信息，请参阅以下主题：
2.3.3.1. 关于 Debezium MongoDB 更改事件中的键
更改事件的密钥包含更改文档的密钥和更改文档的实际键的 schema。对于给定集合，schema 及其对应有效负载都包含一个 id 字段。此字段的值是文档的标识符，表示为来自 MongoDB 扩展 JSON 序列化严格模式的字符串。
考虑一个连接器，其逻辑名称为 fulfillment，包括一个 inventory 数据库的副本集，以及包含如下文档的 customers 集合。
文档示例
更改事件键示例
捕获对 customers 集合的更改的每个更改事件都有相同的事件关键模式。只要 customers 集合有以前的定义，捕获 customers 集合更改的事件都有以下关键结构：在 JSON 中，类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
键的 schema 部分指定一个 Kafka Connect 模式，它描述了键的 |
| 2 |
|
定义键有效负载结构的 schema 名称。这个模式描述了更改的文档的密钥结构。Key 模式名称的格式是 connector-name.database-name.collection-name.
|
| 3 |
|
指明事件键是否在其 |
| 4 |
|
指定 |
| 5 |
|
包含生成此更改事件的文档的密钥。在本例中，键包含类型为 |
这个示例使用带有整数标识符的文档，但任何有效的 MongoDB 文档标识符的工作方式相同，包括文档标识符。对于文档标识符，事件键的 payload.id 值是一个字符串，代表更新的文档的原始 _id 字段作为使用严格的模式的 MongoDB 扩展 JSON 序列化。下表提供了如何表示不同类型的 _id 字段的示例。
| 类型 | MongoDB _id 值 | 密钥的有效负载 |
|---|---|---|
| 整数 | 1234 |
|
| 浮点值 | 12.34 |
|
| 字符串 | "1234" |
|
| 文档 |
|
|
| ObjectId |
|
|
| 二进制 |
|
|
2.3.3.2. 关于 Debezium MongoDB 更改事件中的值
更改事件中的值比键复杂一些。与键一样，值也有一个 schema 部分和一个 payload 部分。schema 部分包含描述 payload 部分的 Envelope 结构的 schema，包括其嵌套字段。更改创建、更新或删除数据的操作的事件，它们都有带有 envelope 结构的值 payload。
考虑用于显示更改事件键示例相同的示例文档：
文档示例
每个事件类型描述了更改本文档的更改值部分：
创建 事件
以下示例显示了一个更改事件的值部分，连接器为在 customer 集合中创建数据的操作生成的更改事件值部分：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 值的 schema，它描述了值有效负载的结构。在连接器为特定集合生成的更改事件时，更改事件的值 schema 都相同。 |
| 2 |
|
在 |
| 3 |
|
|
| 4 |
|
|
| 5 |
|
值的实际数据。这是更改事件提供的信息。 |
| 6 |
|
指定事件发生后文档状态的可选字段。在本例中， |
| 7 |
| 描述事件源元数据的强制字段。此字段包含可用于将此事件与其他事件进行比较的信息，以及事件的来源、发生事件的顺序以及事件是否是同一事务的一部分。源元数据包括：
|
| 8 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中，
|
| 9 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 10 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 9 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更改流捕获模式
示例 customers 集合中一个更新的改变事件的值有与那个集合的 create 事件相同的模式。同样，事件值的有效负载具有相同的结构。但是，事件值 payload 在更新 事件中包含不同的值。只有在 capture.mode 选项被设置为 change_streams_update_full 时，update 事件才会包括一个 after 值。如果 capture.mode 选择被设置为 *_with_pre_image 选项之一，会提供一个 before 值。在这种情况下，有一个新的结构化字段 updateDescription，它有几个额外的字段：
-
updatedFields是一个字符串字段，其中包含更新的文档字段的 JSON 表示及其值 -
removedFields是一个从文档中删除的字段名称列表 -
truncatedArrays是已截断的文档中的数组列表
以下是当连接器在 customers 集合中为更新生成的更改事件值的示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中， |
| 2 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 3 |
| 包含更改前实际 MongoDB 文档的 JSON 字符串表示。
如果捕获模式没有设置为 |
| 4 |
|
包含实际 MongoDB 文档的 JSON 字符串表示。 |
| 5 |
|
包含文档更新字段值的 JSON 字符串表示。在本例中，更新会将 |
| 6 |
| 描述事件源元数据的强制字段。此字段包含与同一集合的 create 事件相同的信息，但它们的值不同，因为此事件来自 oplog 中的不同位置。源元数据包括：
|
事件中的 after 值应作为文档的时间点值进行处理。该值不会被动态计算，但是从集合中获取的。因此，如果多个更新一个紧随另一个发生，则所有 update 事件都会包含在文档中存储的代表最后的值相同的 after 值。
如果您的应用程序依赖于逐步更改演进，则应该只依赖 updateDescription。
删除 事件
delete 更改事件中的值与为同一集合的 create 和 update 事件相同的 schema 部分。delete 事件中的 payload 部分包含与为同一集合的 create 和 update 事件不同的值。特别是，delete 事件既不包含 after 值，也不包含 updateDescription 值。以下是 customers 集合中文档的 delete 事件示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述操作类型的强制字符串。 |
| 2 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 3 |
| 包含更改前实际 MongoDB 文档的 JSON 字符串表示。
如果捕获模式没有设置为 |
| 4 |
| 描述事件源元数据的强制字段。此字段包含与同一集合的 create 或 update 事件相同的信息，但它们的值不同，因为此事件来自 oplog 中的不同位置。源元数据包括：
|
MongoDB 连接器事件设计为与 Kafka 日志压缩 一起使用。日志压缩支持删除一些旧的信息，只要至少保留每个密钥的最新消息。这可让 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
tombstone 事件
唯一标识的文档的所有 MongoDB 连接器事件都完全相同。删除文档时，delete 事件值仍可用于日志压缩，因为 Kafka 您可以删除具有相同键的所有之前信息。但是，为了使 Kafka 删除具有该键的所有信息，消息值必须是 null。为了实现此目的，在 Debezium 的 MongoDB 连接器发出 delete 事件后，连接器会发出一个特殊的 tombstone 事件，它具有相同的键但一个 null 值。tombstone 事件会通知 Kafka 删除所有具有相同键的消息。
2.3.4. 设置 MongoDB 以使用 Debezium 连接器
MongoDB 连接器使用 MongoDB 的更改流捕获更改，因此连接器只能用于 MongoDB 副本集，或用于每个分片是单独的副本集的分片集群。有关设置 副本集或 分片集群的信息，请参阅 MongoDB 文档。另外，请确保了解如何使用副本集启用 访问控制和身份验证。
您还必须有一个 MongoDB 用户，它具有适当的角色才能读取 oplog 可以读取的 admin 数据库。此外，用户还必须能够读取分片集群的配置服务器中配置数据库，并且必须具有 listDatabases 特权操作。当使用更改流时（默认），用户还必须具有集群范围的特权操作 find 和 changeStream。
当您打算使用 pre-image 并填充 before 字段时，您需要首先为一个集合启用 changeStreamPreAndPostImages，使用 db.createCollection(), create, 或 collMod。
最佳 Oplog 配置
Debezium MongoDB 连接器读取 更改流，以获取副本集的 oplog 数据。由于 oplog 是一个固定大小，上限的集合，如果超过其最大配置的大小，它开始覆盖其最旧的条目。如果因为任何原因停止连接器，它会在重启时，它会尝试从最后的 oplog 流位置恢复流。但是，如果从 oplog 中删除了最后一个流位置，具体取决于连接器的 snapshot.mode 属性中指定的值，连接器可能无法启动，报告 无效的恢复令牌错误。如果失败，您必须创建新的连接器，以便 Debezium 继续从数据库中捕获记录。如需更多信息，请参阅 如果 snapshot.mode 设为 initial，则连接器在停止了较长的时间间隔后失败。
为确保 oplog 保留 Debezium 恢复流所需的偏移值，您可以使用以下任一方法：
- 增加 oplog 的大小。根据您的典型工作负载，将 oplog 大小设置为一个大于每小时峰值 oplog 条目的值。
- 增加 oplog 条目保留的最短小时数 (MongoDB 4.4 及更高版本)。此设置基于时间，因此保证最后 n 小时中的条目可用，即使 oplog 达到其配置的最大值。虽然这通常是首选选项，但对于具有接近容量高负载的集群，请指定最大 oplog 大小。
为了帮助防止与缺少 oplog 条目相关的故障，跟踪报告复制行为的指标非常重要，并优化 oplog 大小以支持 Debezium。特别是，您应该监控 Oplog GB/Hour 和 Replication Oplog 窗口的值。如果 Debezium 在超过 replication oplog 窗口值的间隔离线，并且主 oplog 增长速度比 Debezium 可以消耗条目快，则连接器失败可能会导致。
有关如何监控这些指标的详情，请查看 MongoDB 文档。
最好将最大 oplog 大小设置为基于 oplog 的每小时增长的值(Oplog GB/Hour)，乘以可能需要解决 Debezium 失败的时间。
也就是说，
Debezium 失败的 oplog GB/Hour X average 反应时间
例如，如果 oplog 大小限制被设置为 1GB，并且 oplog 每小时增长 3GB，则 oplog 条目会每小时清除三次。如果 Debezium 在这段时间内失败，则其最后一个 oplog 位置可能会被删除。
如果 oplog 以 3GB/小时的速度增长，并且 Debezium 在两个小时内离线，您可以将 oplog 大小设置为 3GB/小时 X 2 小时或 6GB。
2.3.5. 部署 Debezium MongoDB 连接器
您可以使用以下任一方法部署 Debezium MongoDB 连接器：
2.3.5.1. 使用 Apache Kafka 的 Streams 部署 MongoDB 连接器
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅在 OpenShift Container Platform 中管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.18. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium MongoDB 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关脚本引擎。SMT 归档和脚本语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.67. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Red Hat Maven 存储库中提供了 Debezium 连接器工件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需的脚本语言组件
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
作为替代方案，Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为mongodb-inventory-connector.yaml例 2.19.
mongodb-inventory-connector.yaml文件，为 Debezium 连接器定义KafkaConnector自定义资源Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.68. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址和端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
8
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。9
连接器从中捕获更改的集合名称。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f mongodb-inventory-connector.yaml
oc create -n debezium -f mongodb-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
您现在已准备好 验证 Debezium MongoDB 部署。
要部署 Debezium MongoDB 连接器，您必须构建包含 Debezium 连接器存档的自定义 Kafka Connect 容器镜像，然后将此容器镜像推送到容器 registry。然后，创建两个自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium MongoDB 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- MongoDB 正在运行，您完成了 设置 MongoDB 以使用 Debezium 连接器 的步骤。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka 流。
- podman 或 Docker 已安装。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。
流程
为 Kafka Connect 创建 Debezium MongoDB 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-mongodb.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-mongodb.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-mongodb:latest .
podman build -t debezium-container-for-mongodb:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-mongodb:latest .
docker build -t debezium-container-for-mongodb:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令使用名称
debezium-container-for-mongodb构建容器镜像。将自定义镜像推送到容器 registry，如
quay.io或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：podman push <myregistry.io>/debezium-container-for-mongodb:latest
podman push <myregistry.io>/debezium-container-for-mongodb:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-mongodb:latest
docker push <myregistry.io>/debezium-container-for-mongodb:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium MongoDB
KafkaConnect自定义资源(CR)。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。输入以下命令将
KafkaConnectCR 应用到 OpenShift Kafka Connect 环境：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令添加一个 Kafka Connect 实例，用于指定为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium MongoDB 连接器实例。您可以在指定连接器的配置属性的
.yaml文件中配置 Debezium MongoDB 连接器。连接器配置可能会指示 Debezium 为 MongoDB 副本集或分片集群的子集生成更改事件。另外，您可以设置过滤不需要的集合的属性。以下示例配置了 Debezium 连接器，该连接器通过
192.168.99.100上的端口27017连接到 MongoDB 副本集rs0，并捕获清单集合中发生的更改。inventory-connector-mongodb是副本集的逻辑名称。
MongoDB
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.69. MongoDB inventory-connector.yaml 示例中的设置描述 项 描述 1
用于在 Kafka Connect 中注册连接器的名称。
2
MongoDB 连接器类的名称。
3
用于连接到 MongoDB 副本集的主机地址。
4
MongoDB 副本集的逻辑名称。逻辑名称形成了生成的事件的命名空间，在使用 Avro converter 时，用于连接器写入的 Kafka 主题的名称、Kafka Connect 模式名称和相应 Avro 模式的命名空间。
5
与要监控的所有集合匹配的正则表达式（如 < dbName>.<collectionName> ）的可选列表。
使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的清单集合运行。
有关您可以为 Debezium MongoDB 连接器设置的配置属性的完整列表，请参阅 MongoDB 连接器配置属性。
结果
连接器启动后，它会完成以下操作：
- 在 MongoDB 副本集中执行集合的一致性快照。
- 读取副本集的更改流。
- 为每个插入、更新和删除文档生成更改事件。
- 流将事件记录改为 Kafka 主题。
2.3.5.4. 验证 Debezium MongoDB 连接器是否正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，点您要检查的连接器名称，如 inventory-connector-mongodb。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-mongodb -n debezium
oc describe KafkaConnector inventory-connector-mongodb -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.20.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，单击要检查的主题的名称，例如
inventory-connector-mongodb.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.21.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-mongodb.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-mongodb.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中返回
的格式相同，例如inventory-connector-mongodb.inventory.addresses。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.22. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-mongodb.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mongodb.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mongodb.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.mongodb.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-mongodb.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"mongodb","name":"inventory-connector-mongodb","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"mongodb-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-mongodb.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mongodb.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mongodb.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.mongodb.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-mongodb.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"mongodb","name":"inventory-connector-mongodb","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"mongodb-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
2.3.5.5. Debezium MongoDB 连接器配置属性的描述
Debezium MongoDB 连接器有许多配置属性，可用于为应用程序获得正确的连接器行为。许多属性具有默认值。有关属性的信息按如下方式进行组织：
除非默认值可用 ， 否则需要以下配置属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| false |
将此属性设置为 警告 此属性允许您修改当前的默认行为。如果默认行为更改为允许连接器自动无效，并整合早期连接器版本记录的偏移，则属性可能会在以后的发行版本中删除。 | |
| 没有默认值 | 连接器的唯一名称。尝试使用相同名称再次注册将失败。（所有 Kafka 连接连接器都需要此属性。） | |
| 没有默认值 |
连接器的 Java 类的名称。对于 MongoDB 连接器，始终使用 | |
| 没有默认值 |
指定连接器用来连接到 MongoDB 副本集 的连接字符串。此属性替换了 MongoDB 连接器之前版本中提供的 | |
| 没有默认值 |
标识此连接器监控的连接器和/或 MongoDB 副本集或分片集群的唯一名称。每台服务器应该被最多一个 Debezium 连接器监控，因为此服务器名称前缀所有保留的 Kafka 主题都与 MongoDB 副本集或集群类似。仅使用字母数字字符、连字符、句点和下划线来组成名称。逻辑名称应该在所有其他连接器之间唯一，因为该名称用作命名从此连接器接收记录的 Kafka 主题的前缀。 警告 不要更改此属性的值。如果您更改了 name 值，重启后，而不是继续向原始主题发送事件，连接器会将后续事件发送到名称基于新值的主题。 | |
| DefaultMongoDbAuthProvider |
完整的 Java 类名称，是 io.debezium.connector.mongodb.connection.MongoDbAuthProvider 接口的实现。此类处理在 MongoDB 连接上设置凭证（在每个应用程序引导时称为）。默认行为会根据每个文档使用 | |
| 没有默认值 |
使用默认 | |
| 没有默认值 |
使用默认 | |
|
|
使用默认 | |
|
| 连接器将使用 SSL 连接到 MongoDB 实例。 | |
|
|
启用 SSL 时，此设置控制是否在连接阶段禁用严格的主机名检查。如果为 | |
| regex | 用于根据包括/excluded 数据库和集合名称匹配的事件的模式。将 属性设置为以下值之一：
| |
| 空字符串 |
与要监控的数据库名称匹配的正则表达式或文字的逗号分隔列表。默认情况下，会监控所有数据库。
要匹配数据库的名称，Debebe 根据
如果您在配置中包含此属性，不要设置 | |
| 空字符串 |
与监控中排除的数据库名称匹配的正则表达式或文字的逗号分隔列表。当设置了
要匹配数据库的名称，Debebe 根据
如果您在配置中包含此属性，请不要设置 | |
| 空字符串 |
可选的正则表达式或文字列表，与要监控 MongoDB 集合的完全限定命名空间匹配。默认情况下，连接器会监控除
要匹配命名空间的名称，Debebe 根据
如果您在配置中包含此属性，不要设置 | |
| 空字符串 |
可选的正则表达式或文字列表，与 MongoDB 集合的完全限定命名空间匹配，以便从监控中排除。当设置了
要匹配命名空间的名称，Debebe 根据
如果您在配置中包含此属性，请不要设置 | |
|
|
指定连接器用来捕获 MongoDB 服务器中的
| |
|
| 指定连接器 打开的更改流的范围。将此属性设置为以下值之一：
| |
|
指定连接器监控的更改的数据库。只有在 | ||
| 空字符串 | 可选的、以逗号分隔的字段名称列表，它们应该不包括在更改事件消息值中。字段的完全限定域名格式为 databaseName.collectionName.fieldName.nestedFieldName，其中 databaseName 和 collectionName 可能包含通配符 HEKETI，匹配任何字符。 | |
| 空字符串 | 可选的完全限定替换项列表，用于在更改事件消息值中重命名字段。字段的完全限定替换格式为 databaseName.collectionName.fieldName.nestedFieldName:newNestedFieldName，其中 databaseName 和 collectionName 可能包含通配符 高可用性，其匹配任意字符，冒号(:)用于决定字段的重命名映射。下一个字段替换应用于列表中上一个字段替换的结果，因此在重命名同一路径的多个字段时请注意这一点。 | |
|
|
控制 删除 事件是否后跟 tombstone 事件。 | |
| none |
指定应该如何调整模式名称，以便与连接器使用的消息转换器兼容。可能的设置：
| |
| none |
指定应如何调整字段名称，以便与连接器使用的消息转换器兼容。可能的设置：
如需了解更多详细信息，请参阅 Avro 命名。 |
以下 高级配置 属性具有在大多数情况下可以正常工作的良好默认值，因此很少需要在连接器配置中指定。
| 属性 | 默认 | 描述 |
|---|---|---|
|
|
指定当
要将这个选项与 MongoDB 更改流集合一起使用，您必须配置集合来 返回文档前和后镜像。只有在操作发生前需要的配置时才可用操作的预镜像和后镜像。 将此属性设置为以下值之一：
警告
如果查找过程无法检索文档，则无法将完整的文档填充为事件有效负载中的 可能会出现失败的查找，因为删除操作会在创建后马上删除文档，或者因为对分片键的更改会导致将文档移到不同的位置。当您修改组成密钥的任何属性时，分片密钥更改可能会导致。
| |
|
| 正整数值，用于指定应在每个迭代此连接器期间处理的每个批处理事件的最大值。默认值为 2048。 | |
|
|
正整数值，用于指定阻塞队列可以保存的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将 | |
|
|
指定阻塞队列的最大卷的长整数值，以字节为单位。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。 | |
|
| 正整数值指定连接器在每次迭代过程中应等待的毫秒数，以便出现新的更改事件。默认值为 500 毫秒，或 0.5 秒。 | |
|
| 正整数值，在连接第一次尝试或没有主可用后尝试重新连接主时指定初始延迟。默认值为 1 秒(1000 ms)。 | |
|
| 正整数值，指定在重复连接尝试或没有主可用后尝试重新连接主时的最大延迟。默认值为 120 秒(120,000 ms)。 | |
|
|
正整数值，用于指定在异常发生前尝试副本集主的失败连接数上限，并中止任务。默认值为 16，它的默认值是 | |
|
|
控制发送心跳消息的频率。
将此参数设置为 | |
|
|
在流过程中跳过的操作类型的逗号分隔列表。操作包括： | |
| 没有默认值 | 控制快照中包含哪些集合项目。此属性仅影响快照。以 databaseName.collectionName 格式指定以逗号分隔的集合名称列表。
对于您指定的每个集合，还要指定另一个配置属性： | |
| 没有默认值 |
连接器在启动后执行快照前应等待的时间（毫秒）； | |
| 0 |
指定连接器在完成快照后延迟流过程启动的时间（以毫秒为单位）。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的 | |
|
|
指定在拍摄快照时应从一个集合中读取的最大文档数。连接器将在这个大小的多个批处理中读取集合内容。 | |
|
|
可选的、以逗号分隔的正则表达式列表，与您要包含在快照中的模式的完全限定域名(< 要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 schema 的整个名称字符串匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
|
| 正整数值，用于指定在副本集中执行集合同步的最大线程数。默认为 1。 | |
| Initial | 指定连接器启动时执行快照的条件。将 属性设置为以下值之一：
| |
|
|
当设置为 如需了解更多详细信息，请参阅 Transaction Metadata。 | |
| 10000 (10 秒) | 在发生 Retriable 错误后重启连接器前等待的毫秒数。 | |
|
| 连接器为新的、删除或更改副本集轮询的时间间隔。 | |
| 10000 (10 秒) | 驱动程序在中止连接尝试前等待的毫秒数。 | |
| 10000 (10 秒) | 集群监控器试图到达每台服务器的频率。 | |
| 0 |
在发生超时前，套接字上的发送/接收前的毫秒数。 | |
| 30000 (30 秒) | 驱动程序在超时并抛出错误前等待选择服务器的毫秒。 | |
| 没有默认值 | 当流传输更改时，此设置将处理应用到更改流事件，作为标准 MongoDB 聚合流管道的一部分。管道(pipeline)是一个 MongoDB 聚合管道，由数据库的说明组成，用于过滤或转换数据。这可用于自定义连接器消耗的数据。此属性的值必须是 JSON 格式的允许 聚合管道阶段 的数组。请注意，这会在用于支持连接器的内部管道后附加（例如过滤操作类型、数据库名称、集合名称等）。 | |
| internal_first | 用于构建有效 MongoDB 聚合流管道的顺序。将 属性设置为以下值之一：
| |
| fail | 处理超过指定 BSON 大小的文档的更改事件的策略。将 属性设置为以下值之一：
| |
| 0 | 处理更改事件的最大允许大小( 以字节为单位 )。这包括数据库操作前和之后的大小，这更具体地限制了 fullDocument 和 fullDocumentBeforeChange 文件，该文件的大小用于 MongoDB 更改事件。 | |
|
|
指定 oplog/change 流光标在导致执行超时异常前等待服务器生成结果的最大毫秒数。值 | |
| 没有默认值 |
用于向连接器发送信号的数据收集的完全限定名称。https://docs.redhat.com/documentation/en/red_hat_build_of_debezium/2.7.3/html-single/debezium_user_guide/index#debezium-signaling-enabling-source-signaling-channel使用以下格式指定集合名称： | |
| source | 为连接器启用的信号通道名称列表。默认情况下，以下频道可用：
| |
| 没有默认值 | 为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
| |
|
|
连接器在增量快照块中获取并读取的最大文档数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。 | |
|
|
指定连接器在增量快照中使用的水位线机制，以重复数据删除事件，这些事件可能会被增量快照捕获，然后在流恢复后重新捕获。
| |
|
|
应用于决定数据更改的主题名称、模式更改、事务、心跳事件等主题名称，默认为 | |
|
|
指定主题名称的分隔符，默认为 | |
|
| 在绑定的并发散列映射中保存主题名称的大小。此缓存将有助于确定与给定数据收集对应的主题名称。 | |
|
|
控制连接器发送心跳消息的主题名称。主题名称具有此模式： | |
|
|
控制连接器发送事务元数据消息的主题名称。主题名称具有此模式： | |
|
|
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如 连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。 | |
|
|
指定连接器如何在生成 Retriable 错误的操作后响应，如连接错误。
|
用于配置 MongoDB 连接器如何与 Kafka 信号主题交互的属性
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
用于配置 MongoDB 连接器接收器通知频道的透传属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
2.3.6. 监控 Debezium MongoDB 连接器性能
Debezium MongoDB 连接器除了对 Zookeeper、Kafka 和 Kafka Connect 具有 JMX 指标的内置支持外，还有两个指标类型。
Debezium 监控文档 提供有关如何使用 JMX 公开这些指标的详细信息。
2.3.6.1. MongoDB 连接器快照和流 MBean 对象的自定义名称
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.23. 自定义标签如何修改连接器 MBean 名称
默认情况下，MongoDB 连接器使用以下 MBean 名称进行流传输指标：
debezium.mongodb:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.mongodb:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.mongodb:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.mongodb:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.3.6.2. 在 MongoDB 快照过程中监控 Debezium
MBean 为 debezium.mongodb:type=connector-metrics,context=snapshot,server= <topic.prefix& gt; ,task= <task.id>。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
Debezium MongoDB 连接器还提供以下自定义快照指标：
| 属性 | 类型 | 描述 |
|---|---|---|
|
|
| 数据库断开连接的数量。 |
2.3.6.3. 监控 Debezium MongoDB 连接器记录流
MBean 为 debezium.mongodb:type=connector-metrics,context=streaming,server= <topic.prefix& gt; ,task= <task.id>。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
Debezium MongoDB 连接器还提供以下自定义流指标：
| 属性 | 类型 | 描述 |
|---|---|---|
|
|
| 数据库断开连接的数量。 |
|
|
| 主要节点选举数量。 |
2.3.7. Debezium MongoDB 连接器如何处理错误和问题
Debezium 是一个分布式系统，它捕获多个上游数据库中的所有更改，永远不会丢失或丢失某个事件。当系统正常运行并谨慎管理时，Debezium 会在每次更改事件时发送一次。
如果发生错误，系统不会丢失任何事件。但是，当它从错误中恢复时，可能会重复一些更改事件。在这种情况下，Debebe （如 Kafka ）至少提供一次 更改事件交付。
以下主题详细介绍了 Debezium MongoDB 连接器如何处理各种错误和问题。
配置和启动错误
在以下情况下，连接器会在尝试启动时失败，在日志中报告错误或异常，并停止运行：
- 连接器的配置无效。
- 连接器无法使用指定的连接参数成功连接到 MongoDB。
失败后，连接器会尝试使用 exponential backoff 重新连接。您可以配置重新连接尝试的最大数量。
在这些情况下，这个错误将了解更多有关此问题的详细信息，并可能会有推荐的临时解决方案。当配置已被修正或 MongoDB 问题已被解决时，连接器可以重启。
尝试重新连接由三个属性控制：
-
connect.backoff.initial.delay.ms- 在第一次尝试重新连接前的延迟，默认值为 1 秒(1000 毫秒)。 -
connect.backoff.max.delay.ms- 尝试重新连接前的最大延迟，默认值为 120 秒(120,000 毫秒)。 -
connect.max.attempts- 生成错误前尝试的最大尝试次数，默认值为 16。
每个延迟都加倍之前的延迟，最多为最大延迟。根据默认值，下表显示每个失败的连接尝试的延迟，以及失败前的总时间。
| 重新连接尝试号 | 延迟（以秒为单位） | 尝试前的总延迟，以分钟和秒为单位 |
|---|---|---|
| 1 | 1 | 00:01 |
| 2 | 2 | 00:03 |
| 3 | 4 | 00:07 |
| 4 | 8 | 00:15 |
| 5 | 16 | 00:31 |
| 6 | 32 | 01:03 |
| 7 | 64 | 02:07 |
| 8 | 120 | 04:07 |
| 9 | 120 | 06:07 |
| 10 | 120 | 08:07 |
| 11 | 120 | 10:07 |
| 12 | 120 | 12:07 |
| 13 | 120 | 14:07 |
| 14 | 120 | 16:07 |
| 15 | 120 | 18:07 |
| 16 | 120 | 20:07 |
连接器无法启动 - InvalidResumeToken 或 ChangeStreamHistoryLost
在较长时间内停止的连接器无法启动，并报告以下例外：
Command failed with error 286 (ChangeStreamHistoryLost): 'PlanExecutor error during aggregation :: caused by :: Resume of change stream was not possible, as the resume point may no longer be in the oplog
Command failed with error 286 (ChangeStreamHistoryLost): 'PlanExecutor error during aggregation :: caused by :: Resume of change stream was not possible, as the resume point may no longer be in the oplog前面的例外表示 oplog 中不再存在与连接器恢复令牌对应的条目。因为 oplog 不再包含连接器处理的最后偏移量，所以连接器无法恢复流。
您可以使用以下选项之一从失败中恢复：
- 删除失败的连接器，并使用相同的配置创建新连接器，但使用不同的连接器名称。
- 暂停连接器，然后删除偏移量或更改偏移主题。
为了帮助防止与缺失恢复令牌相关的故障，请 优化 oplog 的配置。
Kafka Connect 进程正常停止
如果 Kafka Connect 正在以分布式模式运行，并且 Kafka Connect 进程被安全停止，则在关闭 Kafka Connect 之前，将所有进程的连接器任务迁移到该组中的另一个 Kafka Connect 进程，新的连接器任务将完全关闭之前的任务。处理过程中会有一个短暂的延迟，而连接器任务被安全停止并在新进程中重启。
如果组只包含一个进程，且该进程安全停止，则 Kafka Connect 将停止连接器，并记录每个副本集的最后一个偏移。重启后，副本集任务将继续完全关闭它们。
Kafka Connect 进程崩溃
如果 Kafka Connector 进程意外停止，则它运行的连接器任务将终止，而不会记录它们最近处理的偏移量。当 Kafka Connect 以分布式模式运行时，它将在其他进程中重启这些连接器任务。但是，MongoDB 连接器将从之前进程 记录 的最后偏移量中恢复，这意味着新的替换任务可能会生成在崩溃前处理的一些相同的更改事件。重复事件的数量取决于偏移清除周期以及崩溃前数据更改的卷。
因为在从失败时恢复过程中可能会重复一些事件，所以消费者应始终预期一些事件可能重复。Debezium 更改是幂等的，因此一系列事件始终产生相同的状态。
Debezium 还包括每个更改事件的信息，其中包含有关事件来源的特定于源的信息，包括 MongoDB 事件的唯一事务标识符(h)和时间戳(sec 和 ord)。消费者可以跟踪这些值的其他内容，以了解它是否已看到特定的事件。
如果 snapshot.mode 设为 initial，则在停止了较长的时间间隔后连接器会失败
如果连接器安全停止，用户可能会继续对副本设置成员执行操作。在连接器离线时发生的更改会在 MongoDB 的 oplog 中继续记录。在大多数情况下，连接器重启后，它会读取 oplog 中的偏移值，以确定每个副本集流的最后操作，然后从该点恢复流更改。重启后，当连接器停止到 Kafka 时以及一段时间后，连接器会随数据库捕获。连接器捕获所需的时间取决于 Kafka 的功能和性能，以及数据库中发生的更改卷。
但是，如果连接器为很长时间的间隔停止，则 MongoDB 可能会发生在连接器不活跃时清除 oplog，从而导致连接器最后一次位置的信息丢失。连接器重启后，它无法恢复流，因为 oplog 不再包含之前的偏移值，以标记连接器处理的最后一个操作。连接器无法执行快照，因为它通常当 snapshot.mode 属性设置为 initial，且没有偏移值时。在这种情况下，存在一个不匹配，因为 oplog 不包含之前偏移的值，但偏移值存在于连接器的内部 Kafka offsets 主题中。错误结果，连接器会失败。
要从失败中恢复，请删除失败的连接器，并使用相同的配置创建新连接器，但使用不同的连接器名称。当您启动新连接器时，它会执行快照来达到数据库状态，然后恢复流。
MongoDB 丢失写入
在某些情况下，MongoDB 可能会丢失提交，这会导致 MongoDB 连接器无法捕获丢失的更改。例如，如果在应用更改后的主要崩溃突然崩溃，并记录更改其 oplog，则 oplog 可能在辅助节点可以读取其内容之前不可用。因此，作为新主节点选择的二级节点可能会缺少 oplog 中最新的更改。
目前，无法防止 MongoDB 中的这种副作用。
2.4. MySQL 的 Debezium 连接器
MySQL 有一个二进制日志(binlog)，可按照提交至数据库的顺序记录所有操作。这包括对表模式的更改，以及表中的数据更改。MySQL 使用 binlog 进行复制和恢复。
Debezium MySQL 连接器读取 binlog，为行级 INSERT、UPDATE 和 DELETE 操作生成更改事件，并将更改事件发送到 Kafka 主题。客户端应用程序读取这些 Kafka 主题。
因为 MySQL 通常会在指定时间段内设置为清除 binlogs，所以 MySQL 连接器会为每个数据库执行初始 一致的快照。MySQL 连接器从创建快照的时间点读取 binlog。
有关与此连接器兼容的 MySQL 数据库版本的详情，请参考 Debezium 支持的配置 页面。
使用 Debezium MySQL 连接器的信息和流程组织如下：
- 第 2.4.1 节 “Debezium MySQL 连接器的工作方式”
- 第 2.4.2 节 “Debezium MySQL 连接器数据更改事件的描述”
- 第 2.4.3 节 “Debezium MySQL 连接器如何映射数据类型”
- 第 2.4.4 节 “将 MySQL 数据映射到替代数据类型的自定义转换器”
- 第 2.4.5 节 “设置 MySQL 以运行 Debezium 连接器”
- 第 2.4.6 节 “部署 Debezium MySQL 连接器”
- 第 2.4.7 节 “监控 Debezium MySQL 连接器性能”
- 第 2.4.8 节 “Debezium MySQL 连接器如何处理错误和问题”
2.4.1. Debezium MySQL 连接器的工作方式
连接器支持的 MySQL 拓扑概述对规划应用程序非常有用。要优化地配置和运行 Debezium MySQL 连接器，了解连接器如何跟踪表的结构、公开模式更改、执行快照并确定 Kafka 主题名称。
详情包括在以下主题中：
2.4.1.1. Debezium 连接器支持的 MySQL 拓扑
Debezium MySQL 连接器支持以下 MySQL 拓扑：
- Standalone
- 当使用单个 MySQL 服务器时，服务器必须启用 binlog，以便 Debezium MySQL 连接器可以监控服务器。这通常可以接受，因为二进制日志也可以用作增量 [backup]。在这种情况下，MySQL 连接器始终连接到并遵循此独立 MySQL 服务器实例。
- 主(primary)和副本
Debezium MySQL 连接器可以遵循其中一个主服务器，或者其中一个副本(如果该副本启用了 binlog)，但连接器仅检测对该服务器可见的集群中的更改。通常，除了多主拓扑外，这并不是一个问题。
连接器在服务器的 binlog 中记录其位置，该位置在集群中的每个服务器上都有所不同。因此，连接器必须只遵循一个 MySQL 服务器实例。如果该服务器失败，则必须重启或恢复该服务器，然后才能继续连接器。
- 高可用性集群
- MySQL 存在各种 [高可用性] 解决方案，它们能够更容易容忍和几乎从问题和故障中恢复。由于 HA MySQL 集群使用 GTID，副本能够跟踪任何主服务器中发生的所有更改。
- 多主要
使用每个从多个主服务器复制的一个或多个 MySQL 副本节点。集群复制提供了一种强大的方法来聚合多个 MySQL 集群的复制。
Debezium MySQL 连接器可以使用这些多主 MySQL 副本作为源，只要新副本被捕获到旧副本，就可以切换到不同的多主 MySQL 副本。也就是说，新副本具有第一个副本上看到的所有事务。即使连接器只使用数据库和/或表的子集，因为在尝试重新连接到新的多主 MySQL 副本时，也可以将连接器配置为包含或排除特定的 GTID 源。
- 托管
Debezium MySQL 连接器可以使用托管数据库选项，如 Amazon RDS 和 Amazon Aurora。
由于这些托管的选项不允许使用全局读取锁定，因此连接器在创建一致的快照时会使用表级锁定。
2.4.1.2. Debezium MySQL 连接器如何处理数据库架构更改
当数据库客户端查询数据库时，客户端将使用数据库的当前架构。但是，可以随时更改数据库架构，这意味着连接器必须能够识别每次插入、更新或删除操作时的 schema。另外，连接器不一定将当前模式应用到每个事件。如果事件相对旧，则在应用当前模式之前记录这些事件。
为确保在架构更改后处理发生的正确事件，MySQL 包含在事务日志中，不仅包含影响数据的行级更改，还要处理应用到数据库的 DDL 语句。当连接器在 binlog 中遇到这些 DDL 语句时，它会解析它们并更新每个表的 schema 的内存表示。连接器使用此架构表示在每次插入、更新或删除操作时标识表的结构，并生成适当的更改事件。在单独的数据库架构历史记录 Kafka 主题中，连接器记录了所有 DDL 语句，以及显示每个 DDL 语句的 binlog 中的位置。
当连接器在崩溃或安全停止后重启时，它开始从特定位置读取 binlog，即从特定时间点读取 binlog。连接器通过读取数据库模式历史记录 Kafka 主题来重建在此时存在的表结构，并将所有 DDL 语句解析到连接器启动的 binlog 中的点。
此数据库架构历史记录主题仅用于内部连接器。另外，连接器也可以将 schema 更改事件发送到面向消费者应用程序的不同主题。
当 MySQL 连接器捕获在应用 schema 更改工具（如 gh-ost 或 pt-online-schema-change ）的表中的更改时，会在迁移过程中创建帮助程序表。您必须配置连接器来捕获这些帮助程序表中发生的更改。如果消费者不需要记录连接器为帮助程序表生成的记录，请将单个消息转换(SMT) 配置为从连接器发出的消息中删除这些记录。
其他资源
- 接收 Debezium 事件记录 的主题的默认名称。
2.4.1.3. Debezium MySQL 连接器如何公开数据库架构更改
您可以配置 Debezium MySQL 连接器来生成模式更改事件，以描述应用到数据库中表的 schema 更改。连接器将模式更改事件写入名为 < topicPrefix> 的 Kafka 主题，其中 topicPrefix 是 topic.prefix 连接器配置属性中指定的命名空间。连接器发送到 schema 更改主题的消息包含一个有效负载，并可以选择包含更改事件消息的 schema。
模式更改事件的 schema 具有以下元素：
名称- 模式更改事件消息的名称。
type- 更改事件消息的类型。
version- 架构的版本。version 是一个整数，每次更改 schema 时都会递增。
fields- 更改事件消息中包含的字段。
示例：MySQL 连接器模式更改主题的 Schema
以下示例显示了 JSON 格式的典型模式。
模式更改事件消息的有效负载包括以下元素：
ddl-
提供导致 schema 的 SQL
CREATE、ALTER或DROP语句。 databaseName-
DDL 语句应用到的数据库名称。
databaseName的值充当 message 键。 pos- 语句的 binlog 中的位置。
tableChanges-
架构更改后整个表模式的结构化表示。
tableChanges字段包含一个数组，其中包含表的每列条目。由于结构化表示以 JSON 或 Avro 格式显示数据，因此用户可以轻松地读取消息，而无需首先通过 DDL 解析器处理它们。
对于处于捕获模式的表，连接器不仅将模式更改的历史记录存储在 schema 更改主题中，还要存储在内部数据库架构历史记录主题中。内部数据库架构历史记录主题仅用于连接器，它不用于直接使用应用程序。确保需要针对 schema 更改通知的应用程序只消耗了来自 schema 更改主题的信息。
永不对数据库 schema 历史记录主题进行分区。要使数据库架构历史记录主题正常工作，它必须保持一致的全局顺序，连接器向其发送的事件记录。
要确保主题不在分区中分割，请使用以下方法之一为主题设置分区计数：
-
如果您手动创建数据库架构历史记录主题，请指定分区计数
1。 -
如果您使用 Apache Kafka 代理自动创建数据库模式历史记录主题，则会创建主题，将 Kafka
num.partitions配置选项 的值设置为1。
连接器发送到其 schema 更改主题的消息格式处于 inubating 状态，并可能会在不通知的情况下更改。
示例：向 MySQL 连接器模式更改主题发送的消息
以下示例显示了 JSON 格式的典型的模式更改消息。消息包含表 schema 的逻辑表示。
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
|
| 2 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 3 |
|
标识包含更改的数据库和模式。 |
| 4 |
|
此字段包含负责 schema 更改的 DDL。 |
| 5 |
| 包含 DDL 命令生成的架构更改的一个或多个项目的数组。 |
| 6 |
| 描述更改类型。该值是以下之一：
|
| 7 |
|
创建、更改或丢弃的表的完整标识符。对于表重命名，此标识符是 < |
| 8 |
| 代表应用的更改后的表元数据。 |
| 9 |
| 编写表主键的列列表。 |
| 10 |
| changed 表中每个列的元数据。 |
| 11 |
| 每个表更改的自定义属性元数据。 |
如需更多信息，请参阅 模式历史记录主题。
2.4.1.4. Debezium MySQL 连接器如何执行数据库快照
当 Debezium MySQL 连接器首次启动时，它会执行数据库的初始 一致快照。此快照可让连接器为数据库的当前状态建立基准。
Debezium 在运行快照时可以使用不同的模式。快照模式由 snapshot.mode 配置属性决定。属性的默认值为 initial。您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。
您可以在以下部分中找到有关快照的更多信息：
连接器在执行快照时完成一系列任务。确切的步骤因快照模式以及对数据库的影响的表锁定策略而有所不同。当 Debezium MySQL 连接器执行 使用全局读取锁定或 表级锁定 的初始快照时，它会完成不同的步骤。
2.4.1.4.1. 使用全局读取锁定的初始快照
您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。如果您配置不同的快照模式，连接器使用此工作流的修改版本完成快照。有关不允许全局读取锁定的环境中的快照进程的详情，请查看 表级锁定的快照工作流。
Debezium MySQL 连接器用来执行带有全局读取锁定的初始快照的默认工作流
下表显示了 Debezium 遵循的工作流中的步骤，以创建具有全局读取锁定的快照。
| 步骤 | 操作 |
|---|---|
| 1 | 建立与数据库的连接。 |
| 2 |
确定要捕获的表。默认情况下，连接器捕获所有非系统表的数据。快照完成后，连接器将继续流传输指定表的数据。如果您希望连接器只从特定表捕获数据，您可以通过设置 |
| 3 |
获取表上要捕获的全局读取锁定，以阻止其他数据库客户端 写入。 |
|
4 注意 使用这些隔离语义可能会减慢快照的进度。如果快照需要很长时间才能完成，请考虑使用不同的隔离配置，或者跳过初始快照并运行 增量快照。 | 5 |
| 阅读当前的 binlog 位置。 | 6 |
|
捕获数据库中所有表的结构或指定用于捕获的所有表。连接器在其内部数据库模式历史记录主题中保留模式信息，包括所有必要的 注意
默认情况下，连接器捕获数据库中每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。 | 7 |
| 释放在第 3 步中获得的全局读锁定。其他数据库客户端现在可以写入数据库。 | 8 |
| 在步骤 5 中连接器读取的 binlog 位置，连接器开始扫描指定为捕获的表。在扫描过程中，连接器完成以下任务：
| 9 |
| 提交事务。 | 10 |
生成的初始快照会捕获捕获表中每行的当前状态。在这个基准状态中，连接器会捕获后续更改。
在快照过程开始后，如果进程因为连接器失败、重新平衡或其他原因而中断，进程会在连接器重启后重启。
连接器完成初始快照后，它会继续从第 5 步中读取的位置流，使其不会丢失任何更新。
如果连接器因任何原因再次停止，它会在重启后恢复流更改，从之前离开的位置恢复流更改。
连接器重启后，如果修剪日志，则日志中的连接器位置可能不再可用。然后，连接器会失败，并返回表示需要新快照的错误。要将连接器配置为在这种情况下自动启动快照，请将 snapshot.mode 属性的值设置为 when_needed。有关对 Debezium MySQL 连接器进行故障排除的更多提示，请参阅 当出现问题时的行为。
2.4.1.4.2. 使用表级别锁定的初始快照
在某些数据库环境中，管理员不允许全局读取锁定。如果 Debezium MySQL 连接器检测到不允许全局读取锁定，则连接器会在执行快照时使用表级锁定。要使连接器执行使用表级锁定的快照，Debezium 连接器用来连接到 MySQL 的数据库帐户必须具有 LOCK TABLES 权限。
Debezium MySQL 连接器用于执行带有表级锁定的初始快照的默认工作流
下表显示了 Debezium 遵循的工作流中的步骤，以使用表级读取锁定创建快照。有关不允许全局读取锁定的环境中的快照进程的详情，请查看 全局读取锁定的快照工作流。
| 步骤 | 操作 |
|---|---|
| 1 | 建立与数据库的连接。 |
| 2 |
确定要捕获的表。默认情况下，连接器会捕获所有非系统表。要让连接器捕获表或表元素的子集，您可以设置多个 |
| 3 | 获取表级锁定。 |
| 4 | 5 |
| 阅读当前的 binlog 位置。 | 6 |
|
读取将连接器配置为捕获更改的数据库和表的 schema。连接器在其内部数据库模式历史记录主题中保留模式信息，包括所有必要的 注意 默认情况下，连接器捕获数据库中每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。 有关您在初始快照中没有包括快照持久模式信息的更多信息，请参阅 了解为什么初始快照捕获所有表的 schema。 | 7 |
| 在步骤 5 中连接器读取的 binlog 位置，连接器开始扫描指定为捕获的表。在扫描过程中，连接器完成以下任务：
| 8 |
| 提交事务。 | 9 |
| 释放表级锁定。其他数据库客户端现在可以写入任何之前锁定的表。 | 10 |
| 设置 | 描述 |
|---|---|
|
| 连接器在每次启动时都执行快照。快照包括捕获的表的结构和数据。指定此值，每次连接器启动时，使用从捕获的表中数据的完整表示来填充主题。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照，如用于创建初始快照的默认工作流 中所述。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照。快照完成后，连接器会停止，且不会为后续数据库更改流传输事件记录。 |
|
|
弃用，请参阅 |
|
|
连接器捕获所有相关表的结构，执行 创建初始快照的默认工作流 中描述的所有步骤，但不创建 |
|
|
当连接器启动时，而不是执行快照时，它会立即开始为后续数据库更改流事件记录。这个选项考虑将来弃用，而是使用 |
|
|
弃用， |
|
|
设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
如需更多信息，请参阅连接器配置属性表中的 snapshot.mode。
2.4.1.4.3. 有关初始快照捕获所有表的 schema 历史记录的描述
连接器运行的初始快照捕获两种类型的信息：
- 表数据
-
有关
INSERT、UPDATE和DELETE操作的信息，它们在连接器的table.include.list属性中命名。 - 模式数据
- 描述应用到表的结构更改的 DDL 语句。如果配置了 schema 数据，则 schema 数据会被保留到内部模式历史记录主题，以及连接器的 schema 更改主题。
运行初始快照后，您可能会注意到快照捕获了未指定用于捕获的表的模式信息。默认情况下，初始快照旨在捕获数据库中存在的每个表的模式信息，而不仅限于为捕获指定的表。连接器要求表的 schema 在捕获表之前存在于 schema 历史记录主题中。通过启用初始快照来捕获不属于原始捕获集的表，Debezium 准备连接器，以便稍后需要从这些表中读取事件数据。如果初始快照没有捕获表的模式，您必须将 schema 添加到历史记录主题，然后才能从表中捕获数据。
在某些情况下，您可能想要限制初始快照中的模式捕获。当您要减少完成快照所需的时间时，这非常有用。或者，当 Debezium 通过有权访问多个逻辑数据库的用户帐户连接到数据库实例时，但您希望连接器只从特定逻辑数据库中的表捕获更改。
其他信息
- 从初始快照未捕获的表中捕获数据（无模式更改）
- 从没有由初始快照捕获的表捕获数据(schema 更改)
-
设置
schema.history.internal.store.only.captured.tables.ddl属性，以指定要从中捕获模式信息的表。 -
设置
schema.history.internal.store.only.captured.databases.ddl属性，以指定捕获模式更改的逻辑数据库。
2.4.1.4.4. 从初始快照未捕获的表中捕获数据（无模式更改）
在某些情况下，您可能希望连接器从最初快照未捕获其 schema 的表中捕获数据。根据连接器配置，初始快照可能会只捕获数据库中特定表的表模式。如果历史记录主题中没有表模式，连接器无法捕获表，并报告缺少的 schema 错误。
您可能仍然能够从表中捕获数据，但您必须执行额外的步骤来添加表模式。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 在事务日志中，表的所有条目都使用相同的模式。有关从具有结构化更改的新表捕获数据的详情，请参考 从初始快照(schema 更改)中未捕获的表 捕获数据。
流程
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 将以下更改应用到连接器配置：
-
将
snapshot.mode设置为schema_only_recovery。 -
将
schema.history.internal.store.only.captured.tables.ddl的值设置为false。 -
添加您希望连接器捕获到
table.include.list的表。这样可保证以后，连接器可以重建所有表的 schema 历史记录。
-
将
- 重启连接器。快照恢复过程会根据表的当前结构重建模式历史记录。
- （可选）在快照完成后，启动 增量快照 来捕获新添加的表的现有数据，以及该连接器离线时发生的其他表的更改。
-
（可选）将
snapshot.mode重置为schema_only，以防止连接器在以后的重启后启动恢复。
2.4.1.4.5. 从没有由初始快照捕获的表捕获数据(schema 更改)
如果将架构更改应用到表，则在架构更改前提交的记录与更改后提交的结构不同。当 Debezium 捕获表中的数据时，它会读取 schema 历史记录，以确保它将正确的模式应用到每个事件。如果 schema 历史记录主题中没有 schema，连接器将无法捕获表，并会产生错误结果。
如果要捕获初始快照未捕获的表中的数据，并修改了表的 schema，您必须将 schema 添加到历史记录主题（如果还没有可用）。您可以通过运行新的模式快照或运行表的初始快照来添加架构。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 对表应用了一个架构更改，因此要捕获的记录没有统一的结构。
流程
- 初始快照捕获了所有表的模式(
storage.only.captured.tables.ddl设置为false) -
编辑
table.include.list属性，以指定您要捕获的表。 - 重启连接器。
- 如果要从新添加的表中捕获现有数据，则启动 增量快照。
-
编辑
- 初始快照没有捕获所有表的模式(storage
.only.captured.tables.ddl设置为true) 如果初始快照没有保存您要捕获的表的模式，请完成以下步骤之一：
- 流程 1：Schema 快照，后跟增量快照
在此过程中，连接器首先执行 schema 快照。然后，您可以启动增量快照，使连接器能够同步数据。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为schema_only。 -
编辑
table.include.list以添加您要捕获的表。
-
将
- 重启连接器。
- 等待 Debezium 捕获新表和现有表的模式。连接器停止后发生的数据更改不会被捕获。
- 为确保没有数据丢失，可启动 增量快照。
- 流程 2：初始快照，后跟可选的增量快照
在此过程中，连接器执行数据库的完整初始快照。与任何初始快照一样，在具有许多大表的数据库中，运行初始快照可能是一个耗时的操作。快照完成后，您可以选择性地触发增量快照，以捕获连接器离线期间发生的任何更改。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
-
编辑
table.include.list以添加您要捕获的表。 为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为initial。 -
（可选）将
schema.history.internal.store.only.captured.tables.ddl设置为false。
-
将
- 重启连接器。连接器使用完整的数据库快照。快照完成后，连接器会过渡到 streaming。
- （可选）要捕获连接器脱机时更改的任何数据，请启动 增量快照。
2.4.1.5. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供总结表数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改为捕获不同的表集合。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号表。您可以通过向 Debezium 信号表发送信号请求来启动临时快照。
当您启动现有表的临时快照时，连接器会将内容附加到表已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的表。快照可以捕获数据库的全部内容，或者仅捕获数据库中表的子集。此外，快照也可捕获数据库中表的内容的子集。
您可以通过向信号表发送 execute-snapshot 消息来指定要捕获的表。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的表名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| N/A |
包含与快照中包含的表的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作表的主键的列名称。 |
触发临时增量快照
您可以通过向信号表添加带有 execute-snapshot 信号类型的条目，或者向 Kafka 信号发送信号消息 来启动临时增量快照。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个表的开始和端点。根据表中的条目数量以及配置的块大小，Debezium 会将表分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号表或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.4.1.6. 增量快照
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个表。您可以指定您希望快照捕获的表 以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debezium 使用水位线来跟踪其进度，维护其捕获的每个表行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获表。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，以将表添加到其
table.include.list属性中。
增量快照过程
当您运行增量快照时，Debezium 按主密钥对每个表进行排序，然后根据 配置的块大小 将表分成块。通过块工作的块，然后捕获块中的每个表行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改表记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获了包含该行的 READ 事件前修改表行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一表行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定表块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到表的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
2.4.1.6.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号表。您可以提交快照信号，作为 SQL INSERT 查询。
在 Debezium 检测到信号表中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的表，并可选择性地指定快照操作的类型。Debezium 目前支持 增量 和 阻塞 快照类型。
要指定要包含在快照中的表，提供一个列出表的 data-collections 数组，或用于匹配表的正则表达式数组，例如：
{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会解释空数组，意味着不需要任何操作，且不会执行快照。
如果要包含在快照中的表的名称包含一个点(.)、空格或其它非字母数字字符，则必须使用双引号转义表名称。
例如，要包含 db1 数据库中存在的表，并且名为 My.Table，请使用以下格式 ："db1.\"My.Table\" "。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
发送 SQL 查询，将临时增量快照请求添加到信号表中：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、type和data参数的值 与信号表的字段 相对应。
下表描述了示例中的参数：Expand 表 2.77. SQL 命令中的字段描述，用于将增量快照信号发送到信号表 项 值 描述 1
database.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshottype参数指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定表名称或正则表达式数组，以匹配快照中包含的表名称。
数组列出了使用格式database.table的正则表达式，以匹配表的完全限定名称。此格式与您用来指定连接器 信号表的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
有效值为incremental和blocking值。
如果没有指定值，连接器默认为执行增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
每个额外条件都是带有data-collection和filter属性的对象。您可以为每个数据收集指定不同的过滤器。
请参阅data-collection属性是过滤器应用到的数据收集的完全限定域名。有关additional-conditions参数的详情，请参考 第 2.4.1.6.2 节 “使用附加条件运行临时增量快照”。
2.4.1.6.2. 使用附加 条件运行临时增量快照
如果您希望快照只在表中包括内容子集，您可以通过将 additional-conditions 参数附加到快照信号来修改信号请求。
对典型快照的 SQL 查询采用以下格式：
SELECT * FROM <tableName> ....
SELECT * FROM <tableName> ....
通过添加 additional-conditions 参数，您可以在 SQL 查询中附加 WHERE 条件，如下例所示：
SELECT * FROM <data-collection> WHERE <filter> ....
SELECT * FROM <data-collection> WHERE <filter> ....以下示例显示了向信号表发送带有额外条件的临时增量快照请求的 SQL 查询：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
例如，假设您有一个包含以下列的 products 表：
-
ID（主密钥） -
color -
quantity
如果您需要 product 表的增量快照，其中只包含 color=blue 的数据项，您可以使用以下 SQL 语句来触发快照：
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue"}]}');
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue"}]}');
additional-conditions 参数还允许您传递基于多个列的条件。例如，使用上例中的 product 表，您可以提交查询来触发增量快照，该快照仅包含 color=blue 和 quantity>10 的项数据：
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue AND quantity>10"}]}');
INSERT INTO db1.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.products", "filter": "color=blue AND quantity>10"}]}');以下示例显示了连接器捕获的增量快照事件的 JSON。
例 2.24. 增量快照事件消息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.4.1.6.3. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.25. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择表内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果一个带有列 ID （主键）、颜色 和品牌 的 products 表，如果您希望快照只包含 color='blue' 的内容，当请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 product 表，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的 表中的内容，您可以发送以下请求：
products
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.4.1.6.4. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的信号发送信号来停止已经运行的快照。
您可以通过在 SQL INSERT 查询中发送停止快照信号，向信号表提交停止快照信号。stop-snapshot 信号将快照操作的类型指定为 增量，并选择性地指定要从当前运行的快照中省略的表。在 Debezium 检测到信号表中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
发送 SQL 查询以停止临时增量快照到信号表：
INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
INSERT INTO db1.debezium_signal (id, type, data) values ('ad-hoc-1', 'stop-snapshot', '{"data-collections": ["db1.table1", "db1.table2"], "type":"incremental"}');INSERT INTO db1.debezium_signal (id, type, data)1 values ('ad-hoc-1',2 'stop-snapshot',3 '{"data-collections": ["db1.table1", "db1.table2"],4 "type":"incremental"}');5 Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号表的字段相对应。
下表描述了示例中的参数：Expand 表 2.80. SQL 命令中的字段描述，用于将停止增量快照信号发送到信号表 项 值 描述 1
database.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。3
stop-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定表名称或正则表达式数组，以匹配要从快照中删除的表名称。
数组以database.table格式按完全限定名称匹配表的正则表达式。如果您从
data字段省略这个组件，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.4.1.6.5. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，表名称或正则表达式，以匹配要从快照中删除的表名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.table1", "db1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.table1", "db1.table2"], "type": "INCREMENTAL"}}`2.4.1.7. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新表，并在连接器运行时完成快照。
- 您可以添加大表，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个表必须是快照
additional-conditions ：您可以为不同的表指定不同的过滤器。
-
data-collection属性是要应用过滤器的表的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.4.1.8. 接收 Debezium MySQL 更改事件记录的 Kafka 主题的默认名称
默认情况下，MySQL 连接器将所有 INSERT、UPDATE 和 DELETE 操作的更改事件写入表中的单个 Apache Kafka 主题，该事件特定于该表。
连接器使用以下惯例命名更改事件主题：
topicPrefix.databaseName.tableName
假设 fulfillment 是主题前缀，inventory 是数据库名称，数据库包含名为 orders, customers, 和 products 的表。Debezium MySQL 连接器将事件发送到三个 Kafka 主题，一个用于数据库中的每个表：
fulfillment.inventory.orders fulfillment.inventory.customers fulfillment.inventory.products
fulfillment.inventory.orders
fulfillment.inventory.customers
fulfillment.inventory.products以下列表提供了默认名称组件的定义：
- topicPrefix
-
由
topic.prefix连接器配置属性指定的主题前缀。 - schemaName
- 发生操作的模式的名称。
- tableName
- 操作发生的表的名称。
连接器应用类似的命名约定来标记其内部数据库架构历史记录主题、架构更改主题 和事务元数据主题。
如果默认主题名称不满足您的要求，您可以配置自定义主题名称。要配置自定义主题名称，您可以在逻辑主题路由 SMT 中指定正则表达式。有关使用逻辑主题路由 SMT 自定义主题命名的更多信息，请参阅 主题路由。
事务元数据
Debezium 可以生成代表事务边界的事件，以及丰富的数据更改事件消息。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
Debezium 为每个事务中的 BEGIN 和 END 分隔符生成事务边界事件。事务边界事件包含以下字段：
status-
BEGIN或END. id- 唯一事务标识符的字符串表示。
ts_ms-
数据源的事务边界事件(
BEGIN或END事件)的时间。如果数据源没有向 Debezium 提供事件时间，则字段代表 Debezium 处理事件的时间。 event_count（用于END事件）- 事务发出的事件总数。
data_collections（用于END事件）-
一组
data_collection和event_count元素，用于指示连接器为来自数据收集的更改发出的事件数。
示例
除非通过 topic.transaction 选项覆盖，否则连接器会将事务事件发送到 < topic.prefix>.transaction 主题。
更改数据事件增强
当启用事务元数据时，数据消息 Envelope 会增加新的 transaction 字段。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示。
total_order- 事件在事务生成的所有事件间的绝对位置。
data_collection_order- 事件在事务发送的所有事件中的每个数据收集位置。
以下是消息示例：
2.4.2. Debezium MySQL 连接器数据更改事件的描述
Debezium MySQL 连接器为每个行级 INSERT、UPDATE 和 DELETE 操作生成数据更改事件。每个事件包含一个键和值。键和值的结构取决于更改的表。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，用户很难处理。要解决这个问题，每个事件都包含其内容的 schema，或者如果您使用 schema registry，消费者可以用来从 registry 获取 schema 的模式 ID。这使得每个事件自包含。
以下框架 JSON 显示了更改事件的基本四部分。但是，如何配置您选择在应用程序中使用的 Kafka Connect 转换器决定了更改事件中的这四个部分的表示。只有在将转换器配置为生成它时，schema 字段才会处于 change 事件中。同样，只有在将转换器配置为生成它时，事件键和事件有效负载才会处于更改事件中。如果您使用 JSON 转换程序，并将其配置为生成所有四个基本更改事件部分，则更改事件具有此结构：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
第一个 |
| 2 |
|
第一个 |
| 3 |
|
第二个 |
| 4 |
|
第二个 |
默认情况下，连接器流将事件记录改为带有与事件原始表相同的名称的主题。请参阅 主题名称。
MySQL 连接器确保所有 Kafka Connect 模式名称都遵循 Avro 模式名称格式。这意味着逻辑服务器名称必须以拉丁字母或下划线开头，即 a-z、A-Z 或 _。逻辑服务器名称和表名称中的每个字符都必须是拉丁字母、数字或下划线，即 a-z、A-Z、0-9 或 _。如果存在无效的字符，它将被一个下划线字符替代。
如果逻辑服务器名称、数据库名称或表名称包含无效字符，则这可能会导致意外冲突，并且区分名称的唯一字符无效，因此用下划线替换。
更多详情位于以下主题中：
2.4.2.1. 关于 Debezium MySQL 更改事件中的键
更改事件的密钥包含更改表键和更改行的实际键的 schema。在连接器创建事件时，schema 及其对应有效负载都包含更改表的 PRIMARY KEY （或唯一约束）中每个列的字段。
请考虑以下 customers 表，后面是此表的更改事件关键示例。
捕获 customer 表更改的每个更改事件都有相同的事件关键模式。只要 customers 表有以前的定义，可以捕获 customer 表更改的事件都有以下关键结构：在 JSON 中，类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
键的 schema 部分指定一个 Kafka Connect 模式，它描述了键的 |
| 2 |
|
定义键有效负载结构的 schema 名称。这个模式描述了更改的表的主密钥的结构。Key 模式名称的格式是 connector-name.database-name.table-name.
|
| 3 |
|
指明事件键是否在其 |
| 4 |
|
指定 |
| 5 |
|
包含生成此更改事件的行的密钥。在本例中，键包含一个 |
2.4.2.2. 关于 Debezium MySQL 更改事件中的值
更改事件中的值比键复杂一些。与键一样，值也有一个 schema 部分和一个 payload 部分。schema 部分包含描述 payload 部分的 Envelope 结构的 schema，包括其嵌套字段。更改创建、更新或删除数据的操作的事件，它们都有带有 envelope 结构的值 payload。
考虑用于显示更改事件键示例相同的示例表：
此表更改更改事件的值部分描述如下：
创建 事件
以下示例显示了一个更改事件的值部分，连接器为在 customer 表中创建数据的操作生成的更改事件的值部分：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 值的 schema，它描述了值有效负载的结构。在连接器为特定表生成的更改事件时，更改事件的值 schema 都相同。 |
| 2 |
|
在 |
| 3 |
|
|
| 4 |
|
|
| 5 |
|
值的实际数据。这是更改事件提供的信息。 |
| 6 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中，
|
| 7 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 8 |
|
指定事件发生前行状态的可选字段。当 |
| 9 |
|
指定事件发生后行状态的可选字段。在本例中， |
| 10 |
| 描述事件源元数据的强制字段。此字段包含可用于将此事件与其他事件进行比较的信息，以及事件的来源、发生事件的顺序以及事件是否是同一事务的一部分。源元数据包括：
|
更新 事件
示例 customers 表中一个更新的改变事件的值有与那个表的 create 事件相同的模式。同样，事件值的有效负载具有相同的结构。但是，事件值 payload 在更新 事件中包含不同的值。以下是当连接器在 customers 表中为更新生成的更改事件值的示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行状态的可选字段。在 update 事件值中， |
| 2 |
|
指定事件发生后行状态的可选字段。您可以比较 |
| 3 |
|
描述事件源元数据的强制字段。
|
| 4 |
|
描述操作类型的强制字符串。在 update 事件值中， |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 6 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 7 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新行主/唯一键的列会更改行键的值。当密钥更改时，Debezium 会输出 三个 事件：一个 DELETE 事件和一个带有行的旧键的 tombstone 事件，后跟一行的新键的事件。详情位于下一节中。
主密钥更新
更改行的主键字段的 UPDATE 操作被称为主键更改。对于主键更改，在 UPDATE 事件记录中，连接器为旧键发出 DELETE 事件记录，并为新(updated)键发出 CREATE 事件记录。这些事件具有常见的结构和内容，另外，每个事件都有一个与主键更改相关的消息标头：
-
DELETE事件记录具有__debezium.newkey作为消息标头。此标头的值是更新行的新主键。 -
CREATE事件记录具有__debezium.oldkey作为消息标头。此标头的值是更新行具有的上一个（折叠）主键。
删除 事件
delete 更改事件中的值与为同一表的 create 和 update 事件相同的 schema 部分。示例 customer 表的 delete 事件中 payload 部分类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行的状态的可选字段。在一个 delete 事件值中， |
| 2 |
|
可选字段，用于指定事件发生后行的状态。在一个 delete 事件值中， |
| 3 |
|
描述事件源元数据的强制字段。在一个 delete 事件值中，
|
| 4 |
|
描述操作类型的强制字符串。 |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 6 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 7 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
删除 更改事件记录为消费者提供处理删除此行所需的信息。包含了旧值，因为有些用户可能需要它们才能正确处理删除。
MySQL 连接器事件设计为使用 Kafka 日志压缩。日志压缩支持删除一些旧的信息，只要至少保留每个密钥的最新消息。这可让 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
tombstone 事件
删除行时，delete 事件值仍可用于日志压缩，因为 Kafka 您可以删除具有相同键的所有之前信息。但是，为了使 Kafka 删除具有相同键的所有信息，消息值必须是 null。为了实现此目的，在 Debezium MySQL 连接器发出 delete 事件后，连接器会发出一个特殊的 tombstone 事件，它具有相同的键但一个 null 值。
截断 事件
truncate 更改事件信号，提示表已被截断。truncate 事件的消息键为 null。message 值类似以下示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述事件源元数据的强制字段。在 truncate 事件值中，
|
| 2 |
|
描述操作类型的强制字符串。 |
| 3 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 4 |
| 可选字段，显示连接器处理事件的时间（以微秒为单位）。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
| 5 |
| 可选字段，显示连接器处理事件的时间，以纳秒为单位。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
如果单个 TRUNCATE 语句应用到多个表，则会为每个删节的表发出一个 truncate 更改事件记录。
truncate 事件表示应用到整个表的更改，它没有消息键。在跨越多个分区的主题中，无法保证应用到整个表的更改事件的顺序。也就是说，没有对 的排序保证(创建、更新 等等)，或者针对该表的 truncate 事件。当消费者从不同分区读取事件时，它只能在从第二个分区读取同一表后从一个分区读取表 的更新 事件。
2.4.3. Debezium MySQL 连接器如何映射数据类型
Debezium MySQL 连接器代表对带有类似行表的事件行的更改。事件包含每个列值的一个字段。该列的 MySQL 数据类型指定 Debezium 如何代表事件中的值。
在 MySQL 中存储字符串的列带有字符集和 collation。在读取 binlog 事件中的列值的二进制表示时，MySQL 连接器使用列的字符集。
连接器可以将 MySQL 数据类型映射到 字面 和 语义 类型。
- literal type ：如何使用 Kafka Connect 模式类型来表示值。
- 语义类型 ： Kafka Connect 模式如何捕获字段的含义（架构名称）。
如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。
详情包括在以下部分中：
基本类型
下表显示了连接器如何映射基本 MySQL 数据类型。
| MySQL 类型 | 字面类型 | 语义类型 |
|---|---|---|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
精度仅用于确定存储大小。精度 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/a |
|
|
|
N/a |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/A |
|
|
|
N/a |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/A |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.
临时类型
排除 TIMESTAMP 数据类型，MySQL temporal 类型取决于 time.precision.mode 连接器配置属性的值。对于 TIMESTAMP 列，它的默认值被指定为 CURRENT_TIMESTAMP 或 NOW，值 1970-01-01 00:00:00 被用于 Kafka Connect schema 中的默认值。
MySQL 允许 DATE, DATETIME, 和 TIMESTAMP 为零值，因为在有些情况下首先使用零值而不是 null 值。当列定义允许 null 值时，MySQL connector 代表零值作为 null 值，或者在列不允许 null 值时作为 epoch 天。
没有时区的临时值
DATETIME 类型代表本地日期和时间，如 "2018-01-13 09:48:27"。正如您所见，没有时区信息。这些列使用 UTC 根据列的精度转换为 epoch 毫秒或微秒。TIMESTAMP 类型代表一个没有时区信息的时间戳。当从 UTC 写入服务器（或会话）到当前时区时，它将由 MySQL 从服务器（或会话）转换为 UTC （或会话的）当前时区（或会话的）在读取值时将其转换为服务器（或会话）当前时区。例如：
-
DATETIME，值为2018-06-20 06:37:03变为1529476623000。 -
TIMESTAMP的值2018-06-20 06:37:03变为2018-06-20T13:37:03Z。
这些列根据服务器（或会话）当前时区，在 UTC 中转换为对应的 io.debezium.time.ZonedTimestamp。默认情况下，将从服务器查询时区。
运行 Kafka Connect 和 Debezium 的 JVM 的时区不会影响这些转换。
有关与临时值相关的属性的更多详细信息，请参阅 MySQL 连接器配置属性的 文档。
- time.precision.mode=adaptive_time_microseconds(default)
MySQL 连接器根据列的数据类型定义决定字面类型和语义类型，以便事件准确表示数据库中的值。所有时间字段都以微秒为单位。只有
00:00:00.000000到23:59:59.999999范围内的正TIME字段值才能正确捕获。Expand 表 2.89. Mappings when time.precision.mode=adaptive_time_microseconds MySQL 类型 字面类型 语义类型 DATEINT32io.debezium.time.Date
代表自时期起的天数。TIME[(M)]INT64io.debezium.time.MicroTime
代表时间值（微秒），且不包括时区信息。MySQL 允许M在0-6范围内。DATETIME, DATETIME(0), DATETIME(1), DATETIME(2), DATETIME(3)INT64io.debezium.time.Timestamp
代表超过 epoch 的毫秒数，不包括时区信息。DATETIME(4), DATETIME(5), DATETIME(6)INT64io.debezium.time.MicroTimestamp
代表过去 epoch 的微秒数，不包括时区信息。- time.precision.mode=connect
MySQL 连接器使用定义的 Kafka Connect 逻辑类型。这种方法的精确度低于默认方法，如果数据库列的比例大于
3，则事件可能不太 精确。只能处理00:00:00.000到23:59:59.999范围的值。只有在确保表中的TIME值永远不会超过支持的范围时，才设置time.precision.mode=connect。预计在以后的 Debezium 版本中会删除connect设置。Expand 表 2.90. time.precision.mode=connect时的映射 MySQL 类型 字面类型 语义类型 DATEINT32org.apache.kafka.connect.data.Date
代表自 epoch 起的天数。TIME[(M)]INT64org.apache.kafka.connect.data.Time
代表以微秒为单位的时间值，且不包含时区信息。DATETIME[(M)]INT64org.apache.kafka.connect.data.Timestamp
代表自 epoch 起的毫秒数，且不包含时区信息。
十进制类型
Debezium 连接器根据 decimal.handling.mode 连接器配置属性的设置来处理十进制。
- decimal.handling.mode=precise
Expand 表 2.91. 当 decimal.handling.mode=precise时映射 MySQL 类型 字面类型 语义类型 NUMERIC[(M[,D])]BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。DECIMAL[(M[,D])]BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。- decimal.handling.mode=double
Expand 表 2.92. Mappings when decimal.handling.mode=double MySQL 类型 字面类型 语义类型 NUMERIC[(M[,D])]FLOAT64不适用
DECIMAL[(M[,D])]FLOAT64不适用
- decimal.handling.mode=string
Expand 表 2.93. 当 decimal.handling.mode=string时映射 MySQL 类型 字面类型 语义类型 NUMERIC[(M[,D])]字符串不适用
DECIMAL[(M[,D])]字符串不适用
布尔值
MySQL 以特定的方式在内部处理 BOOLEAN 值。BOOLEAN 列内部映射到 TINYINT (1) 数据类型。在流过程中创建表时，它使用正确的 BOOLEAN 映射，因为 Debezium 接收原始 DDL。在快照过程中，Debebe 执行 SHOW CREATE TABLE 以获取为 BOOLEAN 和 TINYINT (1) 返回 TINYINT (1) 栏的表定义。然后 Debezium 无法获取原始类型映射，因此映射到 TINYINT (1)。
为了允许您将源列转换为布尔值数据类型，Debebe 提供了一个 TinyIntOneTo BooleanConverter 自定义转换器，您可使用以下方法之一使用：
-
将所有
TINYINT (1)或TINYINT (1) UNSIGNED列映射到BOOLEAN类型。 使用以逗号分隔的正则表达式列表枚举列的子集。
要使用这种类型的转换，您必须使用selector参数设置转换器配置属性，如下例所示：converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.selector=db1.table1.*, db1.table2.column1
converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.selector=db1.table1.*, db1.table2.column1Copy to Clipboard Copied! Toggle word wrap Toggle overflow 注意：在某些情况下，当快照执行
SHOW CREATE TABLE时，数据库可能不会显示tinyint的长度，这意味着此转换器不起作用。新选项length.checker可以解决这个问题，默认值为true。禁用length.checker，并指定需要转换为所选属性的列，而不是根据类型转换所有列，如下例所示：converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.length.checker=false boolean.selector=db1.table1.*, db1.table2.column1
converters=boolean boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter boolean.length.checker=false boolean.selector=db1.table1.*, db1.table2.column1Copy to Clipboard Copied! Toggle word wrap Toggle overflow
空间类型
目前，Debezium MySQL 连接器支持以下空间数据类型。
| MySQL 类型 | 字面类型 | 语义类型 |
|---|---|---|
|
|
|
|
2.4.4. 将 MySQL 数据映射到替代数据类型的自定义转换器
默认情况下，Debezium MySQL 连接器为 MySQL 数据类型提供多个 CustomConverter 实现。这些自定义转换器根据连接器配置为特定数据类型提供替代映射。要在连接器中添加 CustomConverter，请按照 Custom Converters 文档中的 说明进行操作。
TINYINT (1) 用于布尔值
默认情况下，在连接器快照过程中，Debebe MySQL 连接器从 JDBC 驱动程序获取列类型，它将 TINYINT (1) 类型分配给 BOOLEAN 列。然后 Debezium 使用这些 JDBC 列类型来定义快照事件的 schema。连接器从快照过渡到 streaming 阶段后，从默认映射中生成的更改事件模式可能会导致 BOOLEAN 列的映射不一致。为了帮助确保 MySQL 发送 BOOLEAN 列统一，您可以应用自定义 TinyIntOneToBooleanConverter，如以下配置示例所示。
示例： TinyIntOneToBooleanConverter 配置
converters=tinyint-one-to-boolean tinyint-one-to-boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter tinyint-one-to-boolean.selector=.*.MY_TABLE.DATA tinyint-one-to-boolean.length.checker=false
converters=tinyint-one-to-boolean
tinyint-one-to-boolean.type=io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter
tinyint-one-to-boolean.selector=.*.MY_TABLE.DATA
tinyint-one-to-boolean.length.checker=false
在前面的示例中，选择器和 length.checker 属性是可选的。默认情况下，转换器检查 TINYINT 数据类型是否符合 1 的长度。如果 length.checker 为 false，则不会明确地确认 TINYINT 数据类型符合 1 的长度。选择器 根据提供的正则表达式指定要转换的表或列。如果省略 selector 属性，则转换器将所有 TINYINT 列映射到逻辑 BOOL 字段类型。如果您没有配置 选择器 选项，并且您要将 TINYINT 列映射到 TINYINT (1)，请省略 length.checker 属性，或者将其值设为 true。
JDBC sink 数据类型
如果您将 Debezium JDBC sink 连接器与 Debezium MySQL 源连接器集成，MySQL 连接器会在快照和流阶段以不同的方式发出一些列属性。要使 JDBC sink 连接器一致消耗快照和流阶段的更改，您必须包含 JdbcSinkDataTypesConverter converter 作为 MySQL 源连接器配置的一部分，如下例所示：
示例：J dbcSinkDataTypesConverter 配置
在前面的示例中，selectorSetConfiguration 和 treat.real.as.double 配置属性是可选的。
selector SetConfiguration 属性指定以逗号分隔的正则表达式列表，用于指定转换器应用到的表和列。默认情况下，转换器对所有表中的所有布尔值、真实和基于字符串的列数据类型应用以下规则：
-
BOOLEAN数据类型始终作为INT16逻辑类型发送，1代表true，0代表false -
REAL数据类型始终作为FLOAT64逻辑类型发送。 -
基于字符串的列始终包括
__debezium.source.column.character_setschema 参数，其中包含列的字符集。
对于每个数据类型，您可以配置选择器规则来覆盖默认范围，并仅将选择器应用到特定的表和列。例如，要设置布尔值转换器的范围，请将以下规则添加到连接器配置中，如上例中所示： converters.jdbc-sink.selector.boolean=pulpcore.MY_TABLE.BOOL_COL
2.4.5. 设置 MySQL 以运行 Debezium 连接器
在安装和运行 Debezium 连接器前，需要一些 MySQL 设置任务。
详情包括在以下部分中：
2.4.5.1. 为 Debezium 连接器创建 MySQL 用户
Debezium MySQL 连接器需要一个 MySQL 用户帐户。这个 MySQL 用户必须具有对 Debezium MySQL 连接器捕获更改的所有数据库的适当权限。
先决条件
- MySQL 服务器。
- SQL 命令的基本知识。
流程
创建 MySQL 用户：
mysql> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';
mysql> CREATE USER 'user'@'localhost' IDENTIFIED BY 'password';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 为用户授予所需的权限：
mysql> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';
mysql> GRANT SELECT, RELOAD, SHOW DATABASES, REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'user' IDENTIFIED BY 'password';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 有关所需权限的描述，请参考 表 2.95 “用户权限的描述”。
重要如果使用 Amazon RDS 或 Amazon Aurora 等托管选项，不允许全局读取锁定，则使用表级锁定来创建 一致的快照。在这种情况下，您还需要为您创建的用户授予
LOCK TABLES权限。如需了解更多详细信息，请参阅 快照。完成用户权限：
mysql> FLUSH PRIVILEGES;
mysql> FLUSH PRIVILEGES;Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.95. 用户权限的描述 关键字 描述 选择启用连接器从数据库中的表选择行。这仅在执行快照时使用。
重新加载启用连接器使用
FLUSH语句来清除或重新载入内部缓存、清除表或获取锁定。这仅在执行快照时使用。显示数据库通过发出
SHOW DATABASE语句来启用连接器查看数据库名称。这仅在执行快照时使用。复制从设备启用连接器连接并读取 MySQL 服务器 binlog。
复制客户端启用连接器使用以下语句：
-
显示 MASTER 状态 -
显示从状态 -
SHOW BINARY LOGS
连接器始终需要它。
ON标识应用权限的数据库。
TO 'user'指定要授予权限的用户。
IDENTIFIED BY 'password'指定用户的 MySQL 密码。
-
2.4.5.2. 为 Debezium 启用 MySQL binlog
您必须为 MySQL 复制启用二进制日志记录。二进制日志记录事务更新的方式，使副本能够传播这些更改。
先决条件
- MySQL 服务器。
- 适当的 MySQL 用户特权。
流程
-
检查是否启用了
log-bin选项： 如果 binlog 是
OFF，请将下表中的属性添加到 MySQL 服务器的配置文件中：server-id = 223344 # Querying variable is called server_id, e.g. SELECT variable_value FROM information_schema.global_variables WHERE variable_name='server_id'; log_bin = mysql-bin binlog_format = ROW binlog_row_image = FULL binlog_expire_logs_seconds = 864000
server-id = 223344 # Querying variable is called server_id, e.g. SELECT variable_value FROM information_schema.global_variables WHERE variable_name='server_id'; log_bin = mysql-bin binlog_format = ROW binlog_row_image = FULL binlog_expire_logs_seconds = 864000Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 通过再次检查 binlog 状态来确认您的更改：
如果在 Amazon RDS 上运行 MySQL，则必须为您的数据库实例启用自动备份，以便进行二进制日志记录。如果没有将数据库实例配置为执行自动备份，则禁用 binlog，即使您应用了前面步骤中描述的设置。
Expand 表 2.96. MySQL binlog 配置属性的描述 属性 描述 server-idserver-id的值对于 MySQL 集群中的每台服务器和复制客户端必须是唯一的。log_binlog_bin的值是 binlog 文件序列的基本名称。binlog_formatbinlog-format必须设为 ROW或行。binlog_row_imagebinlog_row_image必须设置为FULL或full。binlog_expire_logs_secondsbinlog_expire_logs_seconds对应于已弃用的系统变量expire_logs_days。这是自动 binlog 文件删除的秒数。默认值为2592000，它等于 30 天。设置该值以匹配您的环境需求。如需更多信息，请参阅 MySQL 清除 binlog 文件。
2.4.5.3. 为 Debezium 启用 MySQL 全局事务标识符
全局事务标识符(GTID)唯一标识集群中服务器上发生的事务。虽然 Debezium MySQL 连接器不需要，但使用 GTID 简化了复制，并可让您更轻松地确认主和副本服务器是否一致。
在 MySQL 5.6.5 及更高版本中提供 GTID。详情请查看 MySQL 文档。
先决条件
- MySQL 服务器。
- SQL 命令的基本知识。
- 访问 MySQL 配置文件。
流程
启用
gtid_mode：mysql> gtid_mode=ON
mysql> gtid_mode=ONCopy to Clipboard Copied! Toggle word wrap Toggle overflow 启用
enforce_gtid_consistency:mysql> enforce_gtid_consistency=ON
mysql> enforce_gtid_consistency=ONCopy to Clipboard Copied! Toggle word wrap Toggle overflow 确认更改：
mysql> show global variables like '%GTID%';
mysql> show global variables like '%GTID%';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 结果
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.97. GTID 选项的描述 选项 描述 gtid_mode指定是否启用 MySQL 服务器的 GTID 模式布尔值。
-
ON= enabled -
OFF= disabled
enforce_gtid_consistency布尔值指定服务器是否通过允许执行可以以事务安全方式登录的语句来强制实施 GTID 一致性。使用 GTID 时需要。
-
ON= enabled -
OFF= disabled
-
2.4.5.4. 为 Debezium 配置 MySQL 会话超时
当为大型数据库生成初始一致的快照时，您建立的连接可能会在读取表时超时。您可以通过在 MySQL 配置文件中配置 interactive_timeout 和 wait_timeout 来防止此行为。
先决条件
- MySQL 服务器。
- SQL 命令的基本知识。
- 访问 MySQL 配置文件。
流程
配置
interactive_timeout：mysql> interactive_timeout=<duration-in-seconds>
mysql> interactive_timeout=<duration-in-seconds>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 配置
wait_timeout：mysql> wait_timeout=<duration-in-seconds>
mysql> wait_timeout=<duration-in-seconds>Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.98. MySQL 会话超时选项的描述 选项 描述 interactive_timeout服务器在关闭之前在互动连接上等待活动的秒数。如需更多信息，请参阅：
wait_timeout服务器在关闭之前在非互动连接上等待活动的秒数。
2.4.5.5. 为 Debezium MySQL 连接器启用查询日志事件
您可能希望查看每个 binlog 事件的原始 SQL 语句。在 MySQL 配置文件中启用 binlog_rows_query_log_events 选项，您可以执行此操作。
此选项在 MySQL 5.6 及更高版本中提供。
先决条件
- MySQL 服务器。
- SQL 命令的基本知识。
- 访问 MySQL 配置文件。
流程
在 MySQL 中启用
binlog_rows_query_log_events：mysql> binlog_rows_query_log_events=ON
mysql> binlog_rows_query_log_events=ONCopy to Clipboard Copied! Toggle word wrap Toggle overflow binlog_rows_query_log_events设置为一个值，它启用了/禁用对在 binlog 条目中包括原始SQL语句的支持。-
ON= enabled -
OFF= disabled
-
2.4.5.6. 验证 Debezium MySQL 连接器的 binlog 行值选项
验证数据库中 binlog_row_value_options 变量的设置。要让连接器消耗 UPDATE 事件，此变量必须设置为 PARTIAL_JSON 以外的值。
先决条件
- MySQL 服务器。
- SQL 命令的基本知识。
- 访问 MySQL 配置文件。
流程
检查当前变量值
mysql> show global variables where variable_name = 'binlog_row_value_options';
mysql> show global variables where variable_name = 'binlog_row_value_options';Copy to Clipboard Copied! Toggle word wrap Toggle overflow 结果
+--------------------------+-------+ | Variable_name | Value | +--------------------------+-------+ | binlog_row_value_options | | +--------------------------+-------+
+--------------------------+-------+ | Variable_name | Value | +--------------------------+-------+ | binlog_row_value_options | | +--------------------------+-------+Copy to Clipboard Copied! Toggle word wrap Toggle overflow 如果 变量的值被设置为
PARTIAL_JSON，请运行以下命令来取消设置它：mysql> set @@global.binlog_row_value_options="" ;
mysql> set @@global.binlog_row_value_options="" ;Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.4.6. 部署 Debezium MySQL 连接器
您可以使用以下任一方法部署 Debezium MySQL 连接器：
2.4.6.1. 使用 Streams for Apache Kafka 进行 MySQL 连接器部署
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
2.4.6.2. 使用 Apache Kafka 的 Streams 部署 Debezium MySQL 连接器
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅 OpenShift Container Platform 文档中的管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.26. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium MySQL 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关脚本引擎。SMT 归档和脚本语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.99. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Red Hat Maven 存储库中提供了 Debezium 连接器工件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需的脚本语言组件
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
作为替代方案，Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为mysql-inventory-connector.yaml例 2.27.
mysql-inventory-connector.yaml文件，为 Debezium 连接器定义KafkaConnector自定义资源Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.100. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址。
6
数据库实例的端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
9
连接器的唯一数字 ID。
10
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。11
连接器捕获更改事件的表列表。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f mysql-inventory-connector.yaml
oc create -n debezium -f mysql-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
要部署 Debezium MySQL 连接器，您必须构建包含 Debezium 连接器存档的自定义 Kafka Connect 容器镜像，然后将此容器镜像推送到容器 registry。然后，您需要创建以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium MySQL 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- MySQL 正在运行，您完成了 设置 MySQL 以使用 Debezium 连接器 的步骤。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka 流。
- podman 或 Docker 已安装。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。
流程
为 Kafka Connect 创建 Debezium MySQL 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-mysql.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-mysql.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-mysql:latest .
podman build -t debezium-container-for-mysql:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-mysql:latest .
docker build -t debezium-container-for-mysql:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令使用名称
debezium-container-for-mysql构建容器镜像。将自定义镜像推送到容器 registry，如
quay.io或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：podman push <myregistry.io>/debezium-container-for-mysql:latest
podman push <myregistry.io>/debezium-container-for-mysql:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-mysql:latest
docker push <myregistry.io>/debezium-container-for-mysql:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium MySQL
KafkaConnect自定义资源(CR)。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。输入以下命令将
KafkaConnectCR 应用到 OpenShift Kafka Connect 环境：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令添加一个 Kafka Connect 实例，用于指定为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium MySQL 连接器实例。您可以在指定连接器的配置属性的
.yaml文件中配置 Debezium MySQL 连接器。连接器配置可能会指示 Debezium 为模式和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略、掩码或截断指定列中的值，这些值是敏感、太大或不需要的。以下示例配置了一个 Debezium 连接器，它连接到 MySQL 主机
192.168.99.100，使用端口3306，它会捕获inventory数据库的更改。dbserver1是服务器的逻辑名称。MySQL
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.101. 连接器配置设置的描述 项 描述 1
连接器的名称。
2
只在任何时候只能运行一个任务。由于 MySQL 连接器读取 MySQL 服务器的
binlog，因此使用单一连接器任务来确保正确顺序和事件处理。Kafka Connect 服务使用连接器启动一个或多个完成工作的任务，并在 Kafka Connect 服务集群中自动分发正在运行的任务。如果有任何服务停止或崩溃，则这些任务将重新分发到运行的服务。3
连接器的配置。
4
数据库主机，这是运行 MySQL 服务器的容器的名称(
mysql)。5
连接器的唯一 ID。
6
MySQL 服务器或集群的主题前缀。此名称用作接收更改事件记录的所有 Kafka 主题的前缀。
7
连接器只捕获
inventory表中的更改。8
此连接器将用于写入和恢复 DDL 语句的 Kafka 代理列表到数据库 schema 历史记录主题。重启后，当连接器应开始读取时，连接器会在 binlog 中一次恢复存在的数据库模式。
9
数据库架构历史记录主题的名称。本主题仅用于内部使用，不应供消费者使用。
使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的inventory数据库运行。
有关您可以为 Debezium MySQL 连接器设置的配置属性的完整列表，请参阅 MySQL 连接器配置属性。
结果
连接器启动后，它会对配置了连接器的 MySQL 数据库 执行一致的快照。然后，连接器开始为行级操作生成数据更改事件，并将更改事件记录流传输到 Kafka 主题。
2.4.6.4. 验证 Debezium MySQL 连接器是否正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，单击要检查的连接器名称，如 inventory-connector-mysql。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-mysql -n debezium
oc describe KafkaConnector inventory-connector-mysql -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.28.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，单击要检查的主题的名称，例如
inventory-connector-mysql.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.29.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-mysql.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-mysql.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中返回的
oc describe命令相同，例如inventory-connector-mysql.inventory.addresses。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.30. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-mysql.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mysql.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mysql.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.mysql.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-mysql.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"mysql","name":"inventory-connector-mysql","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"mysql-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-mysql.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mysql.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-mysql.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.mysql.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-mysql.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"mysql","name":"inventory-connector-mysql","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"mysql-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
2.4.6.5. Debezium MySQL 连接器配置属性的描述
Debezium MySQL 连接器有许多配置属性，可用于为应用程序获得正确的连接器行为。许多属性具有默认值。有关属性的信息按如下方式进行组织：
- 所需的连接器配置属性
- 高级连接器配置属性
- 数据库架构历史记录连接器配置属性，用于控制 Debezium 如何处理从数据库架构历史记录主题读取的事件。
所需的 Debezium MySQL 连接器配置属性
除非默认值可用 ， 否则需要以下配置属性。
bigint.unsigned.handling.mode
默认值 ：
指定连接器如何代表更改事件中的 BIGINT UNSIGNED 列。设置以下选项之一：long-
使用 Java
长数据类型来代表 BIGINT UNSIGNED 列值。虽然长类型不提供最大精度，但在大多数消费者中很容易实现。在大多数环境中，这是首选设置。 precise-
使用
java.math.BigDecimal数据类型来表示值。连接器使用 Kafka Connectorg.apache.kafka.connect.data.Decimal数据类型来代表编码的二进制格式的值。如果连接器通常与大于 2^63 的值一起使用，则设置这个选项。长数据类型无法传递该大小的值。
binary.handling.mode默认值：
bytes
指定连接器如何代表二进制列的值，如blob、二进制、varbinary、更改事件。
设置以下选项之一：bytes- 将二进制数据表示为字节数组。
base64- 将二进制数据表示为 base64 编码的字符串。
base64-url-safe- 将二进制数据表示为 base64-url-safe-encoded String。
hex- 将二进制数据表示为十六进制编码(base16)字符串。
column.exclude.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与要从更改事件记录值中排除的列的完全限定名称匹配。源记录中的其他列会正常捕获。列的完全限定域名格式为 databaseName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。如果您在配置中包含此属性，不要设置
column.include.list属性。
column.include.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，该表达式与要包含在更改事件记录值中的列的完全限定名称匹配。事件记录中省略了其他列。列的完全限定域名格式为 databaseName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。
如果您在配置中包含此属性，请不要设置column.exclude.list属性。
column.mask.hash.v2.hashAlgorithm.with.salt.salt默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与基于字符的列的完全限定域名匹配。列的完全限定域名格式为 <databaseName> . <tableName & gt; . <columnName>。
要匹配 Debezium 的名称，请使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。在生成的更改事件记录中，指定列的值将被 pseudonyms 替代。
pseudonym 由一个散列值组成，结果是应用指定的 hashAlgorithm 和 salt 的结果。根据使用的 hash 功能，引用完整性会被维护，而列值则替换为 pseudonyms。Java 加密架构标准算法 文档的 MessageDigest 部分中 描述了支持的哈希功能。
在以下示例中，
CzQMA0cB5K是一个随机选择的 salt。column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName
column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerNameCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如有必要，pseudonym 会自动缩短到列的长度。连接器配置可以包含多个属性，以指定不同的哈希算法和 salt。
根据使用的 hashAlgorithm，所选的 salt 和实际数据集，可能无法完全屏蔽。
哈希策略版本 2 可确保在不同位置或系统中哈希的值。
column.mask.with.length.chars默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与基于字符的列的完全限定域名匹配。如果您希望连接器屏蔽一组列的值，例如，如果它们包含敏感数据，则设置此属性。将length设置为一个正整数，替换在属性名称中的 length 指定的星号（*）的数量列中的数据。将 length 设置为0(zero)，将指定列中的数据替换为空字符串。列的完全限定域名观察以下格式： databaseName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。
您可以在单个配置中指定多个长度不同的属性。
column.propagate.source.type默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与您希望连接器发送代表列元数据的额外参数匹配。当设置此属性时，连接器将以下字段添加到事件记录的 schema 中：-
__debezium.source.column.type -
__debezium.source.column.length -
__debezium.source.column.scale
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
启用连接器来发送此额外数据有助于在 sink 数据库中正确调整特定数字或基于字符的列。
列的完全限定域名观察以下格式之一： databaseName.tableName.columnName, 或 databaseName.schemaName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。
-
column.truncate.to.length.chars默认值 ：没有默认值
一个可选的、以逗号分隔的正则表达式列表，该表达式与基于字符的列的完全限定域名匹配。如果在列中的数据超过了在属性名中的 length 指定的字符长度时删节数据，设置此属性。将length设置为正整数值，例如column.truncate.to.20.chars。列的完全限定域名观察以下格式： databaseName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。
您可以在单个配置中指定多个长度不同的属性。
connect.timeout.ms-
默认值：
30000(30 秒)
一个正整数值，用于指定连接器在连接请求超时前等待与 MySQL 数据库服务器建立连接的最长时间，以毫秒为单位。
connector.class-
默认值： No default
连接器的 Java 类的名称。始终为 MySQL 连接器指定。
database.exclude.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与您不想连接器捕获更改的数据库名称匹配。连接器捕获任何没有在database.exclude.list中命名的数据库中的更改。
要匹配数据库的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与数据库的整个名称字符串匹配；它不匹配数据库名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置database.include.list属性。
database.hostname-
默认值 ：无默认值
MySQL 数据库服务器的 IP 地址或主机名。
database.include.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与连接器捕获更改的数据库名称匹配。连接器不会捕获名称不在database.include.list的任何数据库中的更改。默认情况下，连接器捕获所有数据库中的更改。
要匹配数据库的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与数据库的整个名称字符串匹配；它不匹配数据库名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置database.exclude.list属性。
database.password-
默认值 ：无默认值
连接器用来连接到 MySQL 数据库服务器的 MySQL 用户的密码。
database.port-
默认值：
3306
整数 MySQL 数据库服务器的端口号。
database.server.id-
默认值 ：没有默认值
此数据库客户端的数字 ID。指定 ID 必须在 MySQL 集群中所有当前运行的数据库进程之间唯一。要让它读取 binlog，连接器使用此唯一 ID 将 MySQL 数据库集群作为另一个服务器加入。
database.user-
默认值： No default
连接器用来连接到 MySQL 数据库服务器的 MySQL 用户的名称。
decimal.handling.mode默认值 ：
精确
指定连接器如何处理更改事件中的DECIMAL和NUMERIC字段的值。
设置以下选项之一：precise（默认）-
以二进制形式使用
java.math.BigDecimal值来精确表示值。 double-
使用
双数据类型表示值。这个选项可能会导致精度丢失，但大多数消费者更易于使用。 string- 将值编码为格式化字符串。这个选项易于使用，但可能会导致实际类型丢失语义信息。
event.deserialization.failure.handling.mode默认值 ：
fail
指定连接器在 binlog 事件反序列化过程中如何响应异常。这个选项已弃用，请使用event.processing.failure.handling.mode选项。fail- 传播异常，表示有问题的事件及其 binlog 偏移，并导致连接器停止。
warn- 记录有问题的事件及其 binlog 偏移，然后跳过事件。
ignore- 传递有问题的事件，不会记录任何内容。
field.name.adjustment.mode默认值： No default
指定应该如何调整字段名称，以便与连接器使用的消息转换器兼容。设置以下选项之一：none- 无调整。
avro- 使用下划线字符替换在 Avro 名称中无效的字符。
avro_unicode将 Avro 名称中无法使用的下划线字符或字符替换为对应的 unicode，如
_uxxxx。
注意`_` is an escape sequence, similar to a backslash in Java
`_` is an escape sequence, similar to a backslash in JavaCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如需更多信息，请参阅： Avro 命名。
gtid.source.excludes-
默认值 ：没有默认值
以逗号分隔的正则表达式列表，该表达式与 GTID 集中的源域 ID 匹配，连接器用来查找 MySQL 服务器上的 binlog 位置。当设置此属性时，连接器只使用具有与任何指定排除模式不匹配的源 UUID 的 GTID 范围。
要匹配 GTID 的值，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 GTID 的域标识符匹配。
如果您在配置中包含此属性，不要同时设置gtid.source.includes属性。
gtid.source.includes-
默认值 ：没有默认值
以逗号分隔的正则表达式列表，该表达式与 GTID 集合中的源域 ID 匹配，用于连接器用来查找 MySQL 服务器上的 binlog 位置。当设置此属性时，连接器只使用具有与其中一个包括模式匹配的源 UUID 的 GTID 范围。
要匹配 GTID 的值，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 GTID 的域标识符匹配。
如果您在配置中包含此属性，不要同时设置gtid.source.excludes属性。
include.query-
默认值：
false
布尔值指定连接器是否应该包含生成更改事件的原始 SQL 查询。
如果将此选项设置为true，那么您还必须将binlog_annotate_row_events选项设置为ON来配置 MySQL。当include.query为true时，对快照进程生成的事件不存在查询。
将include.query设置为true可能会公开通过在更改事件中包含原始 SQL 语句来明确排除或屏蔽的表或字段。因此，默认设置为false。
有关配置数据库为每个日志事件返回原始SQL语句的更多信息，请参阅启用查询日志事件。
include.schema.changes-
默认值：
true
布尔值指定连接器是否将数据库 schema 发生的更改发布到带有数据库服务器 ID 名称的 Kafka 主题。连接器捕获的每个架构更改事件都使用一个键，其中包含数据库名称和一个包括描述更改的 DDL 语句的值。此设置不会影响连接器记录其内部数据库架构历史记录中的模式更改的方式。
include.schema.comments默认值：
false
布尔值指定连接器是否解析并发布元数据对象上的表和列注释。
注意当您将这个选项设置为
true时，连接器包含的 schema 注释可为每个 schema 对象添加大量字符串数据。增加逻辑模式对象的数量和大小会增加连接器使用的内存量。
inconsistent.schema.handling.mode默认值 ：
fail
指定连接器如何响应 binlog 事件，这些事件引用内部模式表示中不存在的表。也就是说，内部表示与数据库不一致。
设置以下选项之一：fail- 连接器会抛出一个报告有问题的事件及其 binlog 偏移的异常。然后，连接器会停止。
warn- 连接器会记录有问题的事件及其 binlog 偏移，然后跳过事件。
skip- 连接器跳过有问题的事件，且不会在日志中报告它。
message.key.columns-
默认值 ：没有默认值
一个表达式列表，用于指定连接器用来组成自定义消息键，用于更改它发布到指定表的 Kafka 主题的事件记录。
默认情况下，Debebe 使用表的主键列作为发出的记录的消息键。使用默认键，或者为缺少主密钥的表指定一个键，您可以根据一个或多个列配置自定义消息密钥。
要为表建立自定义消息密钥，请列出表，后跟要用作消息键的列。每个列表条目都采用以下格式：
<fully-qualified_tableName> : & lt;keyColumn>, <keyColumn>
To base a table key on multiple column name, insert commas between the column name.
每个完全限定表名称都是以下格式的正则表达式：
<databaseName> . & lt;tableName>
属性可以包含多个表的条目。使用分号分隔列表中的表条目。
以下示例为表inventory.customers和purchase.orders设置了消息键：inventory.customers:pk1,pk2; (configured).purchaseorders:pk3,pk4
用于表inventory.customer，列pk1和pk2指定为消息键。对于任何数据库中的purchaseorders表，列pk3和pk4服务器作为消息键。
对用来创建自定义消息键的列数量没有限制。但是，最好使用指定唯一密钥所需的最小数量。
name-
默认值 ：连接器没有默认值
唯一名称。如果您试图使用相同的名称注册另一个连接器，注册会失败。所有 Kafka Connect 连接器都需要此属性。
schema.name.adjustment.mode默认值 ： No default
指定连接器如何调整 schema 名称，以便与连接器使用的消息转换器兼容。设置以下选项之一：none- 无调整。
avro- 使用下划线字符替换在 Avro 名称中无效的字符。
avro_unicode-
将 Avro 名称中无法使用的下划线字符或字符替换为对应的 unicode，如
_uxxxx。
注意：_是一个转义序列，类似于 Java 中的反斜杠
skip.messages.without.change-
默认值：
false
指定当连接器没有检测包含列中的更改时，连接器是否为记录发出信息。如果列.include.list 中列出了列，或者未列在column.exclude.list中，则这些列将被视为包含true以防止连接器在包含列中没有更改时捕获记录。
table.exclude.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与您不希望连接器捕获更改的表的完全限定表标识符匹配。连接器捕获table.exclude.list中没有包括的任何更改。每个标识符都是 databaseName.tableName 的形式。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置table.include.list属性。
table.include.list默认值： 空字符串
一个可选的、以逗号分隔的正则表达式列表，与您要捕获的表的完全限定表标识符匹配。连接器不会捕获表.include.list中不包含的任何表中的更改。每个标识符都是 databaseName.tableName 的形式。默认情况下，连接器捕获从其中配置为捕获更改的每个数据库中的所有非系统表中的更改。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
如果您在配置中包含此属性，不要设置table.exclude.list属性。
tasks.max-
默认值：
1
为此连接器创建的最大任务数。因为 MySQL 连接器始终使用单个任务，所以更改默认值无效。
time.precision.mode默认值 ：
adaptive_time_microseconds
指定连接器用来表示时间、日期和时间戳值的精度类型。设置以下选项之一：
adaptive_time_microseconds(default)-
连接器会捕获数据库中日期、日期时间和时间戳值，使用 millisecond、microsecond 或 nanosecond 精度值（基于数据库列的类型），但 TIME 类型字段除外，它们始终捕获为微秒。
connect- 连接器总是使用 Kafka Connect 的内置表示 Time, Date, 和 Timestamp 代表时间和时间戳的值，无论数据库列的精度是什么。
tombstones.on.delete默认值：
true
指定 delete 事件是否后跟一个 tombstone 事件。删除源记录后，连接器可以发出 tombstone 事件（默认行为），使 Kafka 能够完全删除与已删除行的密钥相关的所有事件，以防为主题启用了 日志压缩。设置以下选项之一：
true（默认）-
连接器通过发出 delete 事件和后续的 tombstone 事件来代表删除操作。
false-
连接器只发出 删除 事件。
topic.prefix默认值 ：没有 default
主题前缀，为 Debezium 捕获更改的特定 MySQL 数据库服务器或集群提供命名空间。因为主题前缀用于命名接收此连接器发出的事件的所有 Kafka 主题，所以主题前缀在所有连接器中都是唯一的。值只能包含字母数字字符、连字符、句点和下划线。
警告设置此属性后，请勿更改其值。如果您更改了值，在连接器重启后，而不是继续向原始主题发送事件，连接器会向名称基于新值的主题发出后续事件。连接器也无法恢复其数据库架构历史记录主题。
高级 Debezium MySQL 连接器配置属性
以下列表描述了高级 MySQL 连接器配置属性。这些属性的默认值很少需要更改。因此，您不需要在连接器配置中指定它们。
connect.keep.alive-
默认值：
true
一个布尔值，用于指定是否应使用单独的线程来确保与 MySQL 服务器或集群的连接保持活动状态。
转换器默认值 ：没有默认值
枚举连接器可以使用的 自定义转换器 实例的符号链接名称列表。
例如，布尔值。
需要此属性才能使连接器使用自定义转换器。
对于您为连接器配置的每个转换器，还必须添加一个.type属性，它指定实现转换器接口的类的完全限定域名。.type属性使用以下格式：
<converterSymbolicName>.type例如，
boolean.type: io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverter
boolean.type: io.debezium.connector.binlog.converters.TinyIntOneToBooleanConverterCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如果要进一步控制配置的转换器的行为，您可以添加一个或多个配置参数来将值传递给转换器。要将这些额外的配置参数与转换器关联，请为参数名称添加转换器符号名称作为前缀。
例如，要定义一个
selector参数，用于指定布尔值转换器进程的列子集，请添加以下属性：
boolean.selector=db1.table1.*, db1.table2.column1
boolean.selector=db1.table1.*, db1.table2.column1Copy to Clipboard Copied! Toggle word wrap Toggle overflow
custom.metric.tags-
默认值 ：没有默认值
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如k1=v1,k2=v2
。连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。
database.initial.statements默认值：没有默认值
当 JDBC 连接而不是读取事务日志的连接时要执行的 SQL 语句列表。要将分号指定为 SQL 语句中的字符而不是分隔符，请使用两个分号(;;)。
连接器可以自行决定建立 JDBC 连接，因此此属性是配置会话参数。它不执行 DML 语句。
database.query.timeout.ms-
默认值：
600000(10 分钟)
指定连接器等待查询完成的时间（以毫秒为单位）。将值设为0（零）以删除超时限制。
database.ssl.keystore-
默认值： No default
指定密钥存储文件的位置的可选设置。密钥存储文件可用于客户端和 MySQL 服务器之间的双向身份验证。
database.ssl.keystore.password-
默认值 ：无默认值
密钥存储文件的密码。仅在配置了database.ssl.keystore时指定密码。
database.ssl.mode默认值 ：
首选
指定连接器是否使用加密连接。可用的设置如下：disabled- 指定使用未加密的连接。
preferred（默认）- 如果服务器支持安全连接，则连接器建立一个加密连接。如果服务器不支持安全连接，连接器会返回使用未加密的连接。
required- 连接器建立一个加密的连接。如果无法建立加密连接，连接器会失败。
verify_ca-
连接器的行为与设置
所需选项时的行为，但它也会根据配置的证书颁发机构(CA)证书验证服务器 TLS 证书。如果服务器 TLS 证书与任何有效的 CA 证书不匹配，则连接器会失败。
verify_identity-
当您设置
verify_ca选项时，连接器的行为与设置 verify_ca 选项一样，它还验证服务器证书是否与远程连接的主机匹配。
database.ssl.truststore-
默认值 ：无默认值
服务器证书验证的信任存储文件的位置。
database.ssl.truststore.password-
默认值 ：无默认值
信任存储文件的密码。用于检查信任存储的完整性，并解锁信任存储。
enable.time.adjuster默认值：
true
布尔值表示连接器是否将 2 位规格转换为 4 位。当转换完全委派给数据库时，将值设为false。
MySQL 用户可使用 2 位或 4 位插入年值。2 位值映射到970 到 2069 范围内的一年。默认情况下，连接器执行转换。
errors.max.retries默认值：
-1
指定连接器在操作后如何响应导致可重试错误，如连接错误。
设置以下选项之一：-1- 无限制。无论之前失败的数量如何，连接器总是自动重启，并重试操作。
0- disabled。连接器会立即失败，永远不会重试操作。重启连接器需要用户干预。
> 0- 连接器会自动重启，直到达到指定的最大重试次数。下一次失败后，连接器会停止，用户需要干预才能重启它。
event.converting.failure.handling.mode默认值 ：
警告
指定连接器无法转换表记录时如何响应，因为列的数据类型和 Debezium 内部模式指定的类型不匹配。
设置以下选项之一：fail-
一个异常报告，因为字段的数据类型与 schema 类型不匹配，并表示可能需要在
schema _only_recovery模式中重启连接器来启用成功转换。 warn-
连接器将
null值写入失败的列的 event 字段，将消息写入警告日志。
skip-
连接器将
null值写入失败的列的 event 字段，并将消息写入 debug 日志。
event.processing.failure.handling.mode默认值 ：
fail
指定连接器如何处理处理事件时出现的故障，例如，如果它遇到损坏的事件。可用的设置如下：fail- 连接器会引发一个报告有问题的事件及其位置的异常。然后，连接器会停止。
warn- 连接器不会引发异常。相反，它会记录有问题的事件及其位置，然后跳过事件。
ignore- 连接器忽略有问题的事件，且不会生成日志条目。
heartbeat.action.query默认值： No default
指定当连接器发送 heartbeat 信息时，连接器在源数据库上执行的查询。
例如，以下查询会定期捕获源数据库中设置的已执行 GTID 的状态。
INSERT INTO gtid_history_table （选择 @gtid_executed）
heartbeat.interval.ms默认值 ：
0
指定连接器将心跳消息发送到 Kafka 主题的频率。默认情况下，连接器不会发送 heartbeat 信息。
心跳消息可用于监控连接器是否接收来自数据库的更改事件。心跳消息可能会帮助减少连接器重启时需要重新更改事件的数量。要发送心跳消息，请将此属性设置为正整数，这表示心跳消息之间的毫秒数。
incremental.snapshot.allow.schema.changes-
默认值：
false
指定连接器是否允许增量快照中的模式更改。当值设为true时，连接器会在增量快照期间检测到 schema 变化，并重新选择当前块以避免锁定 DDL。
不支持对主密钥的更改。在增量快照期间更改主设备可能会导致结果不正确。另一个限制是，如果模式更改仅影响列的默认值，则不会检测到更改，直到从 binlog 流处理 DDL。这不会影响快照事件的值，但这些快照事件的 schema 可能具有过时的默认值。
incremental.snapshot.chunk.size-
默认值 ：
1024
，连接器在检索增量快照块时获取并读取的最大行数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。
incremental.snapshot.watermarking.strategy默认值：
insert_insert
指定连接器在增量快照期间使用的水位线机制，以重复数据删除可能被增量快照捕获的事件，然后在流恢复后重新捕获。
您可以指定以下选项之一：insert_insert(default)- 当您发送一个信号来启动增量快照时，对于 Debezium 在快照期间读取的每个块，它会将条目写入信号数据收集来记录信号，以打开快照窗口。快照完成后，Debezium 会插入第二个条目，记录信号以关闭窗口。
insert_delete- 当您发送一个信号来启动增量快照时，对于 Debezium 读取的每个块，它会将单个条目写入信号数据收集，以记录信号来打开快照窗口。快照完成后，会删除此条目。不会为关闭快照窗口的信号创建条目。设置这个选项以防止快速增长信号数据收集。
max.batch.size-
默认值：
2048
Positive 整数值，用于指定此连接器每次迭代过程中应该处理的每个批处理事件的最大大小。
max.queue.size-
默认值 ：
8192
一个正整数值，用于指定阻塞队列可以容纳的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将max.queue.size设置为大于max.batch.size的值。
max.queue.size.in.bytes-
默认值 ：
0
一个长整数值，用于指定阻塞队列的最大卷（以字节为单位）。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。
如果也设置了max.queue.size，当队列的大小达到由任一属性指定的限制时，写入队列会被阻断。例如，如果您设置了max.queue.size=1000和max.queue.size.in.bytes=5000，则在队列包含 1000 个记录后写入队列会被阻断，或者在队列中的记录卷达到 5000 字节。
min.row.count.to.stream.results默认值 ：
1000
在快照过程中，连接器会查询将连接器配置为捕获更改的每个表。连接器使用每个查询结果生成读取事件，其中包含该表中所有行的数据。此属性决定 MySQL 连接器是否将表的结果放在内存中，但速度快，但需要大量内存或流结果，这可能会较慢，但适用于非常大的表。此属性的设置指定表在连接器流结果前必须包含的最小行数。
要跳过所有表大小检查，并且始终在快照中流出所有结果，请
将此属性设置为0。
notification.enabled.channels默认值 ：没有为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
-
sink -
log -
jmx
-
poll.interval.ms-
默认值：
500(0.5 秒)
Positive 整数值，用于指定连接器在开始处理一系列事件前等待新更改事件的毫秒数。
provide.transaction.metadata-
默认值：
false
确定连接器生成带有事务边界的事件，并增强了与事务元数据的更改事件。如果您希望连接器进行此操作，请指定true。如需更多信息，请参阅 事务元数据。
signal.data.collection-
默认值 ：用于向连接器发送信号的数据收集的完全限定名称。https://docs.redhat.com/documentation/en/red_hat_build_of_debezium/2.7.3/html-single/debezium_user_guide/index#debezium-signaling-enabling-source-signaling-channel
使用以下格式指定集合名称：
<databaseName> . < tableName>
signal.enabled.channels默认值 ：对于连接器启用的信号频道名称，没有默认值
列表。默认情况下，以下频道可用：-
source -
kafka -
file -
jmx
-
skipped.operations-
默认值 ：
t
以逗号分隔的操作类型列表，这些类型将在流过程中跳过。操作包括：c用于插入/创建，u用于更新，d表示删除，t代表截断，none不跳过任何操作。默认情况下会跳过截断操作。
snapshot.delay.ms- 默认值 ：在连接器启动时，连接器应在执行快照前等待的时间间隔（以毫秒为单位）。如果您要在集群中启动多个连接器，此属性可用于避免快照中断，这可能会导致连接器重新平衡。
snapshot.fetch.size-
默认值 ： Unset
默认情况下，在快照过程中，连接器会在行批处理中读取表内容。设置此属性以指定批处理中最大行数。
为了保持连接器性能，最好保留此属性的未设置默认值。这个默认配置可让 MySQL 一次将结果设置为 Debezium 一行。相反，如果您设置了此属性，则可能会出现性能问题，因为 Debezium 会尝试一次性将整个结果设置为内存中。
snapshot.include.collection.list-
默认值：
table.include.list中指定的所有表。
一个可选的、以逗号分隔的正则表达式列表，与表的完全限定域名(<databaseName>.<tableName>)匹配，包括在快照中。指定的项目必须在连接器的table.include.list属性中命名。只有在连接器的snapshot.mode属性设置为never以外的值时，此属性才会生效。
此属性不会影响增量快照的行为。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
snapshot.lock.timeout.ms-
默认值：
10000
Positive integer 指定执行快照时等待获取表锁定的最大时间（以毫秒为单位）。如果连接器无法在这个时间段内获取表锁定，则快照会失败。如需更多信息，请参阅
snapshot.locking.mode默认值 ：
最小
指定连接器保存全局 MySQL 读取锁定的时长，这样可防止在连接器执行快照时对数据库进行任何更新。可用的设置如下：Minimal-
连接器只保存全局读锁定，用于读取数据库模式和其他元数据的快照的初始阶段。在快照的下一阶段，连接器会释放锁定，因为它从每个表中选择所有行。要以一致的方式执行 SELECT 操作，连接器使用 REPEATABLE READ 事务。虽然全局读取锁定的发行版本允许 MySQL 客户端更新数据库，但使用 REPEATABLE READ 隔离可确保快照的一致性，因为连接器在事务期间继续读取相同的数据。
extended-
阻止快照持续时间的所有写入操作。如果客户端提交与 MySQL 中 REPEATABLE READ 隔离级别不兼容的并发操作，则使用此设置。
none- 防止连接器在快照过程中获取任何表锁定。虽然对所有快照模式都允许这个选项，但只有在 快照运行时没有更改架构时才安全使用。使用 MyISAM 引擎定义的表始终获取表锁定。因此，即使您设置了这个选项，这些表也会被锁定。此行为与获得行级锁的 InnoDB 引擎定义的表不同。
snapshot.max.threads默认值 ：
1
指定连接器执行初始快照时使用的线程数量。要启用并行初始快照，请将 属性设置为大于 1 的值。在并行初始快照中，连接器同时处理多个表。
重要并行初始快照只是一个技术预览功能。红帽不支持开发人员预览软件，且功能完整或生产就绪。不要将开发人员预览软件用于生产环境或关键业务工作负载。开发人员预览软件提供早期对即将推出的产品软件的访问权限，以将其包括在红帽产品产品中。客户可以使用此软件来测试功能并在开发过程中提供反馈。此软件可能随时更改或删除，并且已获得有限的测试。红帽可能会提供在没有关联 SLA 的情况下对开发者预览软件提交反馈的方法。
有关 Red Hat Developer Preview 软件的支持范围的更多信息，请参阅 开发人员预览支持范围。
snapshot.mode默认值：
initial
指定在连接器启动时运行快照的条件。可用的设置如下：always- 连接器在每次启动时都执行快照。快照包括捕获的表的结构和数据。指定此值，每次连接器启动时，使用从捕获的表中数据的完整表示来填充主题。
Initial（默认）- 连接器仅在为逻辑服务器名称记录偏移时运行快照，或者如果它检测到早期快照无法完成。快照完成后，连接器将开始流传输后续数据库更改的事件记录。
initial_only- 只有在逻辑服务器名称没有记录偏移时，连接器才会运行快照。快照完成后，连接器会停止。它不会转换为从 binlog 读取更改事件。
schema_only-
弃用，请参阅
no_data。 no_data- 连接器运行只捕获 schema 的快照，但不运行任何表数据。如果您不需要主题包含数据的一致性快照，但您想要捕获最后一次连接器重启后应用的 schema 更改，则设置这个选项。
schema_only_recovery-
弃用，
请参阅恢复。 recovery设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。
警告如果在上次连接器关闭后将 schema 更改提交到数据库，则不要使用此模式执行快照。
never-
当连接器启动时，而不是执行快照时，它会立即开始为后续数据库更改流事件记录。这个选项考虑将来弃用，而是使用
no_data选项。 when_needed连接器启动后，只有在检测到以下情况之一时才执行快照：
- 它无法检测任何主题偏移。
- 之前记录的偏移量指定了服务器上不可用的 binlog 位置或 GTID。
snapshot.query.mode默认值：
select_all
指定在执行快照时连接器如何查询数据。
设置以下选项之一：select_all（默认）-
连接器使用
select allquery 从捕获的表中检索行，可以选择根据列包含和排除
与使用
snapshot.select.statement.overrides属性相比，此设置可让您以更灵活的方式管理快照内容。
snapshot.select.statement.overrides默认值： No default
指定要包含在快照中的表行。如果您希望快照只包括表中的行的子集，请使用该属性。此属性仅影响快照。它不适用于连接器从日志读取的事件。
属性包含以逗号分隔的完全限定表名称列表，格式为 <databaseName>.<tableName>。例如，
"snapshot.select.statement.overrides": "inventory.products,customers.orders"
对于列表中的每个表，添加一个进一步的配置属性，以指定在生成快照时在表上运行的
SELECT语句。指定的SELECT语句决定了快照中包含的表行子集。使用以下格式指定此SELECT语句属性的名称：
snapshot.select.statement.overrides. <databaseName > . <tableName> 例如：snapshot.select.statement.overrides.customers.orders
来自一个包括软删除栏的customers.orders表，delete_flag，如果您希望快照只包含不是软删除的记录，请添加以下属性："snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM [customers].[orders] WHERE delete_flag = 0 ORDER BY id DESC"
"snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM [customers].[orders] WHERE delete_flag = 0 ORDER BY id DESC"Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在生成的快照中，连接器只包含
delete_flag = 0的记录。
snapshot.tables.order.by.row.count默认值 ：
禁用
指定连接器在执行初始快照时处理表的顺序。设置以下选项之一：降序- 连接器快照表按顺序，基于最高到最低的行数。
ascending- 连接器快照表基于从最低到最高的行数。
disabled- 在执行初始快照时，连接器忽略了行数。
streaming.delay.ms-
默认值 ：
0
指定时间（以毫秒为单位），连接器会在完成快照后延迟流过程的启动。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的offset.flush.interval.ms属性的值。
table.ignore.builtin-
默认值：
true
一个布尔值，用于指定是否应忽略内置系统表。无论表 include 和 exclude 列表是什么，都适用。默认情况下，系统表中的值更改不包括在捕获中，Debezium 不会为系统表更改生成事件。
topic.cache.size-
默认值 ：
10000
指定可在绑定的并发散列映射中存储在内存中的主题名称数量。连接器使用缓存来帮助确定与数据收集对应的主题名称。
topic.delimiter-
默认值：
指定连接器在主题名称组件间插入的分隔符。
topic.heartbeat.prefix默认值 ：
_debezium-heartbeat
指定连接器向哪些主题发送 heartbeat 信息的名称。主题名称采用以下格式：
topic.heartbeat.prefix.topic.prefix
例如，如果主题前缀是
fulfillment，则默认主题名称为__debezium-heartbeat.fulfill。
topic.naming.strategy-
默认值：
io.debezium.schema.DefaultTopicNamingStrategy
连接器使用的TopicNamingStrategy类的名称。指定策略决定了连接器如何为数据更改、架构更改、事务、心跳等存储事件记录的主题。
topic.transaction默认值 ：
事务
指定连接器发送事务元数据信息的主题名称。主题名称采用以下模式：
topic.prefix.topic.transaction
例如，如果主题前缀是
fulfillment，则默认主题名称为fulfillment.transaction。
use.nongraceful.disconnect-
默认值：false
一个布尔值，用于指定二进制日志客户端的 keepalive 线程是否将SO_LINGER套接字选项设置为0以立即关闭过时的 TCP 连接。
如果连接器在SSLSocketImpl.close中遇到死锁，请将值设为true。
Debezium 连接器数据库架构历史记录配置属性
Debezium 提供了一组 schema.history.internal.* 属性，用于控制连接器如何与 schema 历史记录主题进行交互。
下表描述了用于配置 Debezium 连接器的 schema.history.internal 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器存储数据库 schema 历史记录的 Kafka 主题的完整名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机/端口对列表。此连接用于检索之前由连接器存储的数据库架构历史记录，以及写入从源数据库读取的每个 DDL 语句。每个对都应该指向 Kafka Connect 进程使用的相同 Kafka 集群。 | |
|
| 整数值，指定连接器在启动/恢复期间应等待的最大毫秒数，同时轮询持久数据。默认值为 100ms。 | |
|
| 指定连接器在使用 Kafka admin 客户端获取集群信息时应等待的最大毫秒数。 | |
|
| 指定连接器在使用 Kafka admin 客户端创建 kafka 历史记录主题时应等待的最大毫秒数。 | |
|
|
连接器在连接器恢复失败前尝试读取持久性历史记录数据的次数上限，并显示错误。没有数据后等待的最长时间是 | |
|
|
指定连接器是否应该忽略不正确的或未知数据库语句的布尔值，或停止处理，以便用户可以解决这个问题。安全默认为 | |
|
|
指定连接器是否记录模式或数据库中所有表的布尔值，或者仅从指定为捕获的表记录。
| |
|
|
指定连接器是否从数据库实例中的所有逻辑数据库记录模式结构的布尔值。
|
透传 MySQL 连接器配置属性
您可以在连接器配置中设置 pass-through 属性，以自定义 Apache Kafka producer 和 consumer 的行为。有关 Kafka 生成者和消费者的完整配置属性范围的详情，请参考 Kafka 文档。
直通属性，用于配置生成者和消费者客户端如何与 schema 历史记录主题交互
Debezium 依赖于 Apache Kafka producer 将 schema 更改写入数据库 schema 历史记录主题。同样，它依赖于 Kafka 使用者在连接器启动时从数据库 schema 历史记录主题中读取。您可以通过将值分配给一组以 schema.history.internal.producer和 schema.history.internal.consumerPromQL 前缀开头的 pass-through 配置属性来定义 Kafka producer 和 消费者 客户端的配置。pass-through producer 和 consumer 数据库模式历史记录属性控制一系列行为，如这些客户端如何与 Kafka 代理安全连接，如下例所示：
Debezium 在将属性传递给 Kafka 客户端前从属性名称中剥离前缀。
有关 Kafka producer 配置属性和 Kafka 使用者配置属性的更多信息，请参阅 Apache Kafka 文档。
直通属性，用于配置 MySQL 连接器如何与 Kafka 信号主题交互
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
为信号频道配置 Kafka 消费者客户端的属性
Debezium 连接器提供信号 Kafka 使用者的直通配置。透传信号属性以 signals.consumer.* 前缀开始。例如，连接器将 signal.consumer.security.protocol=SSL 等属性传递给 Kafka 使用者。
Debezium 在将属性传递给 Kafka 信号消费者前从属性中剥离前缀。
用于配置 MySQL 连接器接收器通知频道的直通属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
Debezium 连接器传递数据库驱动程序配置属性
Debezium 连接器提供数据库驱动程序的直通配置。透传数据库属性以前缀 driverPROFILE 开头。例如，连接器将 driver.foobar=false 等属性传递给 JDBC URL。
Debezium 在将属性传递给数据库驱动程序前从属性中剥离前缀。
2.4.7. 监控 Debezium MySQL 连接器性能
Debezium MySQL 连接器提供三种类型的指标，除了对 Zookeeper、Kafka 和 Kafka Connect 提供的 JMX 指标的支持外。
Debezium 监控文档 提供了如何使用 JMX 公开这些指标的详细信息。
2.4.7.1. MySQL 连接器快照和流 MBean 对象的自定义名称
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.31. 自定义标签如何修改连接器 MBean 名称
默认情况下，MySQL 连接器使用以下 MBean 名称进行流传输指标：
debezium.mysql:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.mysql:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.mysql:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.mysql:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.4.7.2. 在 MySQL 数据库快照过程中监控 Debezium
MBean 为 debezium.mysql:type=connector-metrics,context=snapshot,server= <topic.prefix>。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
连接器还会在执行增量快照时提供以下附加快照指标：
2.4.7.3. 监控 Debezium MySQL 连接器记录流
Debezium MySQL 连接器提供三种类型的指标，除了对 Zookeeper、Kafka 和 Kafka Connect 提供的 JMX 指标的支持外。
Debezium 监控文档 提供了如何使用 JMX 公开这些指标的详细信息。
MBean 为 debezium.mysql:type=connector-metrics,context=streaming,server= <topic.prefix>。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
2.4.7.4. 监控 Debezium MySQL 连接器模式历史记录
MBean 为 debezium.mysql:type=connector-metrics,context=schema-history,server= <topic.prefix>。
下表列出了可用的模式历史记录指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
|
| |
|
| 恢复开始的时间（以 epoch 秒为单位）。 | |
|
| 在恢复阶段读取的更改数量。 | |
|
| 恢复和运行时应用的模式更改总数。 | |
|
| 自上次更改从历史记录存储中恢复后经过的毫秒数。 | |
|
| 从上次更改被应用后经过的毫秒数。 | |
|
| 从历史记录存储中恢复最后一次更改的字符串表示。 | |
|
| 最后一次应用更改的字符串表示。 |
2.4.8. Debezium MySQL 连接器如何处理错误和问题
Debezium 是一个分布式系统，它捕获了多个上游数据库中的所有更改，永远不会丢失或丢失某个事件。当系统正常运行或被仔细管理时，Debezium 会在每次更改事件记录的发送 一次。
如果出现错误，系统不会丢失任何事件。但是，当 Debezium 从错误中恢复时，可能会重复一些更改事件。在这些常规情况下，Debezium （如 Kafka） 至少提供一次 更改事件。
详情包括在以下部分中：
- 配置和启动错误
在以下情况下，连接器会在尝试启动时失败，在日志中报告错误或异常，并停止运行：
- 连接器的配置无效。
- 连接器无法使用指定的连接参数成功连接到 MySQL 服务器。
- 连接器会尝试在 MySQL 不再有历史记录的 binlog 中重启。
在这些情况下，错误消息详细介绍了此问题，并可能是一个推荐的临时解决方案。在更正配置或解决 MySQL 问题后，重启连接器。
但是，如果您连接到高可用性 MySQL 集群，您可以立即重启连接器。它将连接到集群中的其他 MySQL 服务器，在服务器 binlog 中找到代表最后一个事务的位置，并开始从该特定位置读取新服务器的 binlog。
- Kafka Connect 正常停止
- 当 Kafka Connect 正常停止时，当 Debezium MySQL 连接器任务在新的 Kafka Connect 进程中停止并重启时会有一个短暂的延迟。
- Kafka Connect 进程崩溃
- 如果 Kafka Connect 崩溃，进程会停止，任何 Debezium MySQL 连接器任务会终止，而不会记录它们最近处理的偏移量。在分布式模式中，Kafka Connect 在其他进程中重启连接器任务。但是，MySQL 连接器会从之前进程记录的最后偏移量中恢复。因此，替换任务可能会重新生成在崩溃前处理的一些事件，从而创建重复的事件。
每个更改事件消息都包含可用于识别重复事件的源特定信息，例如：
- 事件源
- MySQL 服务器的事件时间
- binlog 文件名和位置
- GTIDs （如果使用）
- MySQL 清除 binlog 文件
- 如果 Debezium MySQL 连接器停止太长，MySQL 服务器会清除旧的 binlog 文件，连接器的最后位置可能会丢失。当连接器重启时，MySQL 服务器不再有起点，连接器会执行另一个初始快照。如果禁用了快照，连接器会失败并显示错误。
有关 MySQL 连接器如何执行初始 快照的详情，请查看快照。
2.5. 用于 Oracle 的 Debezium Connector
Debezium 的 Oracle 连接器捕获并记录 Oracle 服务器上的数据库中发生的行级更改，包括在连接器运行时添加的表。您可以将连接器配置为为特定模式和表的子集发出更改事件，或者在特定列中忽略、掩码或截断值。
有关与此连接器兼容的 Oracle 数据库版本的详情，请参考 Debezium 支持的配置 页面。
Debezium 使用原生 LogMiner 数据库软件包更改 Oracle 的事件。
使用 Debezium Oracle 连接器的信息和流程组织如下：
2.5.1. Debezium Oracle 连接器如何工作
要优化地配置和运行 Debezium Oracle 连接器，了解连接器如何执行快照、流更改事件、决定 Kafka 主题名称、使用元数据并实现事件缓冲会很有帮助。
如需更多信息，请参阅以下主题：
2.5.1.1. Debezium Oracle 连接器如何执行数据库快照
通常，Oracle 服务器上的红色日志配置为不保留数据库的完整历史记录。因此，Debezium Oracle 连接器无法从日志中检索数据库的完整历史记录。要让连接器为数据库的当前状态建立基线，连接器首次启动时，它会执行数据库的初始 一致快照。
如果完成初始快照所需的时间超过为数据库设置的 UNDO_RETENTION 时间（默认为十分钟），则可能会出现 ORA-01555 异常。有关错误的更多信息，以及您可以从该错误中恢复的步骤，请参阅 常见问题解答。
在表的快照期间，Oracle 可能会引发 ORA-01466 异常。当用户修改表的模式或添加、更改或丢弃与快照关联的索引或相关对象时，会出现这种情况。如果发生这种情况，连接器将停止，需要从开始获取初始快照。
要解决这个问题，您可以使用大于 0 的值配置 snapshot.database.errors.max.retries 属性，以便特定表的快照将重启。虽然整个快照不会在重试时从开始开始，但问题中的特定表将从开始重新读取，而表的主题将包含重复的快照事件。
您可以在以下部分中找到有关快照的更多信息：
2.5.1.1.1. Oracle 连接器用于执行初始快照的默认工作流
以下工作流列出了 Debezium 创建快照的步骤。这些步骤描述了当 snapshot.mode 配置属性设置为默认值时快照的进程，这是 初始。您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。如果您配置不同的快照模式，连接器使用此工作流的修改版本完成快照。
当快照模式设置为默认值时，连接器完成以下任务来创建快照：
- 建立与数据库的连接。
-
确定要捕获的表。默认情况下，连接器捕获所有表，除了那些与 捕获中排除的 schema 之外的表。快照完成后，连接器将继续流传输指定表的数据。如果您希望连接器只从特定表捕获数据，您可以通过设置
table.include.list或table.exclude.list等属性来仅捕获表或表元素的子集的数据。 -
在每个捕获的表上获取
ROW SHARE MODE锁定，以防止在创建快照期间发生结构更改。Debezium 只保存一个短时间锁定。 - 从服务器的 redo 日志中读取当前系统更改号(SCN)的位置。
捕获所有数据库表的结构或指定用于捕获的所有表。连接器在其内部数据库模式历史记录主题中保留 schema 信息。架构历史记录提供有关发生更改事件时所生效的结构的信息。
注意默认情况下，连接器捕获数据库中处于捕获模式的每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。有关您在初始快照中没有包括快照持久模式信息的更多信息，请参阅 了解为什么初始快照捕获所有表的 schema。
- 释放在第 3 步中获取的锁定。其他数据库客户端现在可以写入任何之前锁定的表。
在第 4 步中读取的 SCN 位置，连接器扫描为捕获指定的表(
SELECT * FROM … AS OF SCN 123)。在扫描过程中，连接器完成以下任务：- 确认表已在快照开始之前创建。如果在快照开始后创建了表，连接器会跳过该表。快照完成后，连接器过渡到 streaming，它会为快照开始后创建的任何表发出更改事件。
-
为从表中捕获的每行生成一个
读取事件。所有读取事件都包含相同的 SCN 位置，这是在第 4 步中获取的 SCN 位置。 -
向源表的 Kafka 主题发出每个
读取事件。 - 释放数据表锁定（如果适用）。
- 在连接器偏移中记录快照成功完成。
生成的初始快照会捕获捕获表中每行的当前状态。在这个基准状态中，连接器会捕获后续更改。
在快照过程开始后，如果进程因为连接器失败、重新平衡或其他原因而中断，进程会在连接器重启后重启。连接器完成初始快照后，它会从第 3 步中读取的位置继续流传输，以便它不会丢失任何更新。如果连接器因任何原因再次停止，它会在重启后恢复流更改，从之前离开的位置恢复流更改。
| 设置 | 描述 |
|---|---|
|
| 在每个连接器启动时执行快照。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照，如用于创建初始快照的默认工作流 中所述。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照并在流传输任何更改事件记录前停止，不允许捕获任何后续更改事件。 |
|
|
弃用，请参阅 |
|
|
连接器捕获所有相关表的结构，执行 默认快照工作流 中描述的所有步骤，但不创建 |
|
|
弃用， |
|
|
设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
如需更多信息，请参阅连接器配置属性表中的 snapshot.mode。
2.5.1.1.2. 有关初始快照捕获所有表的 schema 历史记录的描述
连接器运行的初始快照捕获两种类型的信息：
- 表数据
-
有关
INSERT、UPDATE和DELETE操作的信息，它们在连接器的table.include.list属性中命名。 - 模式数据
- 描述应用到表的结构更改的 DDL 语句。如果配置了 schema 数据，则 schema 数据会被保留到内部模式历史记录主题，以及连接器的 schema 更改主题。
运行初始快照后，您可能会注意到快照捕获了未指定用于捕获的表的模式信息。默认情况下，初始快照旨在捕获数据库中存在的每个表的模式信息，而不仅限于为捕获指定的表。连接器要求表的 schema 在捕获表之前存在于 schema 历史记录主题中。通过启用初始快照来捕获不属于原始捕获集的表，Debezium 准备连接器，以便稍后需要从这些表中读取事件数据。如果初始快照没有捕获表的模式，您必须将 schema 添加到历史记录主题，然后才能从表中捕获数据。
在某些情况下，您可能想要限制初始快照中的模式捕获。当您要减少完成快照所需的时间时，这非常有用。或者，当 Debezium 通过有权访问多个逻辑数据库的用户帐户连接到数据库实例时，但您希望连接器只从特定逻辑数据库中的表捕获更改。
其他信息
- 从初始快照未捕获的表中捕获数据（无模式更改）
- 从没有由初始快照捕获的表捕获数据(schema 更改)
-
设置
schema.history.internal.store.only.captured.tables.ddl属性，以指定要从中捕获模式信息的表。 -
设置
schema.history.internal.store.only.captured.databases.ddl属性，以指定捕获模式更改的逻辑数据库。
2.5.1.1.3. 从初始快照未捕获的表中捕获数据（无模式更改）
在某些情况下，您可能希望连接器从最初快照未捕获其 schema 的表中捕获数据。根据连接器配置，初始快照可能会只捕获数据库中特定表的表模式。如果历史记录主题中没有表模式，连接器无法捕获表，并报告缺少的 schema 错误。
您可能仍然能够从表中捕获数据，但您必须执行额外的步骤来添加表模式。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 事务日志中表的所有条目都使用相同的模式。有关从具有结构化更改的新表捕获数据的详情，请参考 第 2.5.1.1.4 节 “从没有由初始快照捕获的表捕获数据(schema 更改)”。
流程
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 在连接器配置中：
-
将
snapshot.mode设置为schema_only_recovery。 -
（可选）将
schema.history.internal.store.only.captured.tables.ddl的值设置为false，以确保在以后没有为捕获的表捕获数据。只有在历史记录主题中存在表的 schema 历史记录时，连接器才能从表中捕获数据。 -
添加您希望连接器捕获到
table.include.list的表。
-
将
- 重启连接器。快照恢复过程会根据表的当前结构重建模式历史记录。
- （可选）快照完成后，在新添加的表中启动 增量快照。增量快照首先会流传输新添加的表的历史数据，然后恢复从之前配置的表读取更改和存档日志，包括该连接器在连接器离线时发生的更改。
-
（可选）将
snapshot.mode重置为schema_only，以防止连接器在以后的重启后启动恢复。
2.5.1.1.4. 从没有由初始快照捕获的表捕获数据(schema 更改)
如果将架构更改应用到表，则在架构更改前提交的记录与更改后提交的结构不同。当 Debezium 捕获表中的数据时，它会读取 schema 历史记录，以确保它将正确的模式应用到每个事件。如果 schema 历史记录主题中没有 schema，连接器将无法捕获表，并会产生错误结果。
如果要捕获初始快照未捕获的表中的数据，并修改了表的 schema，您必须将 schema 添加到历史记录主题（如果还没有可用）。您可以通过运行新的模式快照或运行表的初始快照来添加架构。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 对表应用了一个架构更改，因此要捕获的记录没有统一的结构。
流程
- 初始快照捕获了所有表的模式(
storage.only.captured.tables.ddl设置为false) -
编辑
table.include.list属性，以指定您要捕获的表。 - 重启连接器。
- 如果要从新添加的表中捕获现有数据，则启动 增量快照。
-
编辑
- 初始快照没有捕获所有表的模式(storage
.only.captured.tables.ddl设置为true) 如果初始快照没有保存您要捕获的表的模式，请完成以下步骤之一：
- 流程 1：Schema 快照，后跟增量快照
在此过程中，连接器首先执行 schema 快照。然后，您可以启动增量快照，使连接器能够同步数据。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为schema_only。 -
编辑
table.include.list以添加您要捕获的表。
-
将
- 重启连接器。
- 等待 Debezium 捕获新表和现有表的模式。连接器停止后发生的数据更改不会被捕获。
- 为确保没有数据丢失，可启动 增量快照。
- 流程 2：初始快照，后跟可选的增量快照
在此过程中，连接器执行数据库的完整初始快照。与任何初始快照一样，在具有许多大表的数据库中，运行初始快照可能是一个耗时的操作。快照完成后，您可以选择性地触发增量快照，以捕获连接器离线期间发生的任何更改。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
-
编辑
table.include.list以添加您要捕获的表。 为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为initial。 -
（可选）将
schema.history.internal.store.only.captured.tables.ddl设置为false。
-
将
- 重启连接器。连接器使用完整的数据库快照。快照完成后，连接器会过渡到 streaming。
- （可选）要捕获连接器脱机时更改的任何数据，请启动 增量快照。
2.5.1.2. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供总结表数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改为捕获不同的表集合。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号表。您可以通过向 Debezium 信号表发送信号请求来启动临时快照。
当您启动现有表的临时快照时，连接器会将内容附加到表已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的表。快照可以捕获数据库的全部内容，或者仅捕获数据库中表的子集。此外，快照也可捕获数据库中表的内容的子集。
您可以通过向信号表发送 execute-snapshot 消息来指定要捕获的表。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的表名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| N/A |
包含与快照中包含的表的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作表的主键的列名称。 |
触发临时增量快照
您可以通过向信号表添加带有 execute-snapshot 信号类型的条目，或者向 Kafka 信号发送信号消息 来启动临时增量快照。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个表的开始和端点。根据表中的条目数量以及配置的块大小，Debezium 会将表分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号表或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.5.1.3. 增量快照
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个表。您可以指定您希望快照捕获的表 以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debezium 使用水位线来跟踪其进度，维护其捕获的每个表行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获表。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，以将表添加到其
table.include.list属性中。
增量快照过程
当您运行增量快照时，Debezium 按主密钥对每个表进行排序，然后根据 配置的块大小 将表分成块。通过块工作的块，然后捕获块中的每个表行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改表记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获了包含该行的 READ 事件前修改表行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一表行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定表块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到表的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
Oracle 的 Debezium 连接器不支持增量快照运行时的 schema 更改。
2.5.1.3.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号表。您可以提交快照信号，作为 SQL INSERT 查询。
在 Debezium 检测到信号表中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的表，并可选择性地指定快照操作的类型。Debezium 目前支持 增量 和 阻塞 快照类型。
要指定要包含在快照中的表，提供一个列出表的 data-collections 数组，或用于匹配表的正则表达式数组，例如：
{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会解释空数组，意味着不需要任何操作，且不会执行快照。
如果要包含在快照中的表的名称包含一个点(.)、空格或其它非字母数字字符，则必须使用双引号转义表名称。
例如，若要将 公共 模式中存在的表包含在 db1 数据库中，并且名称为 My.Table，请使用以下格式 ："db1.public.\"My.Table\" "。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
发送 SQL 查询，将临时增量快照请求添加到信号表中：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、type和data参数的值 与信号表的字段 相对应。
下表描述了示例中的参数：Expand 表 2.107. SQL 命令中的字段描述，用于将增量快照信号发送到信号表 项 值 描述 1
database.schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshottype参数指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定表名称或正则表达式数组，以匹配快照中包含的表名称。
数组列出了使用格式database.schema.table的正则表达式，以匹配表的完全限定域名。此格式与您用来指定连接器 信号表的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
有效值为incremental和blocking值。
如果没有指定值，连接器默认为执行增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
每个额外条件都是带有data-collection和filter属性的对象。您可以为每个数据收集指定不同的过滤器。
请参阅data-collection属性是过滤器应用到的数据收集的完全限定域名。有关additional-conditions参数的详情，请参考 第 2.5.1.3.2 节 “使用附加条件运行临时增量快照”。
2.5.1.3.2. 使用附加 条件运行临时增量快照
如果您希望快照只在表中包括内容子集，您可以通过将 additional-conditions 参数附加到快照信号来修改信号请求。
对典型快照的 SQL 查询采用以下格式：
SELECT * FROM <tableName> ....
SELECT * FROM <tableName> ....
通过添加 additional-conditions 参数，您可以在 SQL 查询中附加 WHERE 条件，如下例所示：
SELECT * FROM <data-collection> WHERE <filter> ....
SELECT * FROM <data-collection> WHERE <filter> ....以下示例显示了向信号表发送带有额外条件的临时增量快照请求的 SQL 查询：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
例如，假设您有一个包含以下列的 products 表：
-
ID（主密钥） -
color -
quantity
如果您需要 product 表的增量快照，其中只包含 color=blue 的数据项，您可以使用以下 SQL 语句来触发快照：
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue"}]}');
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue"}]}');
additional-conditions 参数还允许您传递基于多个列的条件。例如，使用上例中的 product 表，您可以提交查询来触发增量快照，该快照仅包含 color=blue 和 quantity>10 的项数据：
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue AND quantity>10"}]}');
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue AND quantity>10"}]}');以下示例显示了连接器捕获的增量快照事件的 JSON。
例 2.32. 增量快照事件消息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.5.1.3.3. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.33. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择表内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果一个带有列 ID （主键）、颜色 和品牌 的 products 表，如果您希望快照只包含 color='blue' 的内容，当请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 product 表，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的 表中的内容，您可以发送以下请求：
products
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.5.1.3.4. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的信号发送信号来停止已经运行的快照。
您可以通过在 SQL INSERT 查询中发送停止快照信号，向信号表提交停止快照信号。stop-snapshot 信号将快照操作的类型指定为 增量，并选择性地指定要从当前运行的快照中省略的表。在 Debezium 检测到信号表中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
发送 SQL 查询以停止临时增量快照到信号表：
INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
INSERT INTO db1.myschema.debezium_signal (id, type, data) values ('ad-hoc-1', 'stop-snapshot', '{"data-collections": ["db1.schema1.table1", "db1.schema1.table2"], "type":"incremental"}');INSERT INTO db1.myschema.debezium_signal (id, type, data)1 values ('ad-hoc-1',2 'stop-snapshot',3 '{"data-collections": ["db1.schema1.table1", "db1.schema1.table2"],4 "type":"incremental"}');5 Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号表的字段相对应。
下表描述了示例中的参数：Expand 表 2.110. SQL 命令中的字段描述，用于将停止增量快照信号发送到信号表 项 值 描述 1
database.schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。3
stop-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定表名称或正则表达式数组，以匹配要从快照中删除的表名称。
数组列出了正则表达式，该表达式通过其完全限定名称匹配表，格式为database.schema.table如果您从
data字段省略这个组件，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.5.1.3.5. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，表名称或正则表达式，以匹配要从快照中删除的表名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.schema1.table1", "db1.schema1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.schema1.table1", "db1.schema1.table2"], "type": "INCREMENTAL"}}`2.5.1.4. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新表，并在连接器运行时完成快照。
- 您可以添加大表，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个表必须是快照
additional-conditions ：您可以为不同的表指定不同的过滤器。
-
data-collection属性是要应用过滤器的表的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.5.1.5. 接收 Debezium Oracle 更改事件记录的 Kafka 主题的默认名称
默认情况下，Oracle 连接器将所有 INSERT、UPDATE 和 DELETE 操作的更改事件写入一个特定于该表的单个 Apache Kafka 主题。连接器使用以下惯例命名更改事件主题：
topicPrefix.schemaName.tableName
以下列表提供了默认名称组件的定义：
- topicPrefix
-
由
topic.prefix连接器配置属性指定的主题前缀。 - schemaName
- 发生操作的模式的名称。
- tableName
- 操作发生的表的名称。
例如，如果 fulfillment 是服务器名称，inventory 是 schema 名称，数据库包括名为 orders, customers, 和 products 的表，Debezium Oracle 连接器会向以下 Kafka 主题发送事件，数据库中的每个表有一个。
fulfillment.inventory.orders fulfillment.inventory.customers fulfillment.inventory.products
fulfillment.inventory.orders
fulfillment.inventory.customers
fulfillment.inventory.products连接器应用类似的命名约定来标记其内部数据库架构历史记录主题、架构更改主题 和事务元数据主题。
如果默认主题名称不满足您的要求，您可以配置自定义主题名称。要配置自定义主题名称，您可以在逻辑主题路由 SMT 中指定正则表达式。有关使用逻辑主题路由 SMT 自定义主题命名的更多信息，请参阅 主题路由。
2.5.1.6. Debezium Oracle 连接器如何处理数据库架构更改
当数据库客户端查询数据库时，客户端将使用数据库的当前架构。但是，可以随时更改数据库架构，这意味着连接器必须能够识别每次插入、更新或删除操作时的 schema。另外，连接器不一定将当前模式应用到每个事件。如果事件相对旧，则在应用当前模式之前记录这些事件。
为确保在架构更改后处理发生的正确事件，Oracle 包含在 redo 日志中包括影响数据的行级更改，以及应用到数据库的 DDL 语句。当连接器在 redo 日志中遇到这些 DDL 语句时，它会解析它们并更新每个表的 schema 的内存中表示。连接器使用此架构表示在每次插入、更新或删除操作时标识表的结构，并生成适当的更改事件。在单独的数据库架构历史记录 Kafka 主题中，连接器记录了所有 DDL 语句，以及出现每个 DDL 语句的红色日志中的位置。
当连接器在崩溃或安全停止后重启时，它开始从特定位置读取红色日志，即从特定时间点读取红色日志。连接器通过读取数据库模式历史记录 Kafka 主题来重建在此时存在的表结构，并在连接器启动的红色日志中解析所有 DDL 语句。
此数据库架构历史记录主题仅供内部使用。另外，连接器也可以将 schema 更改事件发送到面向消费者应用程序的不同主题。
其他资源
- 接收 Debezium 事件记录 的主题的默认名称。
2.5.1.7. Debezium Oracle 连接器如何公开数据库 schema 的变化
您可以配置 Debezium Oracle 连接器来生成模式更改事件，这些事件描述了应用到数据库中表的结构更改。连接器将模式更改事件写入名为 < serverName> 的 Kafka 主题，其中 serverName 是 topic.prefix 配置属性中指定的命名空间。
当 Debezium 从新表流传输数据时，或更改表的结构时，Debebe 会向 schema 更改主题发送一条新消息。
连接器发送到 schema 更改主题的消息包含一个有效负载，并可以选择包含更改事件消息的 schema。
模式更改事件的 schema 具有以下元素：
名称- 模式更改事件消息的名称。
type- 更改事件消息的类型。
version- 架构的版本。version 是一个整数，每次更改 schema 时都会递增。
fields- 更改事件消息中包含的字段。
示例：Oracle 连接器模式更改主题的 Schema
以下示例显示了 JSON 格式的典型模式。
模式更改事件消息的有效负载包括以下元素：
ddl-
提供导致 schema 的 SQL
CREATE、ALTER或DROP语句。 databaseName-
将语句应用到的数据库的名称。
databaseName的值充当 message 键。 tableChanges-
架构更改后整个表模式的结构化表示。
tableChanges字段包含一个数组，其中包含表的每列条目。由于结构化表示以 JSON 或 Avro 格式显示数据，因此用户可以轻松地读取消息，而无需首先通过 DDL 解析器处理它们。
默认情况下，连接器使用 ALL_TABLES 数据库视图来识别要存储在 schema 历史记录主题中的表名称。在该视图中，连接器只能从可连接到数据库的用户帐户的表中访问数据。
您可以修改设置，以便 schema 历史记录主题存储了不同的表子集。使用以下方法之一更改主题存储的表集合：
-
更改 Debezium 用于访问数据库的帐户的权限，以便在
ALL_TABLES视图中看到不同的表集合。 -
将连接器属性
schema.history.internal.store.only.captured.tables.ddl设置为true。
当连接器被配置为捕获表时，它会存储表的模式更改历史记录，不仅存储在 schema 更改主题中，还存储在内部数据库架构历史记录主题中。内部数据库架构历史记录主题仅用于连接器，它不用于直接使用应用程序。确保需要针对 schema 更改通知的应用程序只消耗了来自 schema 更改主题的信息。
永不对数据库 schema 历史记录主题进行分区。要使数据库架构历史记录主题正常工作，它必须保持一致的全局顺序，连接器向其发送的事件记录。
要确保主题不在分区中分割，请使用以下方法之一为主题设置分区计数：
-
如果您手动创建数据库架构历史记录主题，请指定分区计数
1。 -
如果您使用 Apache Kafka 代理自动创建数据库模式历史记录主题，则会创建主题，将 Kafka
num.partitions配置选项 的值设置为1。
示例：向 Oracle 连接器 schema 更改主题发送的消息
以下示例显示了 JSON 格式的典型的模式更改消息。消息包含表 schema 的逻辑表示。
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 在源对象中，ts_ms 表示更改在数据库中的时间。通过将 payload.source.ts_ms 的值与 payload.ts_ms 的值进行比较，您可以确定源数据库更新和 Debezium 之间的滞后。 |
| 2 |
| 标识包含更改的数据库和模式。 |
| 3 |
| 此字段包含负责 schema 更改的 DDL。 |
| 4 |
| 包含 DDL 命令生成的架构更改的一个或多个项目的数组。 |
| 5 |
|
描述更改类型。
|
| 6 |
|
创建、更改或丢弃的表的完整标识符。对于表重命名，此标识符是 < |
| 7 |
| 代表应用的更改后的表元数据。 |
| 8 |
| 编写表主键的列列表。 |
| 9 |
| changed 表中每个列的元数据。 |
| 10 |
| 每个表更改的自定义属性元数据。 |
在连接器发送到 schema 更改主题的消息中，message 键是包含 schema 更改的数据库的名称。在以下示例中，payload 字段包含 databaseName 键：
2.5.1.8. Debezium Oracle 连接器生成的事件代表事务边界
Debezium 可以生成代表事务元数据边界的事件，以及丰富的数据更改事件消息。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
数据库事务由一个声明块表示，该块包含在 BEGIN 和 END 关键字之间。Debezium 为每个事务中的 BEGIN 和 END 分隔符生成事务边界事件。事务边界事件包含以下字段：
status-
BEGIN或END. id- 唯一事务标识符的字符串表示。
ts_ms-
数据源的事务边界事件(
BEGIN或END事件)的时间。如果数据源没有向 Debezium 提供事件时间，则字段代表 Debezium 处理事件的时间。 event_count（用于END事件）- 事务处理的事件总数。
data_collections（用于END事件）-
一组
data_collection和event_count元素，用于指示连接器为来自数据收集的更改发出的事件数。
以下示例显示了典型的事务边界消息：
示例：Oracle 连接器事务边界事件
除非通过 topic.transaction 选项覆盖，否则连接器会将事务事件发送到 < topic.prefix>.transaction 主题。
2.5.1.8.1. Debezium Oracle 连接器如何使用事务元数据增强更改事件信息
如果启用了事务元数据，数据消息 Envelope 会增加一个新的 transaction 字段。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示。
total_order- 事件在事务生成的所有事件间的绝对位置。
data_collection_order- 事件在事务发送的所有事件中的每个数据收集位置。
以下示例显示了典型的事务事件信息：
LogMiner Mining 策略
Oracle redo 日志中的条目不会存储用户提交的原始 SQL 语句，以便进行 DML 更改。相反，红色条目包含一组更改向量，以及代表与这些向量相关的表、表和列的对象标识符。换句话说，红色日志条目不包括由 DML 更改影响的模式、表或列的名称。
Debezium Oracle 连接器使用 log.mining.strategy 配置属性来控制 Oracle LogMiner 如何处理更改向量中对象标识符的查找。在某些情况下，一个日志 mining 策略可能会比架构更改更可靠。但是，在选择日志 mining 策略前，务必要考虑其在性能和开销方面可能具有的影响。
编写数据字典以恢复日志
默认 mining 策略名为 redo_log_catalog。在此策略中，数据库会在每个红色日志切换后立即将数据字典的副本刷新到 redo 日志。这是跟踪与数据更改交互的模式更改的最可靠策略，因为 Oracle LogMiner 在一系列更改向量的开始和结束数据字典状态之间进行干预。
但是，redo_log_catalog 模式也是最昂贵，因为它需要几个关键步骤才能正常工作。首先，此模式需要在每次日志切换后将数据字典刷新到红色日志。在每个交换机后清除日志可以快速消耗存档日志中重要的空间，而归档日志的高卷可能会超过数据库管理员为准备的数量。如果要使用此模式，请与您的数据库管理员协调以确保正确配置了数据库。
如果您将连接器配置为使用 redo_log_catalog 模式，请不要使用多个 Debezium Oracle 连接器来捕获来自同一逻辑数据库的更改。
直接使用在线目录
下一个策略模式 online_catalog 的工作方式与 redo_log_catalog 模式不同。当策略设置为 online_catalog 时，数据库永远不会将数据字典刷新到红色日志。相反，Oracle LogMiner 始终使用最新的数据字典状态来执行比较。通过始终使用当前的字典，并消除对红色日志的清空，此策略需要较少的开销，并更有效地运行。但是，这些好处是无法解析内部模式更改和数据更改的偏移量。因此，这个策略有时可能会导致事件失败。
如果 LogMiner 在模式更改后无法重建 SQL 可靠性，请检查红色日志以了解证据。查找名称为 OBJ# 123456 （其中数字是表的对象标识符）或带有名称（如 COL1 或 COL2） 的表的引用。当您将连接器配置为使用 online_catalog 策略时，采取措施来确保表 schema 及其索引保持静态状态，并避免更改。如果 Debezium 连接器配置为使用 online_catalog 模式，且您必须应用 schema 更改，请执行以下步骤：
- 等待连接器捕获所有现有的数据更改(DML)。
- 执行架构(DDL)更改，然后等待连接器捕获更改。
- 在表上恢复数据更改(DML)。
按照以下步骤，确保 Oracle LogMiner 可以安全地重建 SQL 以了解所有数据更改。
查询模式
Debezium Oracle 连接器默认与 Oracle LogMiner 集成。此集成需要一组专门的步骤，其中包括生成复杂的 JDBC SQL 查询，以便尽可能在事务日志中记录的更改作为更改事件。JDBC SQL 查询使用的 V$LOGMNR_CONTENTS 视图没有任何索引来改进查询的性能，因此可以使用不同的查询模式来控制如何以改进查询的方式生成 SQL 查询。
log.mining.query.filter.mode 连接器属性可以配置以下内容之一，以便影响生成 JDBC SQL 查询的方式：
none-
（默认）此模式会创建一个 JDBC 查询，它根据不同的操作类型（如插入、更新或删除）在数据库级别上过滤。当根据 schema, table, 或 username include/exclude 列表过滤数据时，这是在连接器中的处理循环过程中完成的。
当从数据库中捕获没有大量更改的表时，这个模式通常很有用。生成的查询非常简单，主要侧重于通过低数据库开销尽快读取。 in-
这个模式会创建一个 JDBC 查询，它不仅过滤在数据库级别上的操作类型，还过滤模式、表和用户名包含/排除列表。查询的 predicates 使用 SQL in-clause 生成，具体取决于 include/exclude 列表配置属性中指定的值。
当从数据库捕获大量表时，这个模式通常很有用，而这些表在更改时非常饱和。生成的查询比none模式复杂，并侧重于减少网络开销，并尽可能在数据库级别执行尽可能多的过滤。
最后，不要将 正则表达式指定为 schema 和 table include/exclude 配置属性的一部分。使用正则表达式将导致连接器与基于这些配置属性的更改不匹配，从而导致更改丢失。 regex-
这个模式会创建一个 JDBC 查询，它不仅过滤在数据库级别上的操作类型，还过滤模式、表和用户名包含/排除列表。但是，与
in模式不同，此模式会根据是否指定了 include 或 exclude 的值，使用 OracleREGEXP_LIKE操作器生成 SQL 查询。
当捕获使用少量正则表达式的表号时，此模式通常很有用。生成的查询比任何其他模式复杂得多，并侧重于减少网络开销，并尽可能在数据库级别执行尽可能多的过滤。
2.5.1.9. Debezium Oracle 连接器如何使用事件缓冲
Oracle 将所有更改按其发生的顺序写入红色日志，包括稍后由回滚丢弃的更改。因此，来自独立事务的并发更改会被干扰。当连接器首先读取更改流时，因为它无法立即确定提交或回滚哪些更改，它会临时将更改事件存储在内部缓冲区中。提交更改后，连接器会将更改事件从缓冲区写入 Kafka。连接器丢弃了回滚丢弃的更改事件。
您可以通过设置属性 log.mining.buffer.type 来配置连接器使用的缓冲机制。
heap
默认缓冲区类型使用 memory 进行配置。在默认 内存设置 下，连接器使用 JVM 进程的堆内存来分配和管理缓冲的事件记录。如果您使用 内存 缓冲区设置，请确定分配给 Java 进程的内存量可以适合您的环境中的长时间运行和大型事务。
2.5.1.10. Debezium Oracle 连接器如何检测 SCN 值中的差距
当 Debezium Oracle 连接器配置为使用 LogMiner 时，它会使用一个基于系统更改号(SCN)的开始和结束范围从 Oracle 收集更改事件。连接器会自动管理此范围，根据连接器是否可以实时流更改，或者由于数据库中的大量或批量事务的卷而处理更改的积压。
在某些情况下，Oracle 数据库会使 SCN 变得非常高，而不是以恒定的速度增加 SCN 值。这种 SCN 值的 jump 可能会发生，因为特定集成与数据库交互，或者作为热备份等事件。
Debezium Oracle 连接器依赖于以下配置属性来检测 SCN 差距并调整 mining 范围。
log.mining.scn.gap.detection.gap.size.min- 指定最小差距大小。
log.mining.scn.gap.detection.time.interval.max.ms- 指定最大时间间隔。
连接器首先比较当前 SCN 和当前 mining 范围内的 SCN 之间的变化数量。如果当前 SCN 值和最高 SCN 值之间的区别大于最小差距，则连接器可能会检测到 SCN 差距。要确认是否存在差距，下一个连接器会比较当前 SCN 和前一个 mining 范围末尾的 SCN 的时间戳。如果时间戳之间的区别小于最大时间间隔，则会确认是否存在 SCN 差距。
当 SCN 差距发生时，Debezium 连接器会自动将当前的 SCN 用作当前 mining 会话范围的端点。这可让连接器快速捕获实时事件，而无需在返回任何更改之间减少较小的范围，因为 SCN 值被意外数量增加。当连接器执行上述响应 SCN 差距的步骤时，它会忽略 log.mining.batch.size.max 属性指定的值。连接器完成 mining 会话并捕获到实时事件后，它会恢复最大日志的强制批处理大小。
只有在连接器运行和处理接近实时事件时，SCN 差距检测才可用。
2.5.1.11. Debezium 如何管理数据库中不经常更改的偏移量
Debezium Oracle 连接器跟踪连接器偏移中的系统更改号，以便在连接器重启时，它可以从其离开的位置开始。这些偏移是每个发出的更改事件的一部分；但是，当数据库频率较低（每数小时或天）时，偏移可能会变得过时，并防止连接器在事务日志中不再提供，防止连接器成功重启。
对于使用非CDB 模式连接到 Oracle 的连接器，您可以启用 heartbeat.interval.ms 来强制连接器定期发出 heartbeat 事件，以便偏移保持同步。
对于使用 CDB 模式连接到 Oracle 的连接器，维护同步更为复杂。不仅必须设置 heartbeat.interval.ms，还需要设置 heartbeat.action.query。需要指定这两个属性，因为在 CDB 模式中，连接器专门用于跟踪 PDB 中的更改。需要在可插拔数据库中触发更改事件所需的补充机制。定期，心跳操作查询会导致连接器插入新表行，或更新可插拔数据库中的现有行。Debezium 检测到表更改并为它们发出更改事件，确保偏移保持同步，即使在进程不经常更改的可插拔数据库中也是如此。
要使连接器使用 heartbeat.action.query 以及不是 连接器用户帐户 的表，您必须授予连接器用户权限才能在这些表上运行必要的 INSERT 或 UPDATE 查询。
2.5.2. Debezium Oracle 连接器数据更改事件的描述
Oracle 连接器发出的每个数据更改事件都有一个键和值。键和值的结构取决于更改事件源自的表。有关 Debezium 构造主题名称的详情，请参考 主题名称。
Debezium Oracle 连接器确保所有 Kafka Connect 模式名称都 是有效的 Avro 模式名称。这意味着，逻辑服务器名称必须以字母字符或下划线([a-z,A-Z,_])开头，而逻辑服务器名称和模式名称和表名称中的所有字符必须是字母数字字符或下划线([a-z,A-Z,0-9,\_])。连接器会自动将无效的字符替换为下划线字符。
当多个逻辑服务器名称、模式名称或表名称不是有效的字符，且这些字符被替换为下划线时，意外命名冲突可能会导致。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，主题消费者可能很难处理。为便于处理可变事件结构，Kafka Connect 中的每个事件都是自包含的。每个消息键和值有两个部分：schema 和 payload。模式描述了有效负载的结构，而有效负载包含实际数据。
连接器不会捕获由 SYS 或 SYSTEM 用户帐户执行的更改。
以下主题包含有关数据更改事件的更多详细信息：
2.5.2.1. 关于 Debezium Oracle 连接器更改事件中的键
对于每个更改的表，更改事件键的结构，以便在创建事件时，表的主键（或唯一键约束）中存在每个列的字段。
例如，在 inventory 数据库 schema 中定义的 customers 表可能有以下更改事件键：
如果 < topic.prefix>.transaction 配置属性的值被设置为 server1，则数据库中 customers 表中发生的每个更改事件的 JSON 表示具有以下关键结构：
密钥的 schema 部分包含一个 Kafka Connect 模式，用于描述密钥部分的内容。在前面的示例中，有效负载 值不是可选的，结构由名为 server1.DEBEZIUM.CUSTOMERS.Key 的 schema 定义，它有一个类型为 int32 的必需字段 id。键的 payload 字段的值表示它实际上是一个带有 id 字段的结构（在 JSON 中，是一个对象），其值为 1004。
因此，您可以将这个键解释为 inventory.customers 表中的行（来自名为 server1 的连接器），其 id 主键列的值为 1004。
2.5.2.2. 关于 Debezium Oracle 连接器更改事件中的值
更改事件消息中的值结构反映了消息中 change 事件中消息键 的结构，并且包含 schema 部分和 payload 部分。
更改事件值的有效负载
更改事件值的有效数据部分中有一个 envelope 数据结构，它包含以下字段：
op-
包含描述操作类型的字符串值的必填字段。Oracle 连接器更改事件值有效负载中的
op字段包含以下值之一：c（创建或插入）、u(update)、d（删除）或r（读取，表示快照）。 before-
存在的可选字段（如果存在）描述了事件 发生前 行的状态。该结构由
server1.INVENTORY.CUSTOMERS.ValueKafka Connect 模式描述，server1连接器用于inventory.customers表中的所有行。
after-
存在的可选字段（如果存在）包含 更改后 行的状态。该结构由用于
before字段的同一server1.INVENTORY.CUSTOMERS.ValueKafka Connect schema 描述。 source包含描述事件源元数据的结构的必填字段。对于 Oracle 连接器，结构包括以下字段：
- Debezium 版本。
- 连接器名称。
- 事件是否是持续快照的一部分。
- 事务 ID （不包含快照）。
- 改变的 SCN。
- 指示源数据库中记录何时更改的时间戳（对于快照，时间戳表示何时发生快照）。
- 进行更改的用户名
与行关联的 ROWID
提示commit_scn字段是可选的，描述了更改事件参与的事务提交的 SCN。
ts_ms- 可选字段，如果存在，包含运行 Kafka Connect 任务的 JVM 中的时间（基于系统时钟），该字段处理事件。
更改事件值的 schema
事件消息值的 schema 部分包含一个 schema，它描述了有效负载的 envelope 结构及其中的嵌套字段。
有关更改事件值的更多信息，请参阅以下主题：
创建 事件
以下示例显示了 customers 表中 create 事件值的值，如 更改事件键 示例所述：
在前面的示例中，注意事件如何定义以下模式：
-
信封 (
server1.DEBEZIUM.CUSTOMERS.Envelope)。 -
源结构(io.debezium.connector.oracle.Source，它特定于 Oracle 连接器并在所有事件间重复使用)。 -
before和after字段的特定于表的模式。
before 和 after 字段的 schema 的名称的格式为 <logicalName>.<schemaName>.<tableName>.Value, 因此完全独立与所有其他表的 schema。因此，当您使用 Avro converter 时，每个逻辑源中的表的 Avro 模式都有自己的演变和历史记录。
此事件的 value 的 payload 部分提供有关事件的信息。它描述了创建了行(op=c)，并显示 after 字段值包含插入到 ID、FIRST_NAME、LAST_NAME 和 EMAIL 列中的值。
默认情况下，事件的 JSON 表示大于描述的行。较大的大小是因为 JSON 表示，包括消息的 schema 和 payload 部分。您可以使用 Avro Converter 减少连接器写入 Kafka 主题的消息大小。
更新 事件
以下示例显示了一个 update 更改事件，连接器从与以前的 create 事件相同的表中捕获。
有效负载的结构与 create (insert)事件有效负载相同，但以下值有所不同：
-
op字段的值为u，表示此行因为更新而改变。 -
before字段显示行的前一状态，以及更新数据库提交前存在的值。 -
after字段显示行的更新状态，EMAIL值现在设置为anne@example.com。 -
source字段的结构包含与之前相同的字段，但值不同，因为连接器从红色日志的不同位置捕获事件。 -
ts_ms字段显示显示 Debezium 处理事件的时间戳。
payload 部分显示一些其他有用的信息。例如，通过比较结构的 before 和 after 结构，我们可以确定在提交后如何更改行。源 结构提供有关 Oracle 记录的信息，提供可追溯性。它还让我们了解此事件何时发生此主题中的其他事件和其他主题。它是否发生在与另一个事件相同的提交之前、之后还是作为其他事件的一部分？
当更新行 primary/unique 键的列时，行的键值会改变。因此，Debebe 在更新后发出三个 事件：
-
DELETE事件。 - 一个 tombstone 事件，带有行的旧键。
-
为行提供新密钥的
INSERT事件。
删除 事件
以下示例显示了上一次 create 和 update 事件示例中显示的表的 delete 事件。delete 事件的 schema 部分与这些事件的 schema 部分相同。
与 create 或 update 事件相比，事件的 payload 部分显示了几个不同之处：
-
op字段的值为d，表示行已被删除。 -
before字段显示与数据库提交删除的行前状态。 -
after字段的值为null，表示行不再存在。 -
source字段的结构中包括了多个在 create 或 update 事件中存在的键， 但ts_ms,scn, 和txId中的值不同。 -
ts_ms显示一个时间戳，指示 Debezium 处理此事件的时间。
delete 事件为用户提供了处理删除此行所需的信息。
Oracle 连接器的事件设计为与 Kafka 日志压缩 一起使用，这允许删除一些旧的信息，只要保留每个密钥的最新消息。这允许 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
删除行时，上例中显示的 delete 事件值仍可用于日志压缩，因为 Kafka 能够删除使用同一键的所有之前信息。message 值必须设置为 null，以指示 Kafka 删除共享同一键的所有消息。为了实现此目的，默认情况下 Debezium 的 Oracle 连接器总是遵循一个 delete 事件，它有一个特殊的 tombstone 事件，它具有相同的键但 null 值。您可以通过设置连接器属性 tombstones.on.delete 来改变默认的行为。
截断 事件
truncate 更改事件信号，提示表已被截断。message 键在本例中是 null，消息值类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述事件源元数据的强制字段。在 truncate 事件值中，
|
| 2 |
|
描述操作类型的强制字符串。 |
| 3 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。
|
由于 truncate 事件代表对整个表所做的更改，且没有消息键，对于具有多个分区的主题，因此不能保证消费者收到 截断 事件和更改事件(创建、更新 等等)。例如，当消费者从不同分区读取事件时，可能会在收到同一表的 truncate 事件后收到表 的更新 事件。只有在主题使用单个分区时，才能保证排序。
如果您不想捕获 截断 事件，请使用 skipped.operations 选项来过滤它们。
2.5.3. Debezium Oracle 连接器如何映射数据类型
当 Debezium Oracle 连接器检测到表行中的值更改时，它会发出一个代表更改的事件。每个更改事件记录的结构与原始表相同，事件记录包含每个列值的字段。表列的数据类型决定了连接器如何代表更改事件字段中的列值，如以下部分所示。
对于表中的每个列，Debebe 将源数据类型映射到 字面类型，在某些情况下，一个 语义类型，在对应的 event 字段中。
- 字面类型
-
描述如何按字面表示值，使用以下 Kafka Connect 模式类型之一：
INT8,INT16,INT32,INT64, INT64 ,FLOAT32,FLOAT64,BOOLEAN,STRING,BYTES,ARRAY,MAP, 和STRUCT. - 语义类型
- 描述 Kafka Connect 模式如何使用字段的名称捕获字段 的含义。
如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。
对于某些 Oracle 大对象(CLOB、NCLOB 和 BLOB)和数字数据类型，您可以通过更改默认配置属性设置来操作连接器执行类型映射的方式。有关 Debezium 属性控制这些数据类型的映射的更多信息，请参阅 Binary 和 Character LOB 类型和 Numeric 类型。
如需有关 Debezium 连接器如何映射 Oracle 数据类型的更多信息，请参阅以下主题：
字符类型
下表描述了连接器如何映射基本字符类型。
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
使用 Debezium Oracle 连接器的 BLOB、CLOB 和 NCLOB 只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅 https://access.redhat.com/support/offerings/techpreview。
下表描述了连接器如何映射二进制和字符大对象(LOB)数据类型。
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
| 不适用 | 不支持这个数据类型 |
|
|
|
根据连接器配置中
|
|
|
| 不适用 |
|
| 不适用 | 不支持这个数据类型。 |
|
| 不适用 | 不支持这个数据类型。 |
|
|
| 不适用 |
|
| 不适用 |
根据连接器配置中
|
如果 Oracle 在 SQL 语句中明确设置了或更改，Oracle 仅为 CLOB、NCLOB 和 BLOB 数据类型提供列值。因此，更改事件永远不会包含未更改的 CLOB、NCLOB 或 BLOB 列的值。相反，它们包含连接器属性 unavailable.value.placeholder 定义的占位符。
如果 CLOB、NCLOB 或 BLOB 列的值已更新，则新值将放置在相应更新更改事件的 after 项中。before 元素包含不可用的值占位符。
数字类型
下表描述了 Debezium Oracle 连接器如何映射数字类型。
您可以改变连接器映射 Oracle DECIMAL, NUMBER, NUMERIC, 和 REAL 数据类型的方式，方法是修改连接器的 decimal.handling.mode 配置属性的值。当将属性设置为 precise 的默认值时，连接器会将这些 Oracle 数据类型映射到 Kafka Connect org.apache.kafka.connect.data.Decimal 逻辑类型，如表中所示。当将 属性的值设置为 双引号 或 字符串 时，连接器会对某些 Oracle 数据类型使用备用映射。如需更多信息，请参阅 下表中的 Semantic 类型和备注 列。
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
当
当将 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
当将
当将 |
|
|
|
当将
当将 |
|
|
|
|
|
|
|
当
当将 |
|
|
|
|
|
|
|
当将
当将 |
如前文所述，Oracle 允许 NUMBER 类型中的负扩展。当数字表示为 Decimal 时，这可能会导致转换为 Avro 格式的问题。十进制 类型包括缩放信息，但 Avro 规格 只允许规模的正数值。根据使用的 schema registry，可能会导致 Avro serialization 失败。要避免这个问题，您可以使用 NumberToZeroScaleConverter，它将带有负精度（小数点左面）的高的数字 (P - S >= 19) 转换为小数点右面零位的 Decimal 类型。它可以配置如下：
converters=zero_scale zero_scale.type=io.debezium.connector.oracle.converters.NumberToZeroScaleConverter zero_scale.decimal.mode=precise
converters=zero_scale
zero_scale.type=io.debezium.connector.oracle.converters.NumberToZeroScaleConverter
zero_scale.decimal.mode=precise
默认情况下，数字会被转换为 Decimal 类型(zero_scale.decimal.mode=precise)，但为了保证完全支持两种类型(双 和 字符串)也被支持。
布尔值类型
Oracle 不提供对 BOOLEAN 数据类型的原生支持。但是，通常使用带有特定语义的其他数据类型来模拟逻辑 BOOLEAN 数据类型的概念。
为了允许您将源列转换为布尔值数据类型，Debebe 提供了一个 NumberOneTo Boolean Converter 自定义转换器，您可使用以下方法之一使用：
-
将所有
NUMBER (1)列映射到BOOLEAN类型。 使用以逗号分隔的正则表达式列表枚举列的子集。
要使用这种类型的转换，您必须使用selector参数设置转换器配置属性，如下例所示：converters=boolean boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter boolean.selector=.*MYTABLE.FLAG,.*.IS_ARCHIVED
converters=boolean boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter boolean.selector=.*MYTABLE.FLAG,.*.IS_ARCHIVEDCopy to Clipboard Copied! Toggle word wrap Toggle overflow
临时类型
除了 Oracle INTERVAL,TIMESTAMP WITH TIME ZONE, 和 TIMESTAMP WITH LOCAL TIME ZONE 数据类型外，连接器转换时序类型的方式取决于 time.precision.mode 配置属性的值。
当 time.precision.mode 配置属性设置为 adaptive （默认值），那么连接器会根据列的数据类型确定 temporal 类型的字面和语义类型，以便事件 准确 表示数据库中的值：
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
当 time.precision.mode 配置属性设置为 connect 时，连接器会使用预定义的 Kafka Connect 逻辑类型。当消费者只了解内置 Kafka Connect 逻辑类型且无法处理变量调整时间值时，这很有用。由于 Oracle 支持的精度级别超过 Kafka Connect 支持中的逻辑类型，如果将 time.precision.mode 设置为 connect，当数据库列的 fractional second precision 值大于 2 时，会出现丢失精度的结果：
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ROWID 类型
下表描述了连接器如何映射 ROWID （托管地址）数据类型。
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
| 不适用 |
|
| 不适用 | 不支持此数据类型。 |
将 XMLTYPE 与 Debezium Oracle 连接器一起使用只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅 https://access.redhat.com/support/offerings/techpreview。
下表描述了连接器如何映射 XMLTYPE 数据类型。
| Oracle 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
用户定义的类型
Oracle 允许您定义自定义数据类型，以便在内置数据类型不符合您的要求时提供灵活性。有几个用户定义的类型，如对象类型、REF 数据类型、Varrays 和 Nested Tables。目前，您不能将 Debezium Oracle 连接器用于任何用户定义的类型。
Oracle 提供的类型
Oracle 提供基于 SQL 的接口，可用于在内置或 ANSI 支持的类型不足时定义新的类型。Oracle 提供多种常用的数据类型来满足各种目的，如 Any 或 Spatial 类型。目前，您不能将 Debezium Oracle 连接器用于任何这些数据类型。
默认值
如果为数据库模式中的列指定默认值，Oracle 连接器会尝试将此值传播到对应的 Kafka 记录字段的 schema。最常见的数据类型包括：
-
字符类型(
CHAR、NCHAR、VARCHAR、VARCHARNVARCHAR2、NVARCHAR2) -
数字类型(
inTEGER、NUMERIC等) -
时序类型(
DATE、TIMESTAMP、INTERVAL等等)
如果 temporal 类型使用 TO_TIMESTAMP 或 TO_DATE 等函数调用来代表默认值，则连接器将通过生成额外的数据库调用来评估该函数来解析默认值。例如，如果使用默认值 TO_ 定义 DATE 列，则列的默认值将是该日期的 UNIX epoch 或 DATE ('2021-01-02', 'YYYY-MM-DD')18629 开始的天数。
如果 temporal 类型使用 SYSDATE 常代表默认值，则连接器会根据列为 NOT NULL 或 NULL 来解决此问题。如果列可为空，则不会设置默认值；但是，如果列不可为空，则默认值将解析为 0（用于 DATE 或 TIMESTAMP(n) 数据类型）或 1970-01-01T00:00:00Z (用于 TIMESTAMP WITH TIME ZONE 或 TIMESTAMP WITH LOCAL TIME ZONE 数据类型)。默认值为数字，除非列是 TIMESTAMP WITH TIME ZONE 或 TIMESTAMP WITH LOCAL TIME ZONE，在这种情况下，其作为字符串发出。
自定义转换器
默认情况下，Debezium Oracle 连接器提供多个特定于 Oracle 数据类型的 CustomConverter 实现。这些自定义转换器根据连接器配置为特定数据类型提供替代映射。要在连接器中添加 CustomConverter，请按照 Custom Converters 文档中的 说明进行操作。
Debezium Oracle 连接器提供以下自定义转换器：
NUMBER (1) 到布尔值
从版本 23 开始，Oracle 数据库提供 BOOLEAN 逻辑数据类型。在早期版本中，数据库使用 NUMBER (1) 数据类型来模拟 BOOLEAN 类型，使用值 0 代表 false，或值 1 代表 true。
默认情况下，当 Debezium 为使用 NUMBER (1) 数据类型的源列发出更改事件时，它会将数据转换为 INT8 字面类型。如果 NUMBER (1) 数据类型的默认映射不满足您的需要，您可以将连接器配置为在通过配置 NumberOneToBooleanConverter 来发送这些列时使用逻辑 BOOL 类型，如下例所示：
示例： NumberOneToBooleanConverter 配置
converters=number-to-boolean number-to-boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter number-to-boolean.selector=.*.MY_TABLE.DATA
converters=number-to-boolean
number-to-boolean.type=io.debezium.connector.oracle.converters.NumberOneToBooleanConverter
number-to-boolean.selector=.*.MY_TABLE.DATA
在前面的示例中，selector 属性是可选的。selector 属性指定转换器应用到的表或列的正则表达式。如果省略 selector 属性，当 Debezium 发出一个事件时，带有 NUMBER (1) 数据类型的每个列都会转换为使用逻辑 BOOL 类型的字段。
NUMBER To Zero Scale
Oracle 支持 创建基于 带有负缩放的 NUMBER 列，即 NUMBER (-2)。并非所有系统都可以处理负缩放值，因此这些值可能会导致管道中处理问题。例如，因为 Apache Avro 不支持这些值，因此如果 Debezium 将事件转换为 Avro 格式，则可能会出现问题。同样，不支持这些值的下游用户也会遇到错误。
配置示例
converters=number-zero-scale number-zero-scale.type=io.debezium.connector.oracle.converters.NumberToZeroScaleConverter number-zero-scale.decimal.mode=precise
converters=number-zero-scale
number-zero-scale.type=io.debezium.connector.oracle.converters.NumberToZeroScaleConverter
number-zero-scale.decimal.mode=precise
在前面的示例中，decimal.mode 属性指定连接器如何发送十进制值。此属性是可选的。如果省略 decimal.mode 属性，则转换器默认使用 PRECISE 十进制处理模式。
RAW 到字符串
虽然 Oracle 建议使用某些数据类型，如 RAW，但旧系统可能会继续使用此类类型。默认情况下，Debebe 将 RAW 列类型作为逻辑 BYTES 发送，这是一种类型，用于启用二进制或基于文本的数据存储。
在某些情况下，RAW 列可能会将字符数据存储为一系列字节。要协助消费者使用，您可以将 Debezium 配置为使用 RawToStringConverter。RawToStringConverter 提供了一种方式，可以轻松地以此类 RAW 列为目标，并以字符串的形式发送值，而不是字节。以下示例演示了如何将 RawToStringConverter 添加到连接器配置中：
示例： RawToStringConverter 配置
converters=raw-to-string raw-to-string.type=io.debezium.connector.oracle.converters.RawToStringConverter raw-to-string.selector=.*.MY_TABLE.DATA
converters=raw-to-string
raw-to-string.type=io.debezium.connector.oracle.converters.RawToStringConverter
raw-to-string.selector=.*.MY_TABLE.DATA
在前面的示例中，选择器 属性允许您定义一个正则表达式，以指定转换器进程的表或列。如果省略 selector 属性，则转换器将所有 RAW 列类型映射到逻辑 STRING 字段类型。
2.5.4. 设置 Oracle 以使用 Debezium
设置 Oracle 以用于 Debezium Oracle 连接器需要执行下列步骤。这些步骤假定将多租户配置与容器数据库一起使用，以及至少一个可插拔数据库。如果您不打算使用多租户配置，可能需要调整以下步骤。
有关设置用于 Debezium 连接器的 Oracle 的详情，请参考以下部分：
2.5.4.1. Debezium Oracle 连接器与 Oracle 安装类型的兼容性
Oracle 数据库可以作为独立实例安装，也可以使用 Oracle Real Application Cluster (RAC)。Debezium Oracle 连接器与两种类型的安装兼容。
2.5.4.2. 在捕获更改事件时 Debezium Oracle 连接器不包括的 schema
当 Debezium Oracle 连接器捕获表时，它会自动从以下模式中排除表：
-
appqossys -
audsys -
ctxsys -
dvsys -
dbsfwuser -
dbsnmp -
qsmadmin_internal -
lbacsys -
mdsys -
ojvmsys -
olapsys -
orddata -
ordsys -
outln -
sys -
system -
vecsys(Oracle 23+) -
wmsys -
xdb
要启用连接器从表中捕获更改，该表必须使用在前面的列表中未命名的模式。
2.5.4.3. 在捕获更改事件时 Debezium Oracle 连接器排除的表
当 Debezium Oracle 连接器捕获表时，它会自动排除与以下规则匹配的表：
-
与
CMP[3|4hmac[0-9]+匹配的压缩顾问表。 -
与
SYS_IOT_OVER_%模式匹配的 index-organized 表。 -
与模式
MDRT_%、MDRS_%或MDXT_%匹配的 spatial 表。 - 嵌套表
要让连接器捕获名称与上述规则匹配的表，您必须重命名该表。
2.5.4.4. 准备 Oracle 数据库以用于 Debezium
Oracle LogMiner 所需的配置
Oracle AWS RDS 不允许执行上述命令，也允许您以 sysdba 身份登录。AWS 提供了这些替代命令来配置 LogMiner。在执行这些命令前，请确保为备份启用了 Oracle AWS RDS 实例。
要确认 Oracle 启用了备份，请首先执行以下命令。LOG_MODE 应使用 ARCHIVELOG。如果没有，您可能需要重启 Oracle AWS RDS 实例。
Oracle AWS RDS LogMiner 所需的配置
SQL> SELECT LOG_MODE FROM V$DATABASE; LOG_MODE ------------ ARCHIVELOG
SQL> SELECT LOG_MODE FROM V$DATABASE;
LOG_MODE
------------
ARCHIVELOG当 LOG_MODE 设置为 ARCHIVELOG 后，执行命令以完成 LogMiner 配置。第一个命令将数据库设置为 archivelogs，第二个命令添加了 supplemental 日志记录。
Oracle AWS RDS LogMiner 所需的配置
exec rdsadmin.rdsadmin_util.set_configuration('archivelog retention hours',24);
exec rdsadmin.rdsadmin_util.alter_supplemental_logging('ADD');
exec rdsadmin.rdsadmin_util.set_configuration('archivelog retention hours',24);
exec rdsadmin.rdsadmin_util.alter_supplemental_logging('ADD');
要让 Debezium 捕获更改数据库行之前的状态，还必须为捕获的表或整个数据库启用附件日志记录。以下示例演示了如何为单个 inventory.customers 表中的所有列配置补充日志记录。
ALTER TABLE inventory.customers ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;
ALTER TABLE inventory.customers ADD SUPPLEMENTAL LOG DATA (ALL) COLUMNS;为所有表列启用附加日志记录会增加 Oracle redo 日志的卷。要防止日志大小过度增长，请有选择地应用前面的配置。
在数据库级别上必须启用最少的附件日志记录，并可以配置如下：
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;
ALTER DATABASE ADD SUPPLEMENTAL LOG DATA;2.5.4.5. 调整 Oracle redo 日志的大小以容纳数据字典
根据数据库配置，恢复日志的大小和数量可能不足以达到可接受的性能。在设置 Debezium Oracle 连接器前，请确保 redo 日志的容量足以支持数据库。
数据库恢复日志的容量必须足以存储其数据字典。通常，数据字典的大小会随着数据库中表和列的数量而增加。如果红色日志缺少足够容量，数据库和 Debezium 连接器都可能会遇到性能问题。
请咨询您的数据库管理员，以评估数据库可能需要增加日志容量。
2.5.4.6. 指定 Debezium Oracle 连接器使用的归档日志目的地
Oracle 数据库管理员可以为存档日志配置最多 31 个不同的目的地。管理员可以为每个目的地设置参数，以为特定用途指定它，例如，记录物理待机日志或外部存储以允许扩展日志保留。Oracle 在 V$ARCHIVE_DEST_STATUS 视图中报告有关归档日志目的地的详细信息。
Debezium Oracle 连接器只使用状态为 VALID 和 LOCAL 的目的地。如果您的 Oracle 环境包含多个满足该条件的目的地，请咨询您的 Oracle 管理员以确定应该使用哪个归档日志目的地。
流程
-
要指定要使用的存档日志目的地，请在连接器配置中设置
log.mining.archive.destination.name属性。
例如，假设数据库配置了两个归档目标路径 /path/one 和，并且/path/twoV$ARCHIVE_DEST_STATUS表将这些路径与列DEST_NAME中指定的目标名称相关联。如果两个目的地都满足 Debezium netobserv-two 的条件，则其状态为VALID，并且其类型是LOCALHEKETI-busybox，将连接器配置为使用数据库写入/path/two的存档日志，将log.mining.archive.archive.destination.name的值设置为DEST_NAME列中的值，在V$ARCHIVE_DEST_DEST_STAUS.name 中与/path/two关联。例如，如果DEST_NAME为LOG_ARCHIVE_DEST_3用于/path/two，您可以将 Debezium 配置为：
{
"log.mining.archive.destination.name": "LOG_ARCHIVE_DEST_3"
}
{
"log.mining.archive.destination.name": "LOG_ARCHIVE_DEST_3"
}
不要将 log.mining.archive.destination.name 的值设置为数据库用于存档日志的路径。将 属性设置为满足归档日志保留策略的 V$ARCHIVE_DEST_STAT_STATUS 表中一行的 列中的归档日志目的地名称。
DEST_ NAME
如果您的 Oracle 环境包含多个满足该条件的目的地，并且您无法指定首选目的地，Debezium Oracle 连接器会随机选择目的地路径。因为为每个目的地配置的保留策略可能会有所不同，因此如果连接器选择从中删除请求的日志数据的路径，这可能会导致错误。
2.5.4.7. 为 Debezium Oracle 连接器创建 Oracle 用户
要使 Debezium Oracle 连接器捕获更改事件，它必须以具有特定权限的 Oracle LogMiner 用户身份运行。以下示例显示了用于在多租户数据库模型中为连接器创建 Oracle 用户帐户的 SQL。
连接器捕获其自身 Oracle 用户帐户所做的数据库更改。但是，它不会捕获 SYS 或 SYSTEM 用户帐户所做的更改。
创建连接器的 LogMiner 用户
| 项 | 角色名称 | 描述 |
|---|---|---|
| 1 | 创建会话 | 启用连接器连接到 Oracle。 |
| 2 | 设置容器 | 启用连接器在可插拔数据库间切换。只有在 Oracle 安装启用了容器数据库支持(CDB)时才需要这样做。 |
| 3 | SELECT ON V_$DATABASE |
启用连接器读取 |
| 4 | FLASHBACK 任何表 |
启用连接器执行 Flashback 查询，这是连接器如何执行数据的初始快照。另外，您还可以为所有表授予 |
| 5 | 选择任何表 |
启用连接器读取任何表。另外，您还可以为所有表授予 |
| 6 | SELECT_CATALOG_ROLE | 启用连接器读取数据字典，这是 Oracle LogMiner 会话所需的。 |
| 7 | EXECUTE_CATALOG_ROLE | 启用连接器将数据字典写入 Oracle redo 日志中，这是跟踪 schema 更改所必需的。 |
| 8 | 选择任何事务 |
启用快照进程，以针对任何事务执行 Flashback 快照查询。当授予 |
| 9 | LOGMINING | 在较新版本的 Oracle 中添加了此角色，作为授予 Oracle LogMiner 及其软件包的完整访问权限的方法。在没有此角色的较早版本的 Oracle 上，您可以忽略此授权。 |
| 10 | 创建表 | 启用连接器在其默认表空间中创建其 flush 表。flush 表允许连接器明确控制 LGWR 内部缓冲区刷新到磁盘。 |
| 11 | 锁定任何表 | 启用连接器在模式快照期间锁定表。如果通过配置明确禁用了快照锁定，则可以安全地忽略这个授权。 |
| 12 | 创建序列 | 启用连接器在默认表空间中创建序列。 |
| 13 | EXECUTE ON DBMS_LOGMNR |
启用连接器在 |
| 14 | EXECUTE ON DBMS_LOGMNR_D |
启用连接器在 |
| 15 到 25 | SELECT ON V_$…. | 启用连接器来读取这些表。连接器必须能够读取 Oracle redo 和 archive 日志的信息，以及当前的事务状态，才能准备 Oracle LogMiner 会话。如果没有这些授权，连接器无法操作。 |
2.5.4.8. 使用 Oracle 待机数据库运行连接器
备用数据库提供主实例的同步副本。如果出现主数据库故障，备用数据库提供连续可用性和灾难恢复。Oracle 同时使用物理和逻辑备用数据库。
物理待机
物理待机是主生产数据库的确切块副本，其系统更改号(SCN)值与主数据库的值相同。Debezium Oracle 连接器无法直接从物理待机数据库捕获更改事件，因为物理待机不接受外部连接。连接器只能在将待机转换为主数据库后从物理待机中捕获事件。然后，连接器会连接到以前的待机，就像是任何主数据库一样。
逻辑待机
逻辑待机包含与主数据相同的逻辑数据，但数据可能会以不同的物理方式存储。逻辑待机中的 SCN 偏移与主数据库中的偏移量不同。您可以将 Debezium Oracle 连接器配置为从逻辑待机数据库捕获更改。
2.5.4.8.1. 从 Oracle 故障转移数据库捕获数据
当您设置故障转移数据库时，通常最好使用物理备用数据库而不是逻辑待机数据库。物理待机与主数据库保持一致状态，而不是逻辑待机。物理待机包含主数据的确切副本，并且待机系统的更改号(SCN)值与主数据的不同。在 Debezium 环境中，数据库故障转移到物理待机后，存在一致的 SCN 值可确保连接器可以找到最后处理的 SCN 值。
物理待机以只读模式锁定，运行受管恢复以维护同步。当数据库处于待机模式时，它不接受来自客户端的外部 JDBC 连接，并且外部应用无法访问它。
在失败事件后，要允许 Debezium 连接到以前的物理待机，DBA 必须执行几个操作来启用故障转移到待机，并将它提升为主数据库。以下列表标识了一些关键操作：
- 在待机上取消受管恢复。
- 完成活动的恢复过程。
- 将待机转换为主要角色。
- 打开客户端读写操作的新主要内容。
在以前的物理待机可用后，您可以将 Debezium Oracle 连接器配置为连接它。要让连接器从新的主设备捕获，请在连接器配置中编辑数据库主机名，将原始主的主机名替换为新主主机名。
2.5.4.8.2. 配置 Debezium Oracle 连接器以从逻辑待机中捕获事件
当 Oracle 的 Debezium 连接器连接到主数据库时，它使用内部清除表来管理 Oracle Log Writer Buffer (LGWR)进程的清除周期。flush 进程要求用户帐户访问数据库具有创建和写入此清除表的权限。但是，逻辑独立数据库通常允许只读访问，从而导致连接器写入数据库。您可以修改连接器配置，使连接器可以从逻辑待机捕获事件，或者 DBA 可以创建一个新的可写表空间，连接器可以在其中存储 flush 表。
Debezium Oracle 连接器从只读逻辑待机数据库中尽力更改是开发者预览功能。红帽不支持开发人员预览功能，且功能完整或生产就绪。不要将开发人员预览软件用于生产环境或关键业务工作负载。开发人员预览软件提供早期对即将推出的产品软件的访问权限，以将其包括在红帽产品产品中。客户可以使用此软件来测试功能并在开发过程中提供反馈。此软件可能没有任何文档，可以随时更改或删除，并且已获得有限的测试。红帽可能会提供在没有关联 SLA 的情况下对开发者预览软件提交反馈的方法。
有关 Red Hat Developer Preview 软件的支持范围的更多信息，请参阅 开发人员预览支持范围。
流程
要启用 Debezium 从 Oracle 只读逻辑待机数据库中捕获事件，请在连接器配置中添加以下属性，以禁用清除表的创建和管理：
internal.log.mining.read.only=true
internal.log.mining.read.only=trueCopy to Clipboard Copied! Toggle word wrap Toggle overflow 上述设置可防止数据库创建和更新
LOG_MINING_FLUSH表。您可以将internal.log.mining.read.only属性与 Oracle Standalone 数据库一起使用，或者与 Oracle RAC 安装一起使用。
2.5.5. 部署 Debezium Oracle 连接器
您可以使用以下任一方法部署 Debezium Oracle 连接器：
由于许可证要求，Debezium Oracle 连接器存档不包括连接器连接到 Oracle 数据库所需的 Oracle JDBC 驱动程序。要启用连接器访问数据库，您必须在连接器环境中添加驱动程序。如需更多信息，请参阅 获取 Oracle JDBC 驱动程序。
2.5.5.1. 获取 Oracle JDBC 驱动程序
由于许可证要求，Debezium 连接到 Oracle 数据库所需的 Oracle JDBC 驱动程序文件不包括在 Debezium Oracle 连接器存档中。该驱动程序可从 Maven Central 下载。根据您使用的部署方法，您可以通过将命令添加到 Kafka Connect 自定义资源或用于构建连接器镜像的 Dockerfile 来检索驱动程序。
-
如果您使用 Streams for Apache Kafka 将连接器添加到 Kafka Connect 镜像，请将驱动程序的 Maven Central 位置添加到
KafkaConnect自定义资源中的builds.plugins.artifact.url中，如 第 2.5.5.3 节 “使用 Streams for Apache Kafka 部署 Debezium Oracle 连接器” 所示。 -
如果您使用 Dockerfile 为连接器构建容器镜像，请在 Dockerfile 中插入
curl命令，以指定从 Maven Central 下载所需驱动程序文件的 URL。如需更多信息，请参阅 通过从 Dockerfile 构建自定义 Kafka Connect 容器镜像来部署 Debezium Oracle 连接器。
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅在 OpenShift Container Platform 中管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.34. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium Oracle 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关语言依赖项。SMT 归档和语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
- Oracle JDBC 驱动程序需要连接到 Oracle 数据库，但不包含在连接器存档中。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.120. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。JDBC 驱动程序文件采用.jar格式。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Red Hat Maven 存储库中提供了 Debezium 连接器工件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需的脚本语言组件
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
11
指定 Maven Central 中 Oracle JDBC 驱动程序的位置。Debezium Oracle 连接器存档中不包含所需的驱动程序。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为oracle-inventory-connector.yaml例 2.35. 为 Debezium 连接器定义
KafkaConnector自定义资源的 Oracle-inventory-connector.yaml文件Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.121. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址。
6
数据库实例的端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
9
要从中捕获更改的数据库的名称。
10
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。11
连接器捕获更改事件的表列表。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f oracle-inventory-connector.yaml
oc create -n debezium -f oracle-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
您现在已准备好 验证 Debezium Oracle 部署。
要部署 Debezium Oracle 连接器，您必须构建包含 Debezium 连接器存档的自定义 Kafka Connect 容器镜像，然后将此容器镜像推送到容器 registry。然后，您需要创建以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium Oracle 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- Oracle 数据库正在运行，您完成了 设置 Oracle 以使用 Debezium 连接器 的步骤。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka的流
- podman 或 Docker 已安装。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。 Kafka Connect 服务器有权访问 Maven Central，以下载 Oracle 所需的 JDBC 驱动程序。您还可以使用驱动程序的本地副本，或使用本地 Maven 存储库或其他 HTTP 服务器可用的副本。
如需更多信息，请参阅 获取 Oracle JDBC 驱动程序。
流程
为 Kafka Connect 创建 Debezium Oracle 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-oracle.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-oracle.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-oracle:latest .
podman build -t debezium-container-for-oracle:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-oracle:latest .
docker build -t debezium-container-for-oracle:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令使用名称
debezium-container-for-oracle构建容器镜像。将自定义镜像推送到容器 registry，如 quay.io 或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：
podman push <myregistry.io>/debezium-container-for-oracle:latest
podman push <myregistry.io>/debezium-container-for-oracle:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-oracle:latest
docker push <myregistry.io>/debezium-container-for-oracle:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium Oracle KafkaConnect 自定义资源(CR)。例如，使用名称
dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。输入以下命令将
KafkaConnectCR 应用到 OpenShift Kafka Connect 环境：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令添加一个 Kafka Connect 实例，用于指定为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium Oracle 连接器实例。您可以在指定连接器的配置属性的
.yaml文件中配置 Debezium Oracle 连接器。连接器配置可能会指示 Debezium 为模式和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略、掩码或截断指定列中的值，这些值是敏感、太大或不需要的。以下示例配置了在端口
1521上连接到 Oracle 主机 IP 地址的 Debezium 连接器。此主机有一个名为ORCLCDB的数据库，server1是服务器的逻辑名称。Oracle
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.122. 连接器配置设置的描述 项 描述 1
当使用 Kafka Connect 服务注册时，连接器的名称。
2
此 Oracle 连接器类的名称。
3
Oracle 实例的地址。
4
Oracle 实例的端口号。
5
Oracle 用户的名称，如 为 连接器创建用户 中所述。
6
Oracle 用户的密码，如为 连接器创建用户 中所述。
7
要从中捕获更改的数据库的名称。
8
连接器从中捕获更改的 Oracle 可插拔数据库的名称。仅在容器数据库(CDB)安装中使用。
9
主题前缀标识，并为 Oracle 数据库服务器提供命名空间，连接器从中捕获更改。
10
此连接器用来将 DDL 语句写入并恢复到数据库 schema 历史记录主题的 Kafka 代理列表。
11
连接器写入和恢复 DDL 语句的数据库架构历史记录主题的名称。本主题仅用于内部使用，不应供消费者使用。
使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的server1数据库运行。
有关您可以为 Debezium Oracle 连接器设置的配置属性的完整列表，请参阅 Oracle 连接器属性。
结果
连接器启动后，它会执行为连接器配置的 Oracle 数据库的一致性快照。然后，连接器开始为行级操作生成数据更改事件，并将更改事件记录流传输到 Kafka 主题。
2.5.5.5. 配置容器数据库和非容器数据库
Oracle 数据库支持以下部署类型：
- 容器数据库(CDB)
- 可以包含多个可插拔数据库(PDB)的数据库。数据库客户端连接到每个 PDB，就像它是标准的非CDB 数据库一样。
- 非容器数据库（非CDB）
- 标准 Oracle 数据库，不支持创建可插拔数据库。
2.5.5.6. 验证 Debezium Oracle 连接器是否正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，点您要检查的连接器名称，如 inventory-connector-oracle。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-oracle -n debezium
oc describe KafkaConnector inventory-connector-oracle -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.36.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，单击要检查的主题的名称，例如
inventory-connector-oracle.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.37.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-oracle.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-oracle.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中返回的
oc describe命令相同，例如inventory-connector-oracle.inventory.addresses。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.38. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-oracle.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-oracle.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-oracle.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.oracle.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-oracle.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"oracle","name":"inventory-connector-oracle","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"oracle-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-oracle.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-oracle.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-oracle.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.oracle.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-oracle.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"oracle","name":"inventory-connector-oracle","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"oracle-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
2.5.6. Debezium Oracle 连接器配置属性的描述
Debezium Oracle 连接器有许多配置属性，可用于为应用程序获得正确的连接器行为。许多属性具有默认值。有关属性的信息按如下方式进行组织：
- 所需的 Debezium Oracle 连接器配置属性
- 数据库架构历史记录连接器配置属性，用于控制 Debezium 如何处理从数据库架构历史记录主题读取的事件。
所需的 Debezium Oracle 连接器配置属性
除非默认值可用 ， 否则需要以下配置属性。
| 属性 | 默认 | 描述 |
| 没有默认值 | 连接器的唯一名称。尝试使用相同名称再次注册将失败。（所有 Kafka 连接连接器都需要此属性。） | |
| 没有默认值 |
连接器的 Java 类的名称。对于 | |
| 没有默认值 |
枚举连接器可以使用的 自定义转换器 实例的符号链接名称列表。
对于您为连接器配置的每个转换器，还必须添加一个
例如， boolean.type: io.debezium.connector.oracle.converters.NumberOneToBooleanConverter
如果要进一步控制配置的转换器的行为，您可以添加一个或多个配置参数来将值传递给转换器。要将任何其他配置参数与转换器关联，请为参数名称添加转换器符号名称前缀。 boolean.selector: .*MYTABLE.FLAG,.*.IS_ARCHIVED | |
|
| 为此连接器创建的最大任务数量。Oracle 连接器始终使用单个任务，因此不使用这个值，因此始终可以接受默认值。 | |
| 没有默认值 | Oracle 数据库服务器的 IP 地址或主机名。 | |
| 没有默认值 | Oracle 数据库服务器的整数端口号。 | |
| 没有默认值 | 连接器用来连接到 Oracle 数据库服务器的 Oracle 用户帐户的名称。 | |
| 没有默认值 | 连接到 Oracle 数据库服务器时要使用的密码。 | |
| 没有默认值 | 要连接的数据库的名称。在容器数据库环境中，指定根容器数据库(CDB)的名称，而不是包含的可插拔数据库(PDB)的名称。 | |
| 没有默认值 | 指定原始数据库 JDBC URL。使用此属性提供定义该数据库连接的灵活性。有效值包括原始 TNS 名称和 RAC 连接字符串。 | |
| 没有默认值 | 要连接的 Oracle 可插拔数据库的名称。仅将此属性与容器数据库(CDB)安装一起使用。 | |
| 没有默认值 |
为 Oracle 数据库服务器提供命名空间的主题前缀，连接器会捕获更改。您设置的值用作连接器发出的所有 Kafka 主题名称的前缀。指定在 Debezium 环境中所有连接器之间唯一的主题前缀。以下字符有效：字母数字字符、连字符、点和下划线。 警告 不要更改此属性的值。如果您更改了 name 值，重启后，而不是继续向原始主题发送事件，连接器会将后续事件发送到名称基于新值的主题。连接器也无法恢复其数据库架构历史记录主题。 | |
|
| 连接器在流数据库更改时使用的适配器实现。您可以设置以下值：
| |
| Initial | 指定连接器用来获取捕获表快照的模式。您可以设置以下值：
快照完成后，连接器将继续从数据库的红色日志中读取更改事件，除非
如需更多信息，请参阅 | |
| shared | 控制连接器保存表锁定的时长。表锁定可防止在连接器执行快照时发生某些类型的更改表操作。您可以设置以下值：
| |
|
|
指定连接器在执行快照时如何查询数据。
与使用 | |
|
在连接器 |
可选的、以逗号分隔的正则表达式列表，与表的完全限定名称(<
在多租户容器数据库(CDB)环境中，正则表达式必须包含 可插拔数据库(PDB)名称，格式为 <
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。
快照只能包含在连接器的
只有在连接器的 | |
| 没有默认值 | 指定要包含在快照中的表行。如果您希望快照只包括表中的行的子集，请使用该属性。此属性仅影响快照。它不适用于连接器从日志读取的事件。
属性包含以逗号分隔的完全限定表名称列表，格式为 <
从包括软删除列 "snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM customers.orders WHERE delete_flag = 0 ORDER BY id DESC"
在生成的快照中，连接器只包含 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您要 捕获更改的模式名称匹配。只有 POSIX 正则表达式有效。没有包含在 schema.
要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 schema 的整个名称字符串匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
|
| 布尔值指定连接器是否应该在元数据对象上解析和发布表和列注释。启用此选项将对内存用量产生影响。逻辑模式对象的数量和大小非常大会影响 Debezium 连接器消耗的内存量，并在每个对象中添加潜在的大型字符串数据可能非常昂贵。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与 您不想 捕获更改的模式名称匹配。只有 POSIX 正则表达式有效。任何名称不包含在 schema.
要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 schema 的整个名称字符串匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与要捕获的表的完全限定表标识符匹配。只有 POSIX 正则表达式有效。当设置此属性时，连接器只从指定的表中捕获更改。每个表标识符都使用以下格式：
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
| 没有默认值 |
可选的正则表达式列表，该表达式与要从监控中排除的表的完全限定表标识符匹配。只有 POSIX 正则表达式有效。连接器从 exclude 列表中没有指定的任何表捕获更改事件。使用以下格式指定每个表的标识符：
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与 change 事件消息值中包含的列的完全限定域名匹配。只有 POSIX 正则表达式有效。列的完全限定域名使用以下格式：
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您要从更改事件消息值中排除的列的完全限定域名匹配。只有 POSIX 正则表达式有效。完全限定列名称使用以下格式：
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。 | |
|
|
指定在包含的列中没有更改时跳过发布消息。如果列没有包括每个 | |
|
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。列的完全限定域名格式为
一个 pseudonym，它包括了通过应用指定的 hashAlgorithm 和 salt 的结果的哈希值。根据使用的 hash 功能，引用完整性会被维护，而列值则替换为 pseudonyms。Java 加密架构标准算法 文档的 MessageDigest 部分中 描述了支持的哈希功能。 column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName
如有必要，pseudonym 会自动缩短到列的长度。连接器配置可以包含多个属性，以指定不同的哈希算法和 salt。 |
| bytes |
指定在更改事件中二进制( | |
| none |
指定应该如何调整模式名称，以便与连接器使用的消息转换器兼容。可能的设置：
| |
| none |
指定应如何调整字段名称，以便与连接器使用的消息转换器兼容。可能的设置：
如需了解更多详细信息，请参阅 Avro 命名。 | |
|
|
指定连接器应如何处理
| |
|
|
指定连接器如何处理 | |
|
| 指定连接器在处理事件时应如何响应异常。您可以设置以下选项之一：
| |
|
| 一个正整数值，用于指定要在此连接器的每个批处理事件的最大大小。 | |
|
|
正整数值，用于指定阻塞队列可以保存的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将 | |
|
|
指定阻塞队列的最大卷的长整数值，以字节为单位。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。 | |
|
| 正整数值指定连接器在每次迭代过程中应等待的毫秒数，以便出现新的更改事件。 | |
|
| 控制 delete 事件后跟一个 tombstone 事件。可能会有以下值：
删除源记录后，tombstone 事件（默认行为）可让 Kafka 完全删除在启用了 日志压缩的主题中已删除行的密钥的所有事件。 | |
| 没有默认值 | 一个表达式列表，用于指定连接器用来组成自定义消息键的表达式列表，用于更改它发布到指定表的 Kafka 主题。
默认情况下，Debebe 使用表的主键列作为发出的记录的消息键。使用默认键，或者为缺少主密钥的表指定一个键，您可以根据一个或多个列配置自定义消息密钥。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果您希望连接器屏蔽一组列的值，例如，如果它们包含敏感数据，则设置此属性。将
一个列的完全限定名称会观察以下格式：< 您可以在单个配置中指定多个长度不同的属性。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，用于对更改事件中的列名称进行掩码处理，将字符替换为星号 ( | |
| 没有默认值 | 可选的、以逗号分隔的正则表达式列表，与您希望连接器发送代表列元数据的额外参数匹配。当设置此属性时，连接器将以下字段添加到事件记录的 schema 中：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
一个列的完全限定名称会观察以下格式之一： < | |
| 没有默认值 | 可选的、以逗号分隔的正则表达式列表，用于指定为数据库中列定义的数据类型的完全限定名称。当设置此属性时，对于带有匹配数据类型的列，连接器会发出事件记录，该记录在其 schema 中包含以下额外字段：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
一个列的完全限定名称会观察以下格式之一： < 有关特定于 Oracle 数据类型名称的列表，请参阅 Oracle 数据类型映射。 | |
|
|
指定（以毫秒为单位）连接器将信息发送到 heartbeat 主题的频率。 | |
| 没有默认值 |
指定当连接器发送心跳消息时连接器在源数据库上执行的查询。 设置此属性并创建一个心跳表，以接收心跳信息，以解决 Debezium 无法同步与高流量数据库位于同一主机上的低流量数据库的偏移 的情况。在连接器将记录插入到配置的表中后，它能够接收来自 low-traffic 数据库的更改，并确认数据库中的 SCN 更改，以便偏移可以与代理同步。 | |
| 没有默认值 |
指定连接器在拍摄快照前等待的时间间隔（毫秒）。 | |
| 0 |
指定连接器在完成快照后延迟流过程启动的时间（以毫秒为单位）。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的 | |
|
| 指定在拍摄快照时应在每个表中读取的最大行数。连接器以指定大小的多个批处理读取表内容。 | |
|
|
指定给定查询的每个数据库往返获取的行数。使用 | |
|
|
如果您希望 Debezium 生成带有事务边界的事件，并使用事务元数据丰富数据事件，将属性设置为 如需了解更多详细信息，请参阅 Transaction Metadata。 | |
|
|
指定控制 Oracle LogMiner 构建如何使用给定数据字典来解析表和列 ids 的 mining 策略。 | |
|
|
指定控制如何构建 Oracle LogMiner 查询的 mining query 模式。 | |
|
|
缓冲区类型控制连接器管理缓冲区事务数据的方式。 | |
|
|
在使用新会话前，LogMiner 会话可以处于活跃状态的最大毫秒数。 | |
|
|
指定 JDBC 连接是否关闭并在日志交换机上重新打开，还是在 mining 会话达到最长生命周期阈值时。 | |
|
| 此连接器尝试从 redo/archive 日志读取的最小 SCN 间隔大小。活跃的批处理大小也会增加/减少这个数量，以便在需要时调优连接器吞吐量。 | |
|
| 从 redo/archive 日志读取时此连接器使用的最大 SCN 间隔大小。 | |
|
| 连接器用于从 redo/archive 日志读取数据的起始 SCN 间隔大小。这也服务器作为调整批处理大小的一种措施 - 当当前 SCN 和批处理开始/端 SCN 之间的区别大于这个值时，批处理大小会增加/减少。 | |
|
| 从 redo/archive 日志读取数据后，连接器在从 redo/archive 日志读取后，以及再次读取数据前的最短时间。值以毫秒为单位。 | |
|
| 在从 redo/archive 日志读取数据后，连接器在从 redo/archive 日志读取数据后，以及再次开始读取数据前，连接器会处于睡眠状态的最长时间。值以毫秒为单位。 | |
|
| 从 redo/archive 日志读取数据后，连接器在从 redo/archive 日志读取后处于睡眠状态的开始时间，然后再重新开始读取数据。值以毫秒为单位。 | |
|
| 连接器用于在从 logminer 读取数据时调整最佳睡眠时间的最大时间量。值以毫秒为单位。 | |
|
|
过去从 SYSDATE 到 mine 归档日志的小时数。当使用默认设置 | |
|
|
控制连接器是否从归档日志或在线恢复日志和存档日志（默认）的组合中减去更改。 | |
|
|
连接器在轮询之间休眠的毫秒数，以确定启动系统更改号是否在存档日志中。如果没有启用 | |
|
|
正整数值，用于指定在红色日志交换机之间保持长时间运行的事务的毫秒数。当设置为 默认情况下，LogMiner 适配器维护所有正在运行的事务的内存缓冲区。因为所有作为事务一部分的 DML 操作都会被缓冲，直到检测到提交或回滚前，应该避免长时间运行的事务，以便不会溢出该缓冲区。任何超过此配置值的事务都会被完全丢弃，连接器不会为作为事务一部分的操作发出任何消息。 | |
| 没有默认值 |
使用 LogMiner 指定一个归档日志时要使用的 Oracle 存档目的地。 | |
| 没有默认值 | 要从 LogMiner 查询中包含的数据库用户列表。如果您希望捕获过程包含来自指定用户的更改，则设置此属性会很有用。 | |
| 没有默认值 | 要从 LogMiner 查询中排除的数据库用户列表。如果您希望捕获过程始终排除特定用户所做的更改，则设置此属性会很有用。 | |
|
|
指定一个值，连接器与当前和之前的 SCN 值之间的差别进行比较，以确定 SCN 差距是否存在。如果 SCN 值之间的区别大于指定的值，且时间差异小于 | |
|
|
指定一个值，以毫秒为单位，连接器与当前和之前的 SCN 时间戳之间的差别进行比较，以确定 SCN 差距是否存在。如果时间戳之间的区别小于指定的值，并且 SCN delta 大于 | |
|
|
指定协调将 Oracle LogWriter Buffer (LGWR)刷新表到红色日志的 flush 表的名称。可以使用 < | |
|
|
指定在 | |
|
|
控制在更改事件中是否发出大型对象(CLOB 或 BLOB)列值。 注意 使用大型对象数据类型是一个技术预览功能。 | |
|
| 指定连接器提供的常量，表示原始值没有变化，不是由数据库提供。 | |
| 没有默认值 | 以逗号分隔的 Oracle Real Application Clusters (RAC)节点主机名或地址列表。需要此字段才能启用与 Oracle RAC 部署的兼容性。 使用以下方法之一指定 RAC 节点列表：
如果您使用 | |
|
| 以逗号分隔的操作类型列表，您希望连接器在流传输过程中跳过。您可以将连接器配置为跳过以下类型的操作：
默认情况下，只跳过 truncate 操作。 | |
| 没有默认值 |
用于向连接器发送信号的数据收集的完全限定名称。https://docs.redhat.com/documentation/en/red_hat_build_of_debezium/2.7.3/html-single/debezium_user_guide/index#debezium-signaling-enabling-source-signaling-channel当您将此属性与 Oracle 可插拔数据库(PDB)搭配使用时，请将其值设为根数据库的名称。 | |
| source | 为连接器启用的信号通道名称列表。默认情况下，以下频道可用：
| |
| 没有默认值 | 为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
| |
|
| 连接器在增量快照块期间获取并读取的最大行数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。 | |
|
|
指定连接器在增量快照中使用的水位线机制，以重复数据删除事件，这些事件可能会被增量快照捕获，然后在流恢复后重新捕获。
| |
|
|
应用于确定数据更改的主题名称、模式更改、事务、心跳事件等主题名称，默认为 | |
|
|
指定主题名称的分隔符，默认为 | |
|
| 在绑定的并发散列映射中保存主题名称的大小。此缓存将有助于确定与给定数据收集对应的主题名称。 | |
|
|
控制连接器发送心跳消息的主题名称。主题名称具有此模式： | |
|
|
控制连接器发送事务元数据消息的主题名称。主题名称具有此模式： | |
|
| 指定连接器在执行初始快照时使用的线程数量。要启用并行初始快照，请将 属性设置为大于 1 的值。在并行初始快照中，连接器同时处理多个表。 重要 并行初始快照只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。 | |
|
<oracle-property-snapshot-database-errors-max-retries, |
|
指定发生数据库错误时重试尝试快照表的数量。此配置属性目前只重试与 |
|
|
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如 连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。 | |
|
|
指定连接器如何在生成 Retriable 错误的操作后响应，如连接错误。
| |
|
| 等待查询执行的时间（以毫秒为单位）。默认为 600 秒(600,000 ms)；零表示没有限制。 |
Debezium Oracle 连接器数据库模式历史记录配置属性
Debezium 提供了一组 schema.history.internal.* 属性，用于控制连接器如何与 schema 历史记录主题进行交互。
下表描述了用于配置 Debezium 连接器的 schema.history.internal 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器存储数据库 schema 历史记录的 Kafka 主题的完整名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机/端口对列表。此连接用于检索之前由连接器存储的数据库架构历史记录，以及写入从源数据库读取的每个 DDL 语句。每个对都应该指向 Kafka Connect 进程使用的相同 Kafka 集群。 | |
|
| 整数值，指定连接器在启动/恢复期间应等待的最大毫秒数，同时轮询持久数据。默认值为 100ms。 | |
|
| 指定连接器在使用 Kafka admin 客户端获取集群信息时应等待的最大毫秒数。 | |
|
| 指定连接器在使用 Kafka admin 客户端创建 kafka 历史记录主题时应等待的最大毫秒数。 | |
|
|
连接器在连接器恢复失败前尝试读取持久性历史记录数据的次数上限，并显示错误。没有数据后等待的最长时间是 | |
|
|
指定连接器是否应该忽略不正确的或未知数据库语句的布尔值，或停止处理，以便用户可以解决这个问题。安全默认为 | |
|
|
指定连接器是否记录模式或数据库中所有表的布尔值，或者仅从指定为捕获的表记录。
| |
|
|
指定连接器是否从数据库实例中的所有逻辑数据库记录模式结构的布尔值。
|
直通 Oracle 连接器配置属性
连接器支持 通过传递 属性，使 Debezium 指定自定义配置选项来微调 Apache Kafka producer 和消费者的行为。有关 Kafka 生成者和消费者的完整配置属性范围的详情，请参考 Kafka 文档。
直通属性，用于配置生成者和消费者客户端如何与 schema 历史记录主题交互
Debezium 依赖于 Apache Kafka producer 将 schema 更改写入数据库 schema 历史记录主题。同样，它依赖于 Kafka 使用者在连接器启动时从数据库 schema 历史记录主题中读取。您可以通过将值分配给一组以 schema.history.internal.producer和 schema.history.internal.consumerPromQL 前缀开头的 pass-through 配置属性来定义 Kafka producer 和 消费者 客户端的配置。pass-through producer 和 consumer 数据库模式历史记录属性控制一系列行为，如这些客户端如何与 Kafka 代理安全连接，如下例所示：
Debezium 在将属性传递给 Kafka 客户端前从属性名称中剥离前缀。
有关 Kafka producer 配置属性和 Kafka 使用者配置属性的更多信息，请参阅 Apache Kafka 文档。
用于通过属性配置 Oracle 连接器如何与 Kafka 信号主题交互
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
为信号频道配置 Kafka 消费者客户端的属性
Debezium 连接器提供信号 Kafka 使用者的直通配置。透传信号属性以 signals.consumer.* 前缀开始。例如，连接器将 signal.consumer.security.protocol=SSL 等属性传递给 Kafka 使用者。
Debezium 在将属性传递给 Kafka 信号消费者前从属性中剥离前缀。
用于配置 Oracle 连接器接收器通知频道的直通属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
Debezium 连接器传递数据库驱动程序配置属性
Debezium 连接器提供数据库驱动程序的直通配置。透传数据库属性以前缀 driverPROFILE 开头。例如，连接器将 driver.foobar=false 等属性传递给 JDBC URL。
Debezium 在将属性传递给数据库驱动程序前从属性中剥离前缀。
2.5.7. 监控 Debezium Oracle 连接器性能
Debezium Oracle 连接器除了 Apache Zookeeper、Apache Kafka 和 Kafka Connect 的内置支持外，还提供三种指标类型。
有关如何通过 JMX 公开这些指标的详情，请参考 监控文档。
2.5.7.1. 用于 Oracle 连接器快照和流 MBean 对象的自定义名称
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.39. 自定义标签如何修改连接器 MBean 名称
默认情况下，Oracle 连接器使用以下 MBean 名称进行流传输指标：
debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.oracle:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.5.7.2. Debezium Oracle 连接器快照指标
MBean 为 debezium.oracle:type=connector-metrics,context=snapshot,server= <topic.prefix>。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
连接器还会在执行增量快照时提供以下附加快照指标：
2.5.7.3. Debezium Oracle 连接器流指标
MBean 为 debezium.oracle:type=connector-metrics,context=streaming,server= <topic.prefix>。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
Debezium Oracle 连接器还提供以下额外的流指标：
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 已处理的最新系统更改号。 | |
|
| 事务缓冲区中最旧的系统更改号。 | |
|
|
最旧的系统更改号（以毫秒为单位）。如果缓冲区为空，则该值将是 | |
|
| 最后提交的系统更改事务缓冲区中的数字。 | |
|
| 系统更改号当前写入连接器的偏移量。 | |
|
| 当前减去的日志文件数组。 | |
|
| 为任何 LogMiner 会话指定的最小日志数。 | |
|
| 为任何 LogMiner 会话指定的最大日志数。 | |
|
|
每个 mined logfile 的当前状态数组，格式为 file | |
|
| 数据库执行最近一天的日志切换的次数。 | |
|
| 最后的 LogMiner 会话查询中观察到的 DML 操作数量。 | |
|
| 处理单个 LogMiner 会话查询时观察到的最大 DML 操作数。 | |
|
| 观察到的 DML 操作总数。 | |
|
| 执行的 LogMiner 会话查询（也称为批处理）的总数。 | |
|
| 最后一次 LogMiner 会话查询的持续时间（以毫秒为单位）。 | |
|
| 任何 LogMiner 会话查询的最长持续时间（以毫秒为单位）。 | |
|
| 处理最后一个 LogMiner 查询批处理的持续时间会导致毫秒。 | |
|
| 解析 DML 事件 SQL 语句的时间（毫秒）。 | |
|
| 启动最后一个 LogMiner 会话的持续时间（毫秒）。 | |
|
| 启动 LogMiner 会话的最长时间，以毫秒为单位。 | |
|
| 连接器启动 LogMiner 会话的总持续时间（毫秒）。 | |
|
| 单一 LogMiner 会话处理结果的最短持续时间（以毫秒为单位）。 | |
|
| 单一 LogMiner 会话处理结果的最大持续时间（以毫秒为单位）。 | |
|
| LogMiner 会话处理结果的总持续时间（毫秒）。 | |
|
| JDBC 驱动程序所花费的总持续时间（毫秒）从 log mining 视图获取下一行。 | |
|
| 从日志 mining 视图中处理的所有会话的行总数。 | |
|
| log mining query per database round-trip 获取的条目数。 | |
|
| 从日志 mining 视图获取另一批结果前，连接器睡眠的毫秒数。 | |
|
| 从 log mining 视图处理的最大行/秒数。 | |
|
| 从日志 mining 处理的平均行/秒数。 | |
|
| 从上一次批处理的 log mining 视图中处理的平均行/秒数。 | |
|
| 检测到的连接问题数量。 | |
|
|
在被丢弃前，事务被连接器的内存中缓冲区保留的小时数，而不提交或回滚。如需更多信息，请参阅 | |
|
| 事务缓冲区中当前活动事务的数量。 | |
|
| 事务缓冲区中提交事务的数量。 | |
|
| 事务缓冲区中回滚事务的数量。 | |
|
| 事务缓冲区中每秒提交事务的平均数量。 | |
|
| 事务缓冲区中注册的 DML 操作数量。 | |
|
| 事务日志中变化和添加到事务缓冲区时的时间差（毫秒）。 | |
|
| 事务日志中变化和添加到事务缓冲区时的最大时间差（毫秒）。 | |
|
| 事务日志中变化和添加到事务缓冲区时的最小时间差异（毫秒）。 | |
|
|
由于其年龄，从事务缓冲区中删除的最新带外事务标识符的数组。详情请查看 | |
|
| 带外 事务 列表中当前条目数。 | |
|
| 最近一次事务标识符的数组，已在事务缓冲区中减和回滚。 | |
|
| 最后一次事务缓冲区提交操作的持续时间（以毫秒为单位）。 | |
|
| 最长事务缓冲区提交操作的持续时间（以毫秒为单位）。 | |
|
| 检测到的错误数量。 | |
|
| 检测到的警告数量。 | |
|
|
检查系统更改号以进行改进并保持不变的次数。高的值可能会表示持续运行较长的事务，并阻止连接器清除最近处理的系统更改号到连接器的偏移量。当条件为最佳时，该值应接近或等于 | |
|
|
检测到的 DDL 记录数量，但无法被 DDL 解析器解析。这应该始终为 | |
|
| 当前最小会话的用户全局区域(UGA)内存消耗（以字节为单位）。 | |
|
| 所有 mining 会话的用户全局区域(UGA)内存消耗上限（以字节为单位）。 | |
|
| 当前 mining 会话的进程全局区域(PGA)内存消耗（以字节为单位）。 | |
|
| 所有 mining 会话的进程全局区域(PGA)内存消耗上限（以字节为单位）。 |
2.5.7.4. Debezium Oracle 连接器模式历史记录指标
MBean 为 debezium.oracle:type=connector-metrics,context=schema-history,server= <topic.prefix>。
下表列出了可用的模式历史记录指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
|
| |
|
| 恢复开始的时间（以 epoch 秒为单位）。 | |
|
| 在恢复阶段读取的更改数量。 | |
|
| 恢复和运行时应用的模式更改总数。 | |
|
| 自上次更改从历史记录存储中恢复后经过的毫秒数。 | |
|
| 从上次更改被应用后经过的毫秒数。 | |
|
| 从历史记录存储中恢复最后一次更改的字符串表示。 | |
|
| 最后一次应用更改的字符串表示。 |
2.5.8. Oracle 连接器常见问题
- 是否支持 Oracle 11g？
- 不支持 Oracle 11g，但我们的目标是以尽力为基础与 Oracle 11g 向后兼容。我们依赖社区与 Oracle 11g 沟通兼容性问题，并在识别回归时提供 bug 修复。
- Oracle LogMiner 弃用了吗？
- 否，Oracle 只弃用了 Oracle LogMiner 中的 Oracle LogMiner 选项，并从 Oracle 19c 开始删除该选项。Debezium Oracle 连接器不依赖于这个选项来正常工作，因此可以安全地与较新的 Oracle 版本一起使用，而不影响。
- 如何更改偏移中的位置？
Debezium Oracle 连接器在偏移中维护两个关键值，一个名为
scn的字段，另一个名为commit_scn。scn字段是一个字符串，代表捕获更改时连接器的低水位线开始位置。-
查找包含连接器偏移的主题名称。这根据设为
offset.storage.topic配置属性的值进行配置。 查找连接器的最后偏移量，其下存储了密钥，并确定用于存储偏移的分区。这可以通过 Kafka 代理安装提供的
kafkacat工具脚本完成。一个示例可能类似如下：kafkacat -b localhost -C -t my_connect_offsets -f 'Partition(%p) %k %s\n' Partition(11) ["inventory-connector",{"server":"server1"}] {"scn":"324567897", "commit_scn":"324567897: 0x2832343233323:1"}kafkacat -b localhost -C -t my_connect_offsets -f 'Partition(%p) %k %s\n' Partition(11) ["inventory-connector",{"server":"server1"}] {"scn":"324567897", "commit_scn":"324567897: 0x2832343233323:1"}Copy to Clipboard Copied! Toggle word wrap Toggle overflow inventory-connector的键是["inventory-connector",{"server":"server1"}]，分区是11，最后一个偏移是键跟随的内容。要移回以前的偏移偏移，应停止连接器，必须发出以下命令：
echo '["inventory-connector",{"server":"server1"}]|{"scn":"3245675000","commit_scn":"324567500"}' | \ kafkacat -P -b localhost -t my_connect_offsets -K \| -p 11echo '["inventory-connector",{"server":"server1"}]|{"scn":"3245675000","commit_scn":"324567500"}' | \ kafkacat -P -b localhost -t my_connect_offsets -K \| -p 11Copy to Clipboard Copied! Toggle word wrap Toggle overflow 这会写入 my_connect_offsets 主题的
my_connect_offsets主题的分区11，即给定的键和偏移值。在本例中，我们将连接器重新定向到 SCN3245675000，而不是324567897。
-
查找包含连接器偏移的主题名称。这根据设为
- 如果连接器无法使用给定偏移 SCN 查找日志，会发生什么情况？
Debezium 连接器在连接器偏移中维护低和高水位线 SCN 值。low-watermark SCN 代表起始位置，必须存在于可用的在线红色或存档日志中，以便连接器成功启动。当连接器报告无法找到这个偏移 SCN 时，这表示仍可用的日志不包含 SCN，因此连接器无法从其离开的地方清除更改。
发生这种情况时，有两个选项。第一个是删除连接器的历史记录主题和偏移量，并建议重启连接器。这将保证任何主题消费者都不会发生数据丢失。第二个是手动操作偏移，将 SCN 传播到红色或存档日志中可用的位置。这将导致在旧的 SCN 值和新提供的 SCN 值之间发生的更改丢失，且不会写入主题。不建议这样做。
- 各种 mining 策略之间的区别是什么？
Debezium Oracle 连接器为
log.mining.strategy提供了三个选项。默认为
redo_in_catalog，这指示连接器每次检测到日志交换机时将 Oracle 数据字典写入 redo 日志。Oracle LogMiner 在解析 redo 和 archive 日志时，这个数据字典需要有效跟踪模式更改。这个选项将生成比归档日志的通常数多，但允许捕获的表实时操作，而不影响捕获数据更改。这个选项通常需要更多 Oracle 数据库内存，并且将导致 Oracle LogMiner 会话和进程在每次日志切换后启动稍有更长的时间。第二个选项
online_catalog不会将 data 字典写入 redo 日志。相反，Oracle LogMiner 将始终使用包含表结构当前状态的在线数据字典。这也意味着，如果表的结构更改，并且不再匹配在线数据字典，如果表的结构发生更改，Oracle LogMiner 将无法解析表或列名称。如果捕获的表可能会有频繁的模式更改，则不应使用此 mining 策略选项。务必要确保所有数据更改都用 schema 更改进行锁定，以便所有更改都已从表的日志中捕获，停止连接器，应用 schema 更改，然后重新启动连接器并恢复表上的数据更改。这个选项需要较少的 Oracle 数据库内存和 Oracle LogMiner 会话，通常启动非常快，因为数据字典不需要被 LogMiner 进程加载或主要。最终选项
混合结合了上述两个策略的优点和其弱点。此策略利用了online_catalog的性能，在对redo_in_catalog的模式跟踪方面具有弹性，同时避免了比普通存档日志生成更高的开销和性能成本。这个模式使用回退模式，如果 LogMiner 无法重建数据库更改的 SQL，Debezium 连接器将依赖于连接器维护的内存中模式模型来重建 SQL in-flight。其目的是，此模式最终将转换到默认值，并可能在以后只有操作模式。- 使用 LogMiner 对 Hybrid mining 策略存在任何限制？
-
是的，
log.mining.strategy的 Hybrid 模式仍然是 work-in-progress 策略，因此还不支持所有数据类型。目前，这个模式无法重建 SQL 语句，其中包括针对CLOB、NCLOB、BLOB、XML或JSON数据类型的操作。因此，如果您启用了值为true的lob.enabled，则无法使用混合策略，连接器将无法启动，因为不支持此组合。 - 为什么连接器会出现停止捕获 AWS 上的更改？
由于 AWS 网关负载平衡器上 350 秒的固定空闲超时，需要超过 350 秒的 JDBC 调用可以无限期地挂起。
如果调用 Oracle LogMiner API 完成超过 350 秒时，可能会触发超时，从而导致 AWS 网关负载平衡器挂起。例如，当 LogMiner 会话处理大量数据与 Oracle 的定期检查点任务同时运行时，可能会发生这样的超时。
要防止在 AWS Gateway Load Balancer 上发生超时的情况，请通过以 root 或 super-user 用户身份执行以下步骤来启用来自 Kafka Connect 环境的 keep-alive 数据包：
在终端中运行以下命令：
sysctl -w net.ipv4.tcp_keepalive_time=60
sysctl -w net.ipv4.tcp_keepalive_time=60Copy to Clipboard Copied! Toggle word wrap Toggle overflow 编辑
/etc/sysctl.conf并设置以下变量的值，如下所示：net.ipv4.tcp_keepalive_time=60
net.ipv4.tcp_keepalive_time=60Copy to Clipboard Copied! Toggle word wrap Toggle overflow 重新配置用于 Oracle 连接器的 Debezium 以使用
database.url属性而不是database.hostname，并添加(ENABLE=broken)Oracle 连接字符串描述符，如下例所示：database.url=jdbc:oracle:thin:username/password!@(DESCRIPTION=(ENABLE=broken)(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(Host=hostname)(Port=port)))(CONNECT_DATA=(SERVICE_NAME=serviceName)))
database.url=jdbc:oracle:thin:username/password!@(DESCRIPTION=(ENABLE=broken)(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(Host=hostname)(Port=port)))(CONNECT_DATA=(SERVICE_NAME=serviceName)))Copy to Clipboard Copied! Toggle word wrap Toggle overflow
前面的步骤将 TCP 网络堆栈配置为每 60 秒发送 keep-alive 数据包。因此，当 JDBC 调用 LogMiner API 完成 350 秒时，AWS Gateway Load Balancer 不会超时，使连接器能够继续从数据库事务日志中读取更改。
- ORA-01555 的原因是什么？如何处理它？
Debezium Oracle 连接器在初始快照阶段执行时使用闪存查询。闪存查询是一种特殊的查询类型，它依赖于闪存区域，由数据库的
UNDO_RETENTION数据库参数维护，以根据表的内容在给定时间或给定 SCN 中返回查询的结果。默认情况下，Oracle 通常只维护一个撤消或闪存区域大约 15 分钟，除非数据库管理员已增加或减少。对于捕获大型表的配置，可能需要超过 15 分钟，或者配置了UNDO_RETENTION来执行初始快照，这最终会导致这个例外：ORA-01555: snapshot too old: rollback segment number 12345 with name "_SYSSMU11_1234567890$" too small
ORA-01555: snapshot too old: rollback segment number 12345 with name "_SYSSMU11_1234567890$" too smallCopy to Clipboard Copied! Toggle word wrap Toggle overflow 处理这个例外的第一个方法是与您的数据库管理员合作，并查看它们是否可以临时增加
UNDO_RETENTION数据库参数。这不需要重新启动 Oracle 数据库，因此这可在不影响数据库可用性的情况下在线完成。但是，如果表空间不足以存储所需的撤消数据，则更改可能会导致上述异常或"快照过旧"异常。处理这个异常的第二个方法是根本不依赖于初始快照，将
snapshot.mode设置为schema_only，然后依赖于增量快照。增量快照不依赖于闪存查询，因此不受 ORA-01555 例外的约束。- ORA-04036 的原因是什么？如何进行处理？
当数据库发生经常时，Debebe Oracle 连接器可能会报告 ORA-04036 异常。在检测到日志交换机前，启动并重复使用 Oracle LogMiner 会话。会话被重新使用，因为它提供与 Oracle LogMiner 的最佳性能利用，但如果发生长时间运行的 mining 会话，这可能会导致过量 PGA 内存用量，最终导致例外：
ORA-04036: PGA memory used by the instance exceeds PGA_AGGREGATE_LIMIT
ORA-04036: PGA memory used by the instance exceeds PGA_AGGREGATE_LIMITCopy to Clipboard Copied! Toggle word wrap Toggle overflow 通过指定 Oracle 交换机红色日志的频率或 Debezium Oracle 连接器可以重新使用 mining 会话来避免这个例外。Debezium Oracle 连接器提供了一个配置选项
log.mining.session.max.ms，它控制当前 Oracle LogMiner 会话在关闭和启动新会话的时长。这允许在不超过数据库允许的 PGA 内存的情况下保留数据库资源。- ORA-01882 的原因是什么，以及如何处理它？
Debezium Oracle 连接器在连接到 Oracle 数据库时可能会报告以下异常：
ORA-01882: timezone region not found
ORA-01882: timezone region not foundCopy to Clipboard Copied! Toggle word wrap Toggle overflow 当时区信息无法被 JDBC 驱动程序正确解析时，会出现这种情况。为了解决这个问题，需要告知驱动程序无法使用区域解析时区详情。这可以通过使用 driver.
oracle.jdbc.timezoneAsRegion=false 指定驱动程序pass through 属性来实现。- ORA-25191 和如何处理它的原因是什么？
Debezium Oracle 连接器会自动忽略 index-organized 表(IOT)，因为 Oracle LogMiner 不支持它们。但是，如果抛出 ORA-25191 异常，这可能是由于映射的唯一情况，并且可能需要额外规则来自动排除这些。ORA-25191 异常示例可能类似如下：
ORA-25191: cannot reference overflow table of an index-organized table
ORA-25191: cannot reference overflow table of an index-organized tableCopy to Clipboard Copied! Toggle word wrap Toggle overflow 如果抛出 ORA-25191 异常，请引发 JIRA 问题，以及表及其与其他父表相关的映射等。作为临时解决方案，可以调整 include/exclude 配置选项，以防止连接器访问这些表。
- 如何解决 SAX 功能外部识别 - 不支持
-
Debezium 2.4 引入了对 Oracle 的
XMLTYPE列类型的支持，并支持此功能，需要 Oraclexdb和xmlparserv2依赖项。
Oracle 的xmlparserv2依赖项实现了基于 SAX 的解析器，如果运行时发现使用了这个实现的解析程序，则在 classpath 上会发生这个错误。为了影响一般使用 SAX 的实施，需要以特定参数启动 JVM。
提供以下 JVM 参数后，Oracle 连接器将成功启动，而不会出现这个错误。
-Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
-Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl2.6. PostgreSQL 的 Debezium 连接器
Debezium PostgreSQL 连接器捕获 PostgreSQL 数据库模式中的行级更改。有关与连接器兼容的 PostgreSQL 版本的详情，请参考 Debezium 支持的配置 页面。
第一次连接到 PostgreSQL 服务器或集群时，连接器会获取所有模式的一致性快照。完成该快照后，连接器会持续捕获行级更改，这些更改插入、更新和删除数据库内容，并提交到 PostgreSQL 数据库。连接器生成数据更改事件记录，并将其流传输到 Kafka 主题。对于每个表，默认行为是连接器将所有生成的事件流传输到该表的独立 Kafka 主题。应用程序和服务消耗来自该主题的数据更改事件记录。
使用 Debezium PostgreSQL 连接器的信息和流程组织如下：
- 第 2.6.1 节 “Debezium PostgreSQL 连接器概述”
- 第 2.6.2 节 “Debezium PostgreSQL 连接器如何工作”
- 第 2.6.3 节 “Debezium PostgreSQL 连接器数据更改事件的描述”
- 第 2.6.4 节 “Debezium PostgreSQL 连接器如何映射数据类型”
- 第 2.6.5 节 “设置 PostgreSQL 以运行 Debezium 连接器”
- 自定义转换器
- 第 2.6.6 节 “部署 Debezium PostgreSQL 连接器”
- 第 2.6.7 节 “监控 Debezium PostgreSQL 连接器性能”
- 第 2.6.8 节 “Debezium PostgreSQL 连接器如何处理错误和问题”
2.6.1. Debezium PostgreSQL 连接器概述
PostgreSQL 的逻辑解码 功能是在版本 9.4 中引入的。是一种机制，允许提取提交至事务日志的更改，以及通过 输出插件 以用户友好的方式处理这些更改。输出插件可让客户端消耗更改。
PostgreSQL 连接器包含两个主要部分，它们一起用于读取和处理数据库更改：
连接器会为捕获的每行级别的插入、更新和删除操作生成更改事件，并在单独的 Kafka 主题中为每个表发送更改事件记录。客户端应用程序读取与感兴趣的数据库表对应的 Kafka 主题，并可对这些主题收到的每行事件做出反应。
PostgreSQL 通常会在一段时间后清除 write-ahead 日志(WAL)片段。这意味着连接器没有对数据库所做的任何更改的完整历史记录。因此，当 PostgreSQL 连接器首先连接到特定的 PostgreSQL 数据库时，它会首先执行每个数据库模式 的一致性快照。连接器完成快照后，它会继续从创建快照的确切点中流传输更改。这样，连接器会以所有数据的一致性视图开始，且不会省略拍摄快照时所做的任何更改。
连接器可以接受失败。当连接器读取更改并生成事件时，它会记录每个事件的 WAL 位置。如果连接器因任何原因（包括通信失败、网络问题或崩溃）停止，重启连接器将继续读取最后一个关闭的 WAL。这包括快照。如果连接器在快照过程中停止，连接器会在重启时启动新的快照。
连接器依赖于并反映 PostgreSQL 逻辑解码功能，它有以下限制：
- 逻辑解码不支持 DDL 更改。这意味着连接器无法向消费者报告 DDL 更改事件。
-
只在主服务器上支持逻辑解码复制
插槽。当有 PostgreSQL 服务器的集群时，连接器只能在活跃的主服务器中运行。它不能在热或温备用副本上运行。如果主服务器失败或降级，连接器将停止。在主服务器恢复后，您可以重启连接器。如果不同的 PostgreSQL 服务器已提升到主，请在重启连接器前调整连接器配置。 - 因为逻辑解码复制插槽在 commit swig- swigand not post commit swig-wagonundesirable side-effects 过程中发布更改。当客户端可能会观察不一致的状态时，有两个主要场景。首先，在复制前的 master 结束时发布未提交的更改。其次，发布无法临时读取的更改（例如，读写一致性），因为它们正在复制。例如，EmbeddedEngine 使用者收到创建的行通知，但它不能被事务读取。
另外，pgoutput 逻辑解码输出插件不会捕获生成的列的值，从而导致连接器输出中缺少这些列的数据。
发生错误时的行为 描述了连接器如何响应是否有问题。
Debezium 目前仅支持使用 UTF-8 字符编码的数据库。使用单字节字符编码时，无法正确处理包含扩展 ASCII 代码字符的字符串。
2.6.2. Debezium PostgreSQL 连接器如何工作
要优化地配置和运行 Debezium PostgreSQL 连接器，了解连接器如何执行快照、流更改事件、决定 Kafka 主题名称并使用元数据。
详情包括在以下主题中：
2.6.2.1. PostgreSQL 连接器的安全性
要使用 Debezium 连接器从 PostgreSQL 数据库流传输更改，连接器必须使用数据库中的特定权限操作。虽然授予所需的特权的一种方法是为用户授予 超级用户特权，但这样做可能会将您的 PostgreSQL 数据暴露给未经授权的访问权限。最好创建一个专用的 Debezium 复制用户，而不是为 Debezium 用户授予特权。
有关为 Debezium PostgreSQL 用户配置 权限的更多信息，请参阅设置权限。有关 PostgreSQL 逻辑复制安全性的更多信息，请参阅 PostgreSQL 文档。
2.6.2.2. Debezium PostgreSQL 连接器如何执行数据库快照
大多数 PostgreSQL 服务器配置为不会在 WAL 段中保留数据库的完整历史记录。这意味着 PostgreSQL 连接器无法通过只读取 WAL 来查看数据库的完整历史记录。因此，当连接器首次启动时，它会执行数据库的初始 一致的快照。
您可以在以下部分中找到有关快照的更多信息：
初始快照的默认工作流行为
执行快照的默认行为由以下步骤组成。您可以通过将 snapshot.mode 连接器配置属性设置为 初始 的值来更改此行为。
-
使用 SERIALIZABLE, READ ONLY, DEFERRABLE 隔离级别启动事务，以确保此事务中的后续读取针对单一数据版本。由于后续
INSERT、UPDATE和DELETE操作的原因，对数据的任何更改都无法在此事务中可见。 - 阅读服务器事务日志中的当前位置。
-
扫描数据库表和模式，为每个行生成一个
READ事件，并将该事件写入适当的表特定的 Kafka 主题。 - 提交事务。
- 在连接器偏移中记录快照成功完成。
如果连接器失败，会在步骤 1 开始后重新平衡或停止，但在重启连接器开始新快照前。连接器完成其初始快照后，PostgreSQL 连接器将继续从第 2 步中读取的位置流。这样可确保连接器不会丢失任何更新。如果连接器因任何原因再次停止，则连接器将继续从之前离开的位置流传输更改。
| 选项 | 描述 |
|---|---|
|
|
连接器在启动时始终执行快照。快照完成后，连接器将继续从上述序列中的步骤 3 中流传输更改。这个模式在以下情况下很有用：
|
|
| 当没有 Kafka offsets 主题时，连接器会执行数据库快照。数据库快照完成后，将写入 Kafka 偏移主题。如果 Kafka offsets 主题中存在之前存储的 LSN，则连接器将继续从该位置流更改。 |
|
| 连接器执行数据库快照并在流传输任何更改事件记录前停止。如果连接器已启动，但没有在停止前完成快照，则连接器会重启快照过程，并在快照完成后停止。 |
|
| 连接器永远不会执行快照。当以这种方式配置连接器时，启动后，它的行为如下： 如果 Kafka offsets 主题中存在之前存储的 LSN，则连接器将继续从该位置流更改。如果没有存储 LSN，则连接器从服务器上创建 PostgreSQL 逻辑复制插槽的时间点开始流更改。只有在您知道所有感兴趣的数据仍然反映在 WAL 中时，才使用此快照模式。 |
|
|
弃用，请参阅 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
2.6.2.3. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供总结表数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改为捕获不同的表集合。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号表。您可以通过向 Debezium 信号表发送信号请求来启动临时快照。
当您启动现有表的临时快照时，连接器会将内容附加到表已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的表。快照可以捕获数据库的全部内容，或者仅捕获数据库中表的子集。此外，快照也可捕获数据库中表的内容的子集。
您可以通过向信号表发送 execute-snapshot 消息来指定要捕获的表。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的表名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| N/A |
包含与快照中包含的表的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作表的主键的列名称。 |
触发临时增量快照
您可以通过向信号表添加带有 execute-snapshot 信号类型的条目，或者向 Kafka 信号发送信号消息 来启动临时增量快照。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个表的开始和端点。根据表中的条目数量以及配置的块大小，Debezium 会将表分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号表或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.6.2.4. 增量快照
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个表。您可以指定您希望快照捕获的表 以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debezium 使用水位线来跟踪其进度，维护其捕获的每个表行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获表。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，以将表添加到其
table.include.list属性中。
增量快照过程
当您运行增量快照时，Debezium 按主密钥对每个表进行排序，然后根据 配置的块大小 将表分成块。通过块工作的块，然后捕获块中的每个表行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改表记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获了包含该行的 READ 事件前修改表行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一表行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定表块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到表的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
PostgreSQL 的 Debezium 连接器不支持增量快照运行时的 schema 更改。如果在增量快照启动前执行 schema 更改，但在以后发送信号，passthrough 配置选项 database.autosave 被设置为 conservative 以正确处理 schema 的更改。
2.6.2.4.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号表。您可以提交快照信号，作为 SQL INSERT 查询。
在 Debezium 检测到信号表中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的表，并可选择性地指定快照操作的类型。Debezium 目前支持 增量 和 阻塞 快照类型。
要指定要包含在快照中的表，提供一个列出表的 data-collections 数组，或用于匹配表的正则表达式数组，例如：
{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会解释空数组，意味着不需要任何操作，且不会执行快照。
如果要包含在快照中的表的名称包含一个点(.)、空格或其它非字母数字字符，则必须使用双引号转义表名称。
例如，要包含 公共 模式中存在的表，并且名为 My.Table，请使用以下格式 ："public.\"My.Table\" "。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
发送 SQL 查询，将临时增量快照请求添加到信号表中：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、type和data参数的值 与信号表的字段 相对应。
下表描述了示例中的参数：Expand 表 2.129. SQL 命令中的字段描述，用于将增量快照信号发送到信号表 项 值 描述 1
schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshottype参数指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定表名称或正则表达式数组，以匹配快照中包含的表名称。
数组列出了使用格式schema.table的正则表达式，以匹配表的完全限定名称。此格式与您用来指定连接器 信号表的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
有效值为incremental和blocking值。
如果没有指定值，连接器默认为执行增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
每个额外条件都是带有data-collection和filter属性的对象。您可以为每个数据收集指定不同的过滤器。
请参阅data-collection属性是过滤器应用到的数据收集的完全限定域名。有关additional-conditions参数的详情，请参考 第 2.6.2.4.2 节 “使用附加条件运行临时增量快照”。
2.6.2.4.2. 使用附加 条件运行临时增量快照
如果您希望快照只在表中包括内容子集，您可以通过将 additional-conditions 参数附加到快照信号来修改信号请求。
对典型快照的 SQL 查询采用以下格式：
SELECT * FROM <tableName> ....
SELECT * FROM <tableName> ....
通过添加 additional-conditions 参数，您可以在 SQL 查询中附加 WHERE 条件，如下例所示：
SELECT * FROM <data-collection> WHERE <filter> ....
SELECT * FROM <data-collection> WHERE <filter> ....以下示例显示了向信号表发送带有额外条件的临时增量快照请求的 SQL 查询：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
例如，假设您有一个包含以下列的 products 表：
-
ID（主密钥） -
color -
quantity
如果您需要 product 表的增量快照，其中只包含 color=blue 的数据项，您可以使用以下 SQL 语句来触发快照：
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue"}]}');
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue"}]}');
additional-conditions 参数还允许您传递基于多个列的条件。例如，使用上例中的 product 表，您可以提交查询来触发增量快照，该快照仅包含 color=blue 和 quantity>10 的项数据：
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue AND quantity>10"}]}');
INSERT INTO myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "schema1.products", "filter": "color=blue AND quantity>10"}]}');以下示例显示了连接器捕获的增量快照事件的 JSON。
例 2.40. 增量快照事件消息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.6.2.4.3. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.41. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择表内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果一个带有列 ID （主键）、颜色 和品牌 的 products 表，如果您希望快照只包含 color='blue' 的内容，当请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 product 表，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的 表中的内容，您可以发送以下请求：
products
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.6.2.4.4. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的信号发送信号来停止已经运行的快照。
您可以通过在 SQL INSERT 查询中发送停止快照信号，向信号表提交停止快照信号。stop-snapshot 信号将快照操作的类型指定为 增量，并选择性地指定要从当前运行的快照中省略的表。在 Debezium 检测到信号表中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
发送 SQL 查询以停止临时增量快照到信号表：
INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
INSERT INTO myschema.debezium_signal (id, type, data) values ('ad-hoc-1', 'stop-snapshot', '{"data-collections": ["schema1.table1", "schema1.table2"], "type":"incremental"}');INSERT INTO myschema.debezium_signal (id, type, data)1 values ('ad-hoc-1',2 'stop-snapshot',3 '{"data-collections": ["schema1.table1", "schema1.table2"],4 "type":"incremental"}');5 Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号表的字段相对应。
下表描述了示例中的参数：Expand 表 2.132. SQL 命令中的字段描述，用于将停止增量快照信号发送到信号表 项 值 描述 1
schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。3
stop-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定表名称或正则表达式数组，以匹配要从快照中删除的表名称。
数组以schema.table格式按完全限定名称匹配表的正则表达式如果您从
data字段省略这个组件，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.6.2.4.5. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，表名称或正则表达式，以匹配要从快照中删除的表名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["schema1.table1", "schema1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["schema1.table1", "schema1.table2"], "type": "INCREMENTAL"}}`2.6.2.5. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新表，并在连接器运行时完成快照。
- 您可以添加大表，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个表必须是快照
additional-conditions ：您可以为不同的表指定不同的过滤器。
-
data-collection属性是要应用过滤器的表的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.6.2.6. Debezium PostgreSQL 连接器如何更改事件记录
PostgreSQL 连接器通常会花费大量时间从它连接到的 PostgreSQL 服务器流更改。这种机制依赖于 PostgreSQL 的复制协议。此协议使客户端能够接收服务器在服务器事务日志中提交的更改（在某些位置上，称为 Log Sequence Numbers (LSN)）。
每当服务器提交事务时，单独的服务器进程都会调用来自 逻辑解码插件的回调功能。此功能处理事务的更改，将它们转换为特定格式（在 Debezium 插件中是Protobuf 或 JSON），并将它们写到输出流中，然后供客户端使用。
Debezium PostgreSQL 连接器充当 PostgreSQL 客户端。当连接器收到更改时，它会将事件转换为 Debezium 的 create, update, 或 delete 事件，包含该事件的 LSN 的事件。PostgreSQL 连接器将记录中的这些更改事件转发到 Kafka Connect 框架，该框架在同一进程中运行。Kafka Connect 进程异步写入更改事件记录，它们生成的顺序与正确的 Kafka 主题相同。
定期，Kafka Connect 会定期记录另一个 Kafka 主题中最新的偏移量。offset 表示 Debezium 包括每个事件的源特定位置信息。对于 PostgreSQL 连接器，在每个更改事件中记录的 LSN 是偏移量。
当 Kafka Connect 正常关闭时，它会停止连接器，将所有事件记录刷新到 Kafka，并记录从每个连接器接收的最后偏移量。当 Kafka Connect 重启时，它会读取每个连接器的最后记录偏移，并在最后记录的偏移处启动每个连接器。当连接器重启时，它会向 PostgreSQL 服务器发送请求，以发送仅在该位置后启动的事件。
PostgreSQL 连接器检索模式信息，作为逻辑解码插件发送的事件的一部分。但是，连接器不会检索关于哪些列组成主密钥的信息。连接器从 JDBC 元数据（侧频道）获取此信息。如果表的主键定义有变化（通过添加、删除或重命名主键列），当 JDBC 的主密钥信息没有与逻辑解码插件生成的更改事件同步时，会有一个小的时间段。在此小期内，可以以不一致的关键结构创建消息。要防止这种不一致，请更新主密钥结构，如下所示：
- 将数据库或应用程序置于只读模式。
- 让 Debezium 处理所有剩余的事件。
- 停止 Debezium。
- 更新相关表中的主密钥定义。
- 将数据库或应用程序置于读/写模式。
- 重启 Debezium。
PostgreSQL 10+ 逻辑解码支持(pgoutput)
从 PostgreSQL 10+ 开始，有一个逻辑复制流模式，称为 pgoutput，它被 PostgreSQL 原生支持。这意味着 Debezium PostgreSQL 连接器可以使用该复制流，而无需额外的插件。这在不支持或不允许安装插件的环境中特别有用。
如需更多信息，请参阅设置 PostgreSQL。
2.6.2.7. 接收 Debezium PostgreSQL 更改事件记录的 Kafka 主题的默认名称
默认情况下，PostgreSQL 连接器将所有 INSERT、UPDATE 和 DELETE 操作的更改事件写入一个特定于该表的单个 Apache Kafka 主题。连接器使用以下惯例命名更改事件主题：
topicPrefix.schemaName.tableName
以下列表提供了默认名称组件的定义：
- topicPrefix
-
由
topic.prefix配置属性指定的主题前缀。 - schemaName
- 发生更改事件的数据库架构的名称。
- tableName
- 发生更改事件的数据库表的名称。
例如，假设 fulfillment 是连接器中的逻辑服务器名称，该连接器捕获 PostgreSQL 安装中的更改，该安装具有一个 postgres 数据库和一个 inventory schem，它包含四个表：products, products_on_hand, customers, 和 orders连接器会将记录流传输到这四个 Kafka 主题：
-
fulfillment.inventory.products -
fulfillment.inventory.products_on_hand -
fulfillment.inventory.customers -
fulfillment.inventory.orders
现在，假设表不是特定模式的一部分，但在默认的 公共 PostgreSQL 模式中创建。Kafka 主题的名称将是：
-
fulfillment.public.products -
fulfillment.public.products_on_hand -
fulfillment.public.customers -
fulfillment.public.orders
连接器应用类似的命名约定来标记其 事务元数据主题。
如果默认主题名称不满足您的要求，您可以配置自定义主题名称。要配置自定义主题名称，您可以在逻辑主题路由 SMT 中指定正则表达式。有关使用逻辑主题路由 SMT 自定义主题命名的更多信息，请参阅 主题路由。
2.6.2.8. Debezium PostgreSQL 连接器生成的事件代表事务边界
Debezium 可以生成代表事务边界的事件，以及丰富的数据更改事件消息。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
对于每个事务 BEGIN 和 END，Debebe 会生成一个包含以下字段的事件：
status-
BEGIN或END. id-
由 Postgres 事务 ID 本身和以冒号分隔的给定操作的 LSN 组成的唯一事务标识符的字符串，即格式是
txID:LSN。 ts_ms-
数据源的事务边界事件(
BEGIN或END事件)的时间。如果数据源没有向 Debezium 提供事件时间，则字段代表 Debezium 处理事件的时间。 event_count（用于END事件）- 事务处理的事件总数。
data_collections（用于END事件）-
一组
data_collection和event_count元素，用于指示连接器为来自数据收集的更改发出的事件数。
示例
除非通过 topic.transaction 选项覆盖，否则事务事件将写入名为 <topic. prefix>。
.transaction 的主题
更改数据事件增强
当启用事务元数据时，数据消息 Envelope 会增加新的 transaction 字段。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示。
total_order- 事件在事务生成的所有事件间的绝对位置。
data_collection_order- 事件在事务发送的所有事件中的每个数据收集位置。
以下是消息示例：
2.6.3. Debezium PostgreSQL 连接器数据更改事件的描述
Debezium PostgreSQL 连接器为每个行级 INSERT、UPDATE 和 DELETE 操作生成数据更改事件。每个事件包含一个键和值。键和值的结构取决于更改的表。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，用户很难处理。要解决这个问题，每个事件都包含其内容的 schema，或者如果您使用 schema registry，消费者可以用来从 registry 获取 schema 的模式 ID。这使得每个事件自包含。
以下框架 JSON 显示了更改事件的基本四部分。但是，如何配置您选择在应用程序中使用的 Kafka Connect 转换器决定了更改事件中的这四个部分的表示。只有在将转换器配置为生成它时，schema 字段才会处于 change 事件中。同样，只有在将转换器配置为生成它时，事件键和事件有效负载才会处于更改事件中。如果您使用 JSON 转换程序，并将其配置为生成所有四个基本更改事件部分，则更改事件具有此结构：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
第一个 |
| 2 |
|
第一个 |
| 3 |
|
第二个 |
| 4 |
|
第二个 |
默认情况下，连接器流将 事件记录更改为使用与事件原始表相同的名称的主题。
从 Kafka 0.10 开始，Kafka 可以选择使用创建消息 的时间戳 记录事件键和值（由制作者记录），或者由 Kafka 写入日志。
PostgreSQL 连接器确保所有 Kafka Connect 模式名称遵循 Avro 模式名称格式。这意味着逻辑服务器名称必须以拉丁字母或下划线开头，即 a-z、A-Z 或 _。逻辑服务器名称和模式和表名称中的每个字符都必须是拉丁字母、数字或下划线，即 a-z、A-Z、0-9 或 \_。如果存在无效的字符，它将被一个下划线字符替代。
如果逻辑服务器名称、模式名称或表名称包含无效字符，则这可能会导致意外冲突，并且区分名称的唯一字符无效，因此用下划线替换。
详情包括在以下主题中：
2.6.3.1. 关于 Debezium PostgreSQL 更改事件中的键
对于给定表，更改事件的键有一个结构，它在表创建时包含每个列的字段。或者，如果表将 REPLICA IDENTITY 设置为 FULL 或 USING INDEX，则每个唯一键约束都有一个字段。
考虑在 公共 数据库架构中定义的 customers 表，以及该表的更改事件密钥示例。
表示例
更改事件键示例
如果 topic.prefix 连接器配置属性的值 PostgreSQL_server，则 customers 表的每个更改事件都具有相同的关键结构，在 JSON 中如下所示：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
键的 schema 部分指定一个 Kafka Connect 模式，它描述了键的 |
| 2 |
|
定义键有效负载结构的 schema 名称。这个模式描述了更改的表的主密钥的结构。Key 模式名称的格式是 connector-name.database-name.table-name.
|
| 3 |
|
指明事件键是否在其 |
| 4 |
|
指定 |
| 5 |
|
包含生成此更改事件的行的密钥。在本例中，键包含一个 |
虽然 column.exclude.list 和 column.include.list 连接器配置属性允许您只捕获表列的子集，但主键或唯一键中的所有列始终包含在事件的密钥中。
如果表没有主键或唯一键，则更改事件的键为 null。没有主键约束或唯一键约束的表中的行无法唯一标识。
2.6.3.2. 关于 Debezium PostgreSQL 更改事件中的值
更改事件中的值比键复杂一些。与键一样，值也有一个 schema 部分和一个 payload 部分。schema 部分包含描述 payload 部分的 Envelope 结构的 schema，包括其嵌套字段。更改创建、更新或删除数据的操作的事件，它们都有带有 envelope 结构的值 payload。
考虑用于显示更改事件键示例相同的示例表：
更改此表的更改事件的值部分因 REPLICA IDENTITY 设置和事件所针对的操作而异。
以下部分详情如下：
副本身份
REPLICA IDENTITY 是一个特定于 PostgreSQL 的表级设置，它决定了逻辑解码插件可用于 UPDATE 和 DELETE 事件的信息量。更具体地说，设置 REPLICA IDENTITY 控制在发生 UPDATE 或 DELETE 事件时所涉及的表列前面的值（若有）信息。
REPLICA IDENTITY 有 4 个可能的值：
DEFAULT- 默认行为是，如果该表有一个主键，则UPDATE和DELETE事件包含表的主键列前面的值。对于UPDATE事件，只有带有更改值的主键列才会显示。如果表没有主键，连接器不会为该表发出
UPDATE或DELETE事件。对于没有主键的表，连接器只发出 创建事件。通常，使用没有主键的表将消息附加到表的末尾，这意味着UPDATE和DELETE事件不可用。-
NOTHING- Emitted 事件用于UPDATE和DELETE操作，不包含任何表列之前值的信息。 -
FULL- Emitted 事件用于UPDATE和DELETE操作，包含表中所有列的以前的值。 -
INDEXindex-name - Emitted 事件用于UPDATE和DELETE操作，包含指定索引中包含的列的先前值。UPDATE事件还包含带有更新值的索引列。
创建 事件
以下示例显示了一个更改事件的值部分，连接器为在 customer 表中创建数据的操作生成的更改事件的值部分：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 值的 schema，它描述了值有效负载的结构。在连接器为特定表生成的更改事件时，更改事件的值 schema 都相同。 |
| 2 |
|
在 |
| 3 |
|
|
| 4 |
|
|
| 5 |
|
值的实际数据。这是更改事件提供的信息。 |
| 6 |
|
指定事件发生前行状态的可选字段。当 注意
此字段是否可用是否取决于每个表的 |
| 7 |
|
指定事件发生后行状态的可选字段。在本例中， |
| 8 |
| 描述事件源元数据的强制字段。此字段包含可用于将此事件与其他事件进行比较的信息，以及事件的来源、发生事件的顺序以及事件是否是同一事务的一部分。源元数据包括：
|
| 9 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中，
|
| 10 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新 事件
示例 customers 表中一个更新的改变事件的值有与那个表的 create 事件相同的模式。同样，事件值的有效负载具有相同的结构。但是，事件值 payload 在更新 事件中包含不同的值。以下是当连接器在 customers 表中为更新生成的更改事件值的示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
可选字段，其中包含数据库提交前所在行中的值。在本例中，仅存在主键列
对于一个 更新 事件，要包含行中的所有列的先前值，您必须通过运行 |
| 2 |
|
指定事件发生后行状态的可选字段。在本例中， |
| 3 |
|
描述事件源元数据的强制字段。
|
| 4 |
|
描述操作类型的强制字符串。在 update 事件值中， |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新行主/唯一键的列会更改行键的值。当密钥更改时，Debezium 会输出 三个 事件：一个 DELETE 事件和一个带有行的旧键的 tombstone 事件，后跟一行的新键的事件。详情位于下一节中。
主密钥更新
更改行的主键字段的 UPDATE 操作被称为主键更改。对于主键更改，为了发送 UPDATE 事件记录，连接器会为旧键发送 DELETE 事件记录，并为新的(updated)密钥发送 CREATE 事件记录。这些事件具有常见的结构和内容，另外，每个事件都有一个与主键更改相关的消息标头：
-
DELETE事件记录具有__debezium.newkey作为消息标头。此标头的值是更新行的新主键。 -
CREATE事件记录具有__debezium.oldkey作为消息标头。此标头的值是更新行具有的上一个（折叠）主键。
删除 事件
delete 更改事件中的值与为同一表的 create 和 update 事件相同的 schema 部分。示例 customer 表的 delete 事件中 payload 部分类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行的状态的可选字段。在一个 delete 事件值中， |
| 2 |
|
可选字段，用于指定事件发生后行的状态。在一个 delete 事件值中， |
| 3 |
|
描述事件源元数据的强制字段。在一个 delete 事件值中，
|
| 4 |
|
描述操作类型的强制字符串。 |
| 5 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
删除 更改事件记录为消费者提供处理删除此行所需的信息。
要让消费者处理为没有主键的表生成的 删除 事件，请将表的 REPLICA IDENTITY 设置为 FULL。当表没有主键且表的 REPLICA IDENTITY 设置为 DEFAULT 或 NOTHING 时，删除 事件没有 before 字段。
PostgreSQL 连接器事件设计为使用 Kafka 日志压缩。日志压缩支持删除一些旧的信息，只要至少保留每个密钥的最新消息。这可让 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
tombstone 事件
删除行时，delete 事件值仍可用于日志压缩，因为 Kafka 您可以删除具有相同键的所有之前信息。但是，为了使 Kafka 删除具有相同键的所有信息，消息值必须是 null。为了实现此目的，PostgreSQL 连接器遵循一个 delete 事件，其中包含一个特殊的tombstone 事件，它有相同的键但值为 null。
截断 事件
truncate 更改事件信号，提示表已被截断。message 键在本例中是 null，消息值类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述事件源元数据的强制字段。在 truncate 事件值中，
|
| 2 |
|
描述操作类型的强制字符串。 |
| 3 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
如果单个 TRUNCATE 语句应用到多个表，则会为每个删节的表发出一个 truncate 更改事件记录。
请注意，由于 truncate 事件代表对整个表所做的更改，并且没有消息键，除非您与单个分区的主题合作，否则对与表相关的更改事件(创建、更新、等 )和 截断 事件没有排序保证。例如，当这些事件从不同的分区读取时，消费者只能在该表的 truncate 事件后收到 update 事件。
此事件类型仅通过 Postgres 14+ 上的 pgoutput 插件支持(Postgres 文档)
一个 消息 事件提示，一个通用逻辑解码消息已被直接插入到 WAL 中，通常使用 pg_logical_emit_message 函数。message 键是 Struct，在本例中带有一个名为 prefix 的单个字段，执行插入消息时指定的前缀。message 值类似于用于事务消息：
与其他事件类型不同，非事务消息将没有任何关联的 BEGIN 或 END 事务事件。message 值与非事务信息类似：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
描述事件源元数据的强制字段。在 message 事件值中，
|
| 2 |
|
描述操作类型的强制字符串。 |
| 3 |
|
显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。
对于非事务 消息 事件， |
| 4 |
| 包含消息元数据的字段
|
2.6.4. Debezium PostgreSQL 连接器如何映射数据类型
PostgreSQL 连接器代表对带有类似行表的事件行的更改。事件包含每个列值的一个字段。事件中的该值取决于列的 PostgreSQL 数据类型。以下小节描述了连接器如何将 PostgreSQL 数据类型映射到 字面类型和 semantic 类型 （在 event 字段中）。
-
literal type 代表值如何被代表，使用 Kafka Connect schema 类型：
INT8,INT16,INT32,INT64,FLOAT32,FLOAT64,BOOLEAN,STRING,BYTES,ARRAY,MAP, 和STRUCT。 - 语义类型 描述了 Kafka Connect 模式如何使用字段名称来捕获字段 的含义。
如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。
详情包括在以下部分中：
基本类型
下表描述了连接器如何映射基本类型。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
|
|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
n/a |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
N/a |
|
|
|
N/a |
|
|
|
N/a |
|
|
|
n/a |
|
|
|
n/a |
|
|
|
n/a |
|
|
|
|
临时类型
除了 PostgreSQL 的 TIMESTAMPTZ 和 TIMETZ 数据类型，它们包含时区信息，临时类型如何映射取决于 time.precision.mode 连接器配置属性的值。以下小节描述了这些映射：
time.precision.mode=adaptive
当 time.precision.mode 属性设为 adaptive 时，默认连接器根据列的数据类型定义决定字面类型和语义类型。这样可确保事件 准确 表示数据库中的值。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
time.precision.mode=adaptive_time_microseconds
当 time.precision.mode 配置属性设置为 adaptive_time_microseconds 时，连接器根据列的数据类型决定 temporal 类型的字面类型和语义类型。这样可确保事件 准确 表示数据库中的值，但所有 TIME 字段都捕获为微秒。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
time.precision.mode=connect
当 time.precision.mode 配置属性设置为 connect 时，连接器使用 Kafka Connect 逻辑类型。当消费者只能处理内置的 Kafka Connect 逻辑类型，且无法处理变量精度时间值时，这很有用。但是，由于 PostgreSQL 支持 microsecond 精度，因此由带有 connect 时间精度模式的连接器 生成的事件会在 数据库列具有大于 3 的 fractional second 精度 值时丢失。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
TIMESTAMP 类型
TIMESTAMP 类型代表一个没有时区信息的时间戳。这些列根据 UTC 转换为等同的 Kafka Connect 值。例如，当 time.precision.mode 没有设置为 connect 时，TIMESTAMP 值 "2018-06-20 15:13:16.945104" 由一个带有值 "1529507596945104" 的 io.debezium.time.MicroTimestamp 代表。
运行 Kafka Connect 和 Debezium 的 JVM 时区不会影响此转换。
PostgreSQL 支持在 TIMESTAMP 列中使用 +/-infinite 值。这些特殊的值转换为时间戳，在正无限循环的情况下值为 9223372036825200000，在负无限循环的情况值为 -9223372036832400000。此行为模拟 PostgreSQL JDBC 驱动程序的标准行为。如需更多信息，请参阅 org.postgresql.PGStatement 接口。
十进制类型
PostgreSQL 连接器配置属性 decimal.handling.mode 的设置决定了连接器如何映射十进制类型。
当将 decimal.handling.mode 属性设为 precise 时，连接器使用 Kafka Connect org.apache.kafka.connect.data.Decimal logical type for all DECIMAL,NUMERIC 和 MONEY 列。这是默认的模式。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
此规则存在例外情况。当在没有扩展限制的情况下使用 NUMERIC 或 DECIMAL 类型时，来自数据库的值会为每个值有不同的(variable)扩展。在这种情况下，连接器使用 io.debezium.data.VariableScaleDecimal，其中包含值和传输值的规模。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
当将 decimal.handling.mode 属性设置为 double 时，连接器表示所有 DECIMAL、NUMERIC 和 MONEY 值作为 Java double 值，并根据下表所示进行编码。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型（架构名称） |
|---|---|---|
|
|
| |
|
|
| |
|
|
|
decimal.handling.mode 配置属性的最后可能的设置 是字符串。在这种情况下，连接器代表 DECIMAL,NUMERIC 和 MONEY 值作为其格式化的字符串表示，并对它们进行编码，如下表中所示。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型（架构名称） |
|---|---|---|
|
|
| |
|
|
| |
|
|
|
当 decimal.handling.mode 为 string 或 double 时，PostgreSQL 支持将 NaN （不是数字）作为存储在 DECIMAL/NUMERIC 值中的特殊值。在这种情况下，连接器将 NaN 编码为 Double.NaN 或字符串常量 NAN。
HSTORE 类型
PostgreSQL 连接器配置属性 hstore.handling.mode 的设置决定了连接器如何映射 HSTORE 值。
当 hstore.handling.mode 属性设为 json （默认值）时，连接器代表 HSTORE 值作为 JSON 值的字符串表示，并对它们进行编码，如下表所示。当 hstore.handling.mode 属性设为 map 时，连接器将 MAP 模式类型用于 HSTORE 值。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
n/a |
域类型
PostgreSQL 支持用户定义的类型，这些类型基于其他底层类型。当使用此类列类型时，Debebe 根据完整的类型层次结构公开列的表示。
捕获使用 PostgreSQL 域类型的列中的更改需要特殊考虑。当定义列使其包含扩展其中一个默认数据库类型的域类型并且域类型定义了自定义长度或扩展时，生成的模式会继承定义的长度或扩展。
当定义列使其包含扩展另一个域类型的域类型时，生成的模式 不会继承 定义的长度或扩展，因为该信息在 PostgreSQL 驱动程序列元数据中不可用。
网络地址类型
PostgreSQL 具有可存储 IPv4、IPv6 和 MAC 地址的数据类型。最好使用这些类型而不是纯文本类型来存储网络地址。网络地址类型提供输入错误检查和专用运算符和功能。
| PostgreSQL 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
N/a |
|
|
|
N/a |
|
|
|
N/a |
|
|
|
N/a |
PostGIS 类型
PostgreSQL 连接器支持所有 PostGIS 数据类型。
| PostGIS 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
有关格式详情，请参阅 Open Geospatial Consortium Simple Features Access 规格。 |
|
|
|
有关格式详情，请参阅 Open Geospatial Consortium Simple Features Access 规格。 |
要粘贴的值
PostgreSQL 在页面大小上有一个硬限制。这意味着，大于大约 8 KB 的值需要使用 TOAST 存储存储存储。这会影响来自数据库的复制消息。使用 TOAST 机制存储的值，且尚未更改的值不会包含在消息中，除非它们是表的副本身份的一部分。Debezium 没有安全的方式直接从数据库读取缺少的值，因为这可能导致竞争条件。因此，Debezium 会遵循这些规则来处理粘贴值：
-
带有
REPLICA IDENTITY FULL-TOAST 列值的表是更改事件中的before和after字段的一部分，就像任何其他列一样。 -
带有
REPLICA IDENTITY DEFAULT的表 - 从数据库接收UPDATE事件时，任何不是副本身份一部分的 TOAST 列值都不会包含在事件中。同样，当收到DELETE事件时，没有 TOAST 列（如果有）位于before字段中。由于 Debezium 无法在此例中安全地提供列值，因此连接器会返回由连接器配置属性unavailable.value.placeholder定义的占位符值。
默认值
如果为数据库模式中的列指定默认值，PostgreSQL 连接器会在可能的情况下尝试将这个值传播到 Kafka 模式。最常见的数据类型包括：
-
布尔值 -
数字类型(
INT、FLOAT、NUMERIC等) -
文本类型(
CHAR、VARCHAR、TEXT等) -
临时类型(
DATE,TIME,INTERVAL,TIMESTAMP,TIMESTAMPTZ) -
JSON,JSONB,XML -
UUID
请注意，对于 temporal 类型，PostgreSQL 库提供了默认值解析；因此，PostgreSQL 通常支持的任何字符串表示也应该被连接器支持。
如果默认值由函数生成，而不是直接指定，则连接器将为给定的数据类型导出等效的 0。这些值包括：
-
用于
BOOLEAN的FALSE -
0，带有适当的精度，用于数字类型 - text/XML 类型的空字符串
-
{}用于 JSON 类型 -
1970-01-01用于DATE,TIMESTAMP,TIMESTAMPTZ类型 -
TIME00:00 -
INTERVAL为EPOCH -
UUID的00000000-0000-0000-0000-000000000000
这个支持目前只适用于显式使用功能。例如，CURRENT_TIMESTAMP (6) 支持括号，但 CURRENT_TIMESTAMP 不被支持。
对默认值传播的支持主要是为了允许在将 PostgreSQL 连接器与 schema registry 搭配使用时实现安全模式演进，该 registry 在 schema 版本之间强制实施兼容性。由于这个主要关注，以及不同插件的刷新行为，Kafka 模式中的默认值无法保证始终与数据库 schema 中的默认值同步。
- 根据给定插件触发刷新内存模式的时间，默认值可能会在 Kafka 模式中显示 'late'。如果默认更改多次 in-between 刷新，则可能不会在 Kafka 模式中跳过值
- 在连接器等待处理时，如果在 Kafka 模式中触发了 schema 刷新，默认值可能会出现 'early'。这是因为在刷新时从数据库读取列元数据，而不是在复制消息中显示。如果连接器位于且发生刷新，则会出现这种情况，如果连接器在一段时间后停止了连接器，则会出现这种情况，同时继续写入源数据库。
这个行为可能是意外的，但仍然是安全的。只有架构定义会受到影响，但消息中存在的实际值则与写入源数据库的内容保持一致。
自定义转换器
默认情况下，Debebe 不会使用自定义数据类型从列复制数据，如使用 SQL CREATE TYPE 语句创建的复合类型。要使用自定义数据类型复制列，请遵循 创建自定义转换器 的说明，但有几个重要的注意事项：
-
将连接器配置中的
include.unknown.datatypes属性设置为true。默认false设置会导致自定义转换器始终返回null值。 传递给转换器的值类型取决于为复制插槽配置的逻辑解码输出插件。
-
decoderbufs传递列数据的字节数组(byte[])表示。 -
pgoutput传递列数据的字符串表示。
-
2.6.5. 设置 PostgreSQL 以运行 Debezium 连接器
此 Debezium 发行版本只支持原生 pgoutput 逻辑复制流。要设置 PostgreSQL，使其使用 pgoutput 插件，您必须启用复制插槽，并配置具有足够特权的用户来执行复制。
详情包括在以下主题中：
2.6.5.1. 为 Debezium pgoutput 插件配置复制插槽
PostgreSQL 的逻辑解码使用复制插槽。要配置复制插槽，请在 postgresql.conf 文件中指定以下内容：
wal_level=logical max_wal_senders=1 max_replication_slots=1
wal_level=logical
max_wal_senders=1
max_replication_slots=1这些设置指示 PostgreSQL 服务器如下：
-
wal_level- 使用 write-ahead 日志的逻辑解码。 -
max_wal_senders- 使用最多一个单独的进程来处理 WAL 更改。 -
max_replication_slots- 允许为流 WAL 更改创建最多一个复制插槽。
可以保证复制插槽保留 Debezium 所需的所有 WAL 条目，即使在 Debezium 中断期间也是如此。因此，务必要密切监控复制插槽，以避免：
- 磁盘消耗太多
- 任何条件，如目录 bloat，当复制插槽保留太长时，可能会发生这种情况
如需更多信息，请参阅有关 复制插槽的 PostgreSQL 文档。
熟悉 PostgreSQL write-ahead 日志 的机制和配置有助于使用 Debezium PostgreSQL 连接器。
2.6.5.2. 为 Debezium 连接器设置 PostgreSQL 权限
设置 PostgreSQL 服务器以运行 Debezium 连接器需要能够执行复制的数据库用户。复制只能由具有适当权限的数据库用户执行，且只能针对配置的数量的主机执行。
虽然默认情况下，超级用户具有必要的 REPLICATION 和 LOGIN 角色，如 安全 中所述，最好不要为 Debezium 复制用户提供升级的特权。反之，创建一个具有最低所需权限的 Debezium 用户。
先决条件
- PostgreSQL 管理权限。
流程
要为用户提供复制权限，请定义 至少具有
REPLICATION和LOGIN权限的 PostgreSQL 角色，然后将该角色授予该用户。例如：CREATE ROLE <name> REPLICATION LOGIN;
CREATE ROLE <name> REPLICATION LOGIN;Copy to Clipboard Copied! Toggle word wrap Toggle overflow
2.6.5.3. 设置特权以启用 Debezium 创建 PostgreSQL 出版物
来自为表创建的 publications 的 PostgreSQL 源表的 Debezium 流改变事件。出版物包含一组经过过滤的更改事件，这些事件由一个或多个表生成。每个发布中的数据会根据发布规格过滤。该规格可由 PostgreSQL 数据库管理员或 Debezium 连接器创建。要允许 Debezium PostgreSQL 连接器创建发布并指定要复制到它们的数据，连接器必须使用数据库中的特定特权操作。
有几个选项可用于确定如何创建发布。通常，在设置连接器前，最好为您要捕获的表手动创建发布。但是，您可以将环境配置为允许 Debezium 自动创建发布的方式，并指定添加到它们中的数据。
Debezium 使用 include list 和 exclude list 属性来指定在发布中如何插入数据。有关启用 Debezium 创建发布的选项的更多信息，请参阅 publication.autocreate.mode。
要使 Debezium 创建 PostgreSQL 出版物，它必须以具有以下特权的用户身份运行：
- 数据库中的复制特权，将表添加到发布中。
-
数据库上的
CREATE特权来添加发布。 -
对表进行
SELECT特权，以复制初始表数据。表所有者会自动具有表的SELECT权限。
要向发布中添加表，用户必须是表的所有者。但是，由于源表已存在，您需要一种与原始所有者共享所有权的机制。要启用共享所有权，您可以创建一个 PostgreSQL 复制策略，然后将现有的表所有者和复制用户添加到组中。
流程
创建复制组。
CREATE ROLE <replication_group>;
CREATE ROLE <replication_group>;Copy to Clipboard Copied! Toggle word wrap Toggle overflow 将表的原始所有者添加到组。
GRANT REPLICATION_GROUP TO <original_owner>;
GRANT REPLICATION_GROUP TO <original_owner>;Copy to Clipboard Copied! Toggle word wrap Toggle overflow 将 Debezium 复制用户添加到组中。
GRANT REPLICATION_GROUP TO <replication_user>;
GRANT REPLICATION_GROUP TO <replication_user>;Copy to Clipboard Copied! Toggle word wrap Toggle overflow 将表的所有权转让到 <
replication_group>。ALTER TABLE <table_name> OWNER TO REPLICATION_GROUP;
ALTER TABLE <table_name> OWNER TO REPLICATION_GROUP;Copy to Clipboard Copied! Toggle word wrap Toggle overflow
要使 Debezium 指定捕获配置，必须将 publication.autocreate.mode 的值设置为 filtered。
2.6.5.4. 配置 PostgreSQL 以允许使用 Debezium 连接器主机复制
要启用 Debezium 来复制 PostgreSQL 数据，您必须配置数据库，以允许使用运行 PostgreSQL 连接器的主机复制。要指定允许使用数据库复制的客户端，请在基于 PostgreSQL 基于主机的身份验证文件 pg_hba.conf 中添加条目。有关 pg_hba.conf 文件的更多信息，请参阅 PostgreSQL 文档。
流程
在
pg_hba.conf文件中添加条目，以指定可以使用数据库主机复制的 Debezium 连接器主机。例如，pg_hba.conf文件示例：local replication <youruser> trust host replication <youruser> 127.0.0.1/32 trust host replication <youruser> ::1/128 trust
local replication <youruser> trust1 host replication <youruser> 127.0.0.1/32 trust2 host replication <youruser> ::1/128 trust3 Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.152. pg_hba.conf 设置的描述 项 描述 1
指示服务器允许在本地复制 &
lt;youruser>，即在服务器机器上。2
指示服务器允许
localhost上的 <youruser> 接收使用IPV4的复制更改。3
指示服务器允许
localhost上的 <youruser> 接收使用IPV6的复制更改。
有关网络掩码的更多信息，请参阅 PostgreSQL 文档。
2.6.5.5. 配置 PostgreSQL 以管理 Debezium WAL 磁盘空间消耗
在某些情况下，WAL 文件消耗的 PostgreSQL 磁盘空间可能会激增或增加通常的比例。这种情况有几个可能的原因：
连接器接收数据的 LSN 最多可在服务器的
pg_replication_slots视图的confirmed_flush_lsn列中提供。比这个 LSN 旧的数据不再可用，数据库负责重新声明磁盘空间。另外，在
pg_replication_slots视图中，restart_lsn列还包含连接器可能需要的最旧 WAL 的 LSN。如果confirmed_flush_lsn的值定期增加，并且restart_lsnlags 的值需要回收空间。数据库通常会在批处理块中回收磁盘空间。这是预期的行为，用户不需要任何操作。
在被跟踪的数据库中有很多更新，但只有少量更新与连接器捕获更改的表和模式相关。这种情形可以通过定期的心跳事件来轻松解决。设置
heartbeat.interval.ms连接器配置属性。注意要使连接器从 heartbeat 表检测和处理事件，您必须将表添加到由 publication.name 属性指定的 PostgreSQL 出版物中。如果此发布规定了 Debezium 部署，则连接器将使用定义的发布。如果发布尚未配置为自动复制数据库中更改
FOR ALL TABLES，则必须明确将 heartbeat 表添加到发布中，例如：
ALTER PUBLICATION < publicationName > ADD TABLE < heartbeatTableName > ;PostgreSQL 实例包含多个数据库，其中一个是高流量数据库。Debezium 捕获另一个数据库（与其他数据库相比）的低流量更改。然后 Debezium 无法确认 LSN 作为每个数据库的复制插槽工作，并且没有调用 Debezium。由于 WAL 由所有数据库共享，因此所使用的数量往往会增长，直到 Debezium 捕获更改的数据库发出事件为止。要解决此问题，需要：
-
使用
heartbeat.interval.ms连接器配置属性启用定期心跳记录生成。 - 定期从 Debezium 捕获更改的数据库发出更改事件。
然后，单独的进程会通过插入新行或重复更新同一行来定期更新表。然后，PostgreSQL 会调用 Debezium，它会确认最新的 LSN，并允许数据库回收 WAL 空间。此任务可以通过
heartbeat.action.query连接器配置属性自动执行。-
使用
为同一数据库服务器设置多个连接器
Debezium 使用复制插槽从数据库流更改。这些复制插槽以 LSN (Log Sequence Number)的形式维护当前位置，它指向 Debezium 连接器消耗的 WAL 中的位置。这有助于 PostgreSQL 保留 WAL 可用，直到 Debezium 处理为止。单个复制插槽只能用于单个消费者或进程 - 因为不同的消费者可能具有不同的状态，并可能需要来自不同位置的数据。
因为复制插槽只能被单个连接器使用，因此必须为每个 Debezium 连接器创建一个唯一的复制插槽。虽然当连接器不处于活跃状态时，Postgres 可能允许其他连接器消耗复制插槽 - 这可能会危险，因为它可能会导致数据丢失，因为插槽只会在 [请参阅更多] 后发出一次更改。
除了复制插槽外，Debezium 在使用 pgoutput 插件时使用发布来流传输事件。与复制插槽类似，发布位于数据库级别，并为一组表定义。因此，每个连接器都需要一个唯一的发布，除非连接器在同一个表中工作。有关启用 Debezium 创建发布的选项的更多信息，请参阅 publication.autocreate.mode
有关如何为每个连接器设置唯一的复制插槽名称和发布名称，请参阅 slot.name 和 publication.name。
2.6.5.6. 升级 Debezium 从中捕获的 PostgreSQL 数据库
当您升级 Debezium 使用的 PostgreSQL 数据库时，您必须执行特定的步骤来防止数据丢失，并确保 Debezium 继续操作。通常，Debezium 可以应对因网络故障和其他中断造成的中断。例如，当连接器监控的数据库服务器停止或崩溃时，连接器重新建立与 PostgreSQL 服务器通信后，它将继续从日志序列号(LSN)偏移记录的最后位置读取。连接器从 Kafka Connect offsets 主题检索最后一次记录的偏移信息，并查询配置的 PostgreSQL 复制插槽以获取具有相同值的日志序列号(LSN)。
要使连接器从 PostgreSQL 数据库启动和捕获更改事件，必须存在复制插槽。但是，作为 PostgreSQL 升级过程的一部分，复制插槽会被删除，在升级完成后不会恢复原始插槽。因此，当连接器重启并从复制插槽请求最后已知的偏移时，PostgreSQL 无法返回信息。
您可以创建新的复制插槽，但您必须执行超过创建新插槽来保护数据丢失。新的复制插槽只能为创建插槽后发生的更改提供 LSN；它无法为升级前发生的事件提供偏移。当连接器重启时，它首先从 Kafka offsets 主题请求最后已知的偏移量。然后，它会向复制插槽发送请求，以返回从偏移主题检索的偏移信息。但是，新的复制插槽无法提供连接器从预期位置恢复流所需的信息。然后，连接器跳过日志中任何现有更改事件，它只从日志中的最新位置恢复流。这可能会导致静默的数据丢失：连接器不会发出跳过的事件的记录，也不会提供任何信息来指示事件被跳过。
有关如何执行 PostgreSQL 数据库升级的指导，以便 Debezium 能够继续捕获事件，同时尽量减少数据丢失的风险，请参阅以下步骤。
流程
- 临时停止写入数据库的应用程序，或者将其置于只读模式。
- 备份数据库。
- 临时禁用对数据库的写访问。
- 在您阻止写操作被保存到 write-ahead 日志(WAL)之前，验证数据库中发生的任何更改，并且 WAL LSN 是否反映在复制插槽上。
-
为连接器提供足够的时间，以捕获写入复制插槽的所有事件记录。
此步骤可确保在考虑停机前发生的所有更改事件，并将其保存到 Kafka。 - 通过检查 flushed LSN 的值来验证连接器是否已消耗来自复制插槽的条目。
通过停止 Kafka Connect 来安全地关闭连接器。
Kafka Connect 停止连接器，将所有事件记录刷新到 Kafka，并记录从每个连接器接收的最后偏移量。
注意作为停止整个 Kafka Connect 集群的替代选择，您可以通过删除连接器来停止连接器。不要删除偏移主题，因为它可能由其他 Kafka 连接器共享。之后，在恢复对数据库的写入访问并准备好重启连接器后，您必须重新创建连接器。
-
作为 PostgreSQL 管理员，丢弃主数据库服务器上的复制插槽。不要使用
slot.drop.on.stop属性来丢弃复制插槽。此属性仅用于测试。 - 停止数据库。
-
使用批准的 PostgreSQL 升级过程，如
pg_upgrade或pg_dump和pg_restore执行升级。 -
（可选）使用标准 Kafka 工具从偏移存储主题中删除连接器偏移。
有关如何删除连接器偏移的示例，请参阅 如何在 Debezium 社区常见问题解答中删除连接器偏移。 - 重新启动数据库。
作为 PostgreSQL 管理员，在数据库上创建 Debezium 逻辑复制插槽。在启用对数据库的写操作前，您必须创建插槽。否则，Debebe 无法捕获更改，从而导致数据丢失。
有关设置复制插槽的详情，请参考 第 2.6.5.1 节 “为 Debezium
pgoutput插件配置复制插槽”。- 验证升级后是否仍然存在定义 Debezium 要捕获的表的发布。如果发布不可用，请以 PostgreSQL 管理员身份连接到数据库，以创建新的发布。
-
如果需要在上一步中创建新发布，请更新 Debezium 连接器配置，将新发布的名称添加到
publication.name属性中。 - 在连接器配置中，重命名连接器。
-
在连接器配置中，将
slot.name设置为 Debezium 复制插槽的名称。 - 验证新复制插槽是否可用。
- 恢复对数据库的写入访问权限，然后重新启动任何写入数据库的应用程序。
在连接器配置中，将
snapshot.mode属性设置为never，然后重新启动连接器。注意如果您无法验证 Debezium 是否已读取步骤 6 中的所有数据库更改，您可以通过设置
snapshot.mode=initial将连接器配置为执行新快照。如果需要，您可以通过检查升级前立即进行的数据库备份内容来确认连接器是否从复制插槽读取所有更改。
其他资源
2.6.6. 部署 Debezium PostgreSQL 连接器
您可以使用以下任一方法部署 Debezium PostgreSQL 连接器：
2.6.6.1. 使用 Streams for Apache Kafka 进行 PostgreSQL 连接器部署
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅在 OpenShift Container Platform 中管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.42. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium PostgreSQL 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关脚本引擎。SMT 归档和脚本语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.153. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Red Hat Maven 存储库中提供了 Debezium 连接器工件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需的脚本语言组件
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
作为替代方案，Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为postgresql-inventory-connector.yaml例 2.43. 为 Debezium 连接器定义
KafkaConnector自定义资源的 PostgreSQL-inventory-connector.yaml文件Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.154. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址。
6
数据库实例的端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
9
要从中捕获更改的数据库的名称。
10
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。11
连接器捕获更改事件的表列表。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f postgresql-inventory-connector.yaml
oc create -n debezium -f postgresql-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
要部署 Debezium PostgreSQL 连接器，您需要构建包含 Debezium 连接器存档的自定义 Kafka Connect 容器镜像，并将此容器镜像推送到容器 registry。然后，您需要创建两个自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium PostgreSQL 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- PostgreSQL 正在运行，并执行 设置 PostgreSQL 的步骤来运行 Debezium 连接器。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka 流。
- podman 或 Docker 已安装。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。
流程
为 Kafka Connect 创建 Debezium PostgreSQL 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-postgresql.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-postgresql.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-postgresql:latest .
podman build -t debezium-container-for-postgresql:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-postgresql:latest .
docker build -t debezium-container-for-postgresql:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow build命令使用名称debezium-container-for-postgresql构建容器镜像。将自定义镜像推送到容器 registry 中，如
quay.io或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：podman push <myregistry.io>/debezium-container-for-postgresql:latest
podman push <myregistry.io>/debezium-container-for-postgresql:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-postgresql:latest
docker push <myregistry.io>/debezium-container-for-postgresql:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium PostgreSQL
KafkaConnect自定义资源(CR)。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。运行以下命令，将
KafkaConnectCR 应用到 OpenShift Kafka 实例：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 这会更新 OpenShift 中的 Kafka Connect 环境，以添加 Kafka Connector 实例，以指定您为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium PostgreSQL 连接器实例。您可以在
.yaml文件中配置 Debezium PostgreSQL 连接器，该文件指定连接器的配置属性。连接器配置可能会指示 Debezium 为模式和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略、掩码或截断指定列中的值，这些值是敏感、太大或不需要的。有关您可以为 Debezium PostgreSQL 连接器设置的配置属性的完整列表，请参阅 PostgreSQL 连接器属性。以下示例显示了一个自定义资源摘录，它配置一个 Debezium 连接器，该连接器连接到 PostgreSQL 服务器主机
192.168.99.100，在端口5432上。此主机有一个名为sampledb的数据库，名为public的 schema，inventory-connector-postgresql是服务器的逻辑名称。
postgresql
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.155. PostgreSQL inventory-connector.yaml 示例中的设置描述 项 描述 1
用于在 Kafka Connect 中注册连接器的名称。
2
为此连接器创建的最大任务数量。因为 PostgreSQL 连接器使用单个连接器任务读取 PostgreSQL 服务器
binlog，以确保正确顺序和事件处理，所以一次只能运行一个任务。Kafka Connect 服务使用连接器启动一个或多个任务来执行工作，并在 Kafka Connect 服务集群中自动分发正在运行的任务。如果有任何服务停止或崩溃，任务将重新分发到运行的服务。3
连接器的配置。
4
运行 PostgreSQL 服务器的数据库主机的名称。在本例中，数据库主机名是
192.168.99.100。5
唯一的主题前缀。主题前缀是 PostgreSQL 服务器或服务器集群的逻辑标识符。这个字符串作为前缀放在所有 Kafka 主题的名称前面，这些主题从连接器接收更改事件记录。
6
连接器只捕获
public模式中的更改。可以将连接器配置为只捕获您选择的表中的更改。如需更多信息，请参阅table.include.list。7
PostgreSQL 逻辑解码插件在 PostgreSQL 服务器上安装的名称。虽然连接器只支持使用
pgoutput插件，但您必须将plugin.name明确设置为pgoutput。使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 这会注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的sampledb数据库运行。
结果
连接器启动后，它会对 为连接器配置的 PostgreSQL 服务器数据库执行一致的快照。然后，连接器开始为行级操作生成数据更改事件，并将更改事件记录流传输到 Kafka 主题。
2.6.6.4. 验证 Debezium PostgreSQL 连接器是否正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，点您要检查的连接器名称，如 inventory-connector-postgresql。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-postgresql -n debezium
oc describe KafkaConnector inventory-connector-postgresql -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.44.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，点您要检查的主题名称，如
inventory-connector-postgresql.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.45.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-postgresql.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-postgresql.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中
oc describe命令返回的格式（如inventory-connector-postgresql.inventory.addresses）。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.46. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-postgresql.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-postgresql.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-postgresql.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.postgresql.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-postgresql.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"postgresql","name":"inventory-connector-postgresql","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"postgresql-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-postgresql.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-postgresql.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-postgresql.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.postgresql.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-postgresql.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"postgresql","name":"inventory-connector-postgresql","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"postgresql-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
2.6.6.5. Debezium PostgreSQL 连接器配置属性的描述
Debezium PostgreSQL 连接器有许多配置属性，您可以使用它们来实现应用程序的正确连接器行为。许多属性具有默认值。有关属性的信息按如下方式进行组织：
所需的 Debezium PostgreSQL 连接器配置属性
除非默认值可用 ， 否则需要以下配置属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器的唯一名称。尝试使用相同名称再次注册将失败。所有 Kafka Connect 连接器都需要此属性。 | |
| 没有默认值 |
连接器的 Java 类的名称。对于 PostgreSQL 连接器，始终使用 | |
|
| 应该为此连接器创建的最大任务数量。PostgreSQL 连接器始终使用单个任务，因此不使用这个值，因此始终可以接受默认值。 | |
|
| PostgreSQL 逻辑解码插件在 PostgreSQL 服务器上安装的名称。
唯一支持的值是 | |
|
| 创建用于特定数据库/schema 的特定插件的 PostgreSQL 逻辑解码插槽的名称。服务器使用此插槽将事件流传输到您要配置的 Debezium 连接器。 插槽名称必须符合 PostgreSQL 复制插槽命名规则，其状态："每个复制插槽都有一个名称，可包含小写字母、数字和下划线字符"。 | |
|
| 当连接器以安全、预期的方式停止时，是否删除逻辑复制插槽。默认行为是，当连接器停止时，复制插槽仍然为连接器配置。当连接器重启时，具有相同的复制插槽可让连接器开始处理它的位置。
仅在测试或开发环境中设置为 | |
|
|
在使用 如果此发布不存在，则会在启动时创建，它将 包含所有表。然后，Debezium 应用自己的 include/exclude 列表过滤（如果已配置），将发布限制为更改感兴趣的特定表的事件。连接器用户必须具有创建此出版物的超级用户权限，因此通常最好在首次启动连接器前创建发布。 如果发布已存在，无论是所有表，或者通过表子集配置，Debezium 会使用定义的发布。 | |
| 没有默认值 | PostgreSQL 数据库服务器的 IP 地址或主机名。 | |
|
| PostgreSQL 数据库服务器的整数端口号。 | |
| 没有默认值 | 用于连接到 PostgreSQL 数据库服务器的 PostgreSQL 数据库用户的名称。 | |
| 没有默认值 | 连接到 PostgreSQL 数据库服务器时要使用的密码。 | |
| 没有默认值 | 从中流传输更改的 PostgreSQL 数据库的名称。 | |
| 没有默认值 |
为特定的 PostgreSQL 数据库服务器或集群提供命名空间的主题前缀，在其中捕获 Debezium。前缀应该在所有其他连接器之间唯一，因为它用作从这个连接器接收记录的所有 Kafka 主题的主题名称前缀。数据库服务器逻辑名称中只能使用字母数字字符、连字符、点和下划线。 警告 不要更改此属性的值。如果您更改了 name 值，重启后，而不是继续向原始主题发送事件，连接器会将后续事件发送到名称基于新值的主题。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您要 捕获更改的模式名称匹配。没有包含在 schema.
要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与架构的整个标识符匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与 您不想 捕获更改的模式名称匹配。任何名称不包含在 schema.
要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与架构的整个标识符匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您要捕获的表的完全限定表标识符匹配。当设置此属性时，连接器只从指定的表中捕获更改。每个标识符都是 schemaName.tableName 的形式。默认情况下，连接器捕获捕获更改的每个模式中的每个非系统表中的更改。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个标识符匹配；它不匹配表名称中可能存在的子字符串。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您不想捕获的表的完全限定表标识符匹配。每个标识符都是 schemaName.tableName 的形式。当设置此属性时，连接器会捕获您没有指定的每个表中的更改。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个标识符匹配；它不匹配表名称中可能存在的子字符串。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与更改事件记录值中包含的列的完全限定域名匹配。列的完全限定域名格式为 schemaName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，表达式用于与列中的整个名称字符串匹配；它不匹配列名称中可能存在的子字符串。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与应从更改事件记录值中排除的列的完全限定名称匹配。列的完全限定域名格式为 schemaName.tableName.columnName。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，表达式用于与列中的整个名称字符串匹配；它不匹配列名称中可能存在的子字符串。 | |
|
|
指定在包含的列中没有更改时跳过发布消息。如果列没有包括每个 注： 只有当表的 REPLICA IDENTITY 被设置为 FULL 时，才可以正常工作 | |
|
|
时间、日期和时间戳可以以不同的精度类型表示： | |
|
|
指定连接器应该如何处理 | |
|
|
指定连接器应该如何处理 | |
|
|
指定连接器如何处理 | |
|
|
是否使用到 PostgreSQL 服务器的加密连接。选项包括： | |
| 没有默认值 | 包含客户端的 SSL 证书的文件路径。如需更多信息 ，请参阅 PostgreSQL 文档。 | |
| 没有默认值 | 包含客户端 SSL 私钥的文件的路径。如需更多信息 ，请参阅 PostgreSQL 文档。 | |
| 没有默认值 |
从 | |
| 没有默认值 | 包含验证服务器的根证书的文件的路径。如需更多信息 ，请参阅 PostgreSQL 文档。 | |
|
| 启用 TCP keep-alive 探测，以验证数据库连接是否仍处于活动状态。如需更多信息 ，请参阅 PostgreSQL 文档。 | |
|
|
控制 删除 事件是否后跟 tombstone 事件。 | |
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果在列中的数据超过了在属性名中的 length 指定的字符长度时删节数据，设置此属性。将
一个列的完全限定名称会观察以下格式：< 您可以在单个配置中指定多个长度不同的属性。 | |
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果您希望连接器屏蔽一组列的值，例如，如果它们包含敏感数据，则设置此属性。将 列的完全限定域名观察以下格式： schemaName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。 您可以在单个配置中指定多个长度不同的属性。 | |
|
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。列的完全限定域名格式为 <schemaName>.<tableName>.<columnName>.
一个 pseudonym，它包括了通过应用指定的 hashAlgorithm 和 salt 的结果的哈希值。根据使用的 hash 功能，引用完整性会被维护，而列值则替换为 pseudonyms。Java 加密架构标准算法 文档的 MessageDigest 部分中 描述了支持的哈希功能。 column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName
如有必要，pseudonym 会自动缩短到列的长度。连接器配置可以包含多个属性，以指定不同的哈希算法和 salt。 |
| 不适用 | 可选的、以逗号分隔的正则表达式列表，与您希望连接器发送代表列元数据的额外参数匹配。当设置此属性时，连接器将以下字段添加到事件记录的 schema 中：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
列的完全限定域名观察以下格式之一： databaseName.tableName.columnName, 或 databaseName.schemaName.tableName.columnName。 | |
| 不适用 | 可选的、以逗号分隔的正则表达式列表，用于指定为数据库中列定义的数据类型的完全限定名称。当设置此属性时，对于带有匹配数据类型的列，连接器会发出事件记录，该记录在其 schema 中包含以下额外字段：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
列的完全限定域名观察以下格式之一： databaseName.tableName.typeName, 或 databaseName.schemaName.tableName.typeName。 有关特定于 PostgreSQL 的数据类型名称的列表，请参阅 PostgreSQL 数据类型映射。 | |
| 空字符串 | 一个表达式列表，用于指定连接器用来组成自定义消息键的表达式列表，用于更改它发布到指定表的 Kafka 主题。
默认情况下，Debebe 使用表的主键列作为发出的记录的消息键。使用默认键，或者为缺少主密钥的表指定一个键，您可以根据一个或多个列配置自定义消息密钥。
每个完全限定表名称都是以下格式的正则表达式： 对用来创建自定义消息键的列数量没有限制。但是，最好使用指定唯一密钥所需的最小数量。
请注意，在表上将此属性设置为 | |
| all_tables |
指定连接器是否和方式创建 发布。此设置仅在使用 注意 要创建发布，连接器必须通过具有特定权限的数据库帐户访问 PostgreSQL。如需更多信息，请参阅设置特权，使 Debezium 创建 PostgreSQL 出版物。 指定以下值之一：
| |
| 空字符串 |
此设置决定了表级别上 副本身份 的值。 schema1.*:FULL,schema2.table2:NOTHING,schema2.table3:INDEX idx_name | |
| bytes |
指定在更改事件中二进制( | |
| none |
指定应该如何调整模式名称，以便与连接器使用的消息转换器兼容。可能的设置：
| |
| none |
指定应如何调整字段名称，以便与连接器使用的消息转换器兼容。可能的设置：
如需更多信息，请参阅 Avro 命名。 | |
|
|
指定在将 Postgres | |
| 没有默认值 | 可选的、以逗号分隔的正则表达式列表，与您希望连接器捕获的逻辑解码消息前缀的名称匹配。默认情况下，连接器会捕获所有逻辑解码信息。当设置此属性时，连接器只使用属性指定的前缀捕获逻辑解码消息。所有其他逻辑解码消息都排除。 要匹配消息前缀的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与整个消息前缀字符串匹配；表达式不匹配前缀中可能存在的子字符串。
如果您在配置中包含此属性，不要设置 有关 消息 事件结构及其排序语义的详情，请参考 消息 事件。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您不希望连接器捕获的逻辑解码消息前缀匹配。当设置此属性时，连接器不会捕获使用指定前缀的逻辑解码消息。所有其他消息都会被捕获。 要匹配消息前缀的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与整个消息前缀字符串匹配；表达式不匹配前缀中可能存在的子字符串。
如果您在配置中包含此属性，不要设置 有关 消息 事件结构及其排序语义的详情，请参考 消息 事件。 |
高级 Debezium PostgreSQL 连接器配置属性
以下 高级配置 属性在大多数情况下可以正常工作，因此很少需要在连接器配置中指定。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
枚举连接器可以使用的 自定义转换器 实例的符号链接名称列表。例如，
您必须设置
对于您为连接器配置的每个转换器，还必须添加一个
例如， isbn.type: io.debezium.test.IsbnConverter
如果要进一步控制配置的转换器的行为，您可以添加一个或多个配置参数来将值传递给转换器。要将任何其他配置参数与转换器关联，请为参数名称添加转换器符号名称作为前缀。 isbn.schema.name: io.debezium.postgresql.type.Isbn | |
| Initial |
指定在连接器启动时执行快照的条件：
如果 Kafka offsets 主题中存在之前存储的 LSN，则连接器将继续从该位置流更改。如果没有存储 LSN，则连接器会在服务器上创建 PostgreSQL 逻辑复制插槽时从点开始流更改。只有在您知道所有感兴趣的数据仍然反映在 WAL 中时，才使用此快照模式。
如需更多信息，请参阅 | |
|
|
指定连接器在执行 schema 快照时如何在表上锁定。
警告 如果在快照过程中可能会出现模式，请不要使用此模式。 | |
|
|
指定连接器在执行快照时如何查询数据。
与使用 | |
|
|
可选的、以逗号分隔的正则表达式列表，与表的完全限定名称(< 要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
|
| 正整数值，用于指定在执行快照时等待获取表锁定的最大时间（以毫秒为单位）。如果连接器无法在这个时间段内获取表锁定，则快照会失败。连接器如何执行快照 提供详细信息。 | |
| 没有默认值 | 指定要包含在快照中的表行。如果您希望快照只包括表中的行的子集，请使用该属性。此属性仅影响快照。它不适用于连接器从日志读取的事件。
属性包含以逗号分隔的完全限定表名称列表，格式为 <
从包括软删除列 "snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM customers.orders WHERE delete_flag = 0 ORDER BY id DESC"
在生成的快照中，连接器只包含 | |
|
|
指定连接器在处理事件时应如何响应异常： | |
|
| 正整数值，用于指定连接器进程的每个批处理事件的最大大小。 | |
|
|
正整数值，用于指定阻塞队列可以保存的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将 | |
|
|
指定阻塞队列的最大卷的长整数值，以字节为单位。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。 | |
|
| 正整数值指定连接器在开始处理一系列事件前应等待新的更改事件数。默认值为 500 毫秒。 | |
|
|
当连接器遇到数据类型为 unknown 的字段时，指定连接器行为。默认行为是连接器省略更改事件中的字段，并记录警告。 注意
当 | |
| 没有默认值 |
在建立 JDBC 连接时，连接器执行的分号分隔的 SQL 语句列表。要将分号用作字符而不是分隔符，请指定两个连续分号 | |
|
|
将复制连接状态更新发送到服务器的频率，以毫秒为单位。 | |
|
|
控制连接器将心跳信息发送到 Kafka 主题的频率。默认行为是连接器不发送心跳消息。 | |
| 没有默认值 |
指定当连接器发送心跳消息时连接器在源数据库上执行的查询。 | |
|
|
指定触发表的内存中模式刷新的条件。 | |
| 没有默认值 | 连接器在连接器启动时执行快照前应等待的时间（以毫秒为单位）。如果您要在集群中启动多个连接器，此属性可用于避免快照中断，这可能会导致连接器重新平衡。 | |
| 0 |
指定连接器在完成快照后延迟流过程启动的时间（以毫秒为单位）。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的 | |
|
| 在快照过程中，连接器在行的批处理中读取表内容。此属性指定批处理中的最大行数。 | |
| 没有默认值 |
要传递给配置的逻辑解码插件的参数的分号分隔列表。例如： | |
|
| 如果连接到复制插槽失败，这是连续尝试连接的最大数量。 | |
|
| 连接器无法连接到复制插槽时在重试尝试之间等待的毫秒数。 | |
|
|
指定连接器提供的恒定，表示原始值是一个未由数据库提供的值。如果 | |
|
|
决定连接器是否生成带有事务边界的事件，并使用事务元数据增强更改事件。如果您希望连接器进行此操作，请指定 | |
|
|
确定连接器是否应该提交源 postgres 数据库中已处理记录的 LSN，以便可以删除 WAL 日志。如果您不希望连接器进行此操作，请指定 | |
| 10000 (10 秒) | 在发生 Retriable 错误后重启连接器前等待的毫秒数。 | |
|
|
在流过程中跳过的操作类型的逗号分隔列表。操作包括： | |
| 没有默认值 |
用于向连接器发送信号的数据收集的完全限定名称。 | |
| source | 为连接器启用的信号通道名称列表。默认情况下，以下频道可用：
| |
| 没有默认值 | 为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
| |
| 1024 | 连接器在增量快照块期间获取并读取的最大行数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。 | |
|
|
指定连接器在增量快照中使用的水位线机制，以重复数据删除事件，这些事件可能会被增量快照捕获，然后在流恢复后重新捕获。
| |
|
|
XMIN 将从复制插槽读取的频率（以毫秒为单位）。XMIN 值提供新复制插槽可从中开始的位置的低限。默认值 | |
|
|
应用于确定数据更改的主题名称、模式更改、事务、心跳事件等主题名称，默认为 | |
|
|
指定主题名称的分隔符，默认为 | |
|
| 在绑定的并发散列映射中保存主题名称的大小。此缓存将有助于确定与给定数据收集对应的主题名称。 | |
|
|
控制连接器发送心跳消息的主题名称。主题名称具有此模式： | |
|
|
控制连接器发送事务元数据消息的主题名称。主题名称具有此模式： | |
|
| 指定连接器在执行初始快照时使用的线程数量。要启用并行初始快照，请将 属性设置为大于 1 的值。在并行初始快照中，连接器同时处理多个表。 重要 并行初始快照只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。 | |
|
|
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如 连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。 | |
|
|
指定连接器如何在生成 Retriable 错误的操作后响应，如连接错误。
| |
|
|
指定连接器等待查询完成的时间（以毫秒为单位）。将值设为 |
透传 PostgreSQL 连接器配置属性
连接器支持 通过传递 属性，使 Debezium 指定自定义配置选项来微调 Apache Kafka producer 和消费者的行为。有关 Kafka 生成者和消费者的完整配置属性范围的详情，请参考 Kafka 文档。
用于通过属性配置 PostgreSQL 连接器如何与 Kafka 信号主题交互
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
为信号频道配置 Kafka 消费者客户端的属性
Debezium 连接器提供信号 Kafka 使用者的直通配置。透传信号属性以 signals.consumer.* 前缀开始。例如，连接器将 signal.consumer.security.protocol=SSL 等属性传递给 Kafka 使用者。
Debezium 在将属性传递给 Kafka 信号消费者前从属性中剥离前缀。
用于配置 PostgreSQL 连接器接收器通知频道的直通属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
Debezium 连接器传递数据库驱动程序配置属性
Debezium 连接器提供数据库驱动程序的直通配置。透传数据库属性以前缀 driverPROFILE 开头。例如，连接器将 driver.foobar=false 等属性传递给 JDBC URL。
Debezium 在将属性传递给数据库驱动程序前从属性中剥离前缀。
2.6.7. 监控 Debezium PostgreSQL 连接器性能
Debezium PostgreSQL 连接器提供两种类型的指标，除了对 Zookeeper、Kafka 和 Kafka Connect 提供的 JMX 指标的支持外。
Debezium 监控文档 提供了如何使用 JMX 公开这些指标的详细信息。
/ type: concept.Customized MBean name
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.47. 自定义标签如何修改连接器 MBean 名称
默认情况下，PostgreSQL 连接器使用以下 MBean 名称进行流传输指标：
debezium.postgresql:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.postgresql:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.postgresql:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.postgresql:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.6.7.1. 在 PostgreSQL 数据库快照过程中监控 Debezium
MBean 为 debezium.postgres:type=connector-metrics,context=snapshot,server= <topic.prefix>。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
连接器还会在执行增量快照时提供以下附加快照指标：
2.6.7.2. 监控 Debezium PostgreSQL 连接器记录流
MBean 为 debezium.postgres:type=connector-metrics,context=streaming,server= <topic.prefix>。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
2.6.8. Debezium PostgreSQL 连接器如何处理错误和问题
Debezium 是一个分布式系统，它捕获了多个上游数据库中的所有更改，永远不会丢失或丢失某个事件。当系统正常运行或被仔细管理时，Debezium 会在每次更改事件记录的发送 一次。
PostgreSQL 更改事件记录的确切交付只是一个技术预览功能。红帽不支持开发人员预览软件，且功能完整或生产就绪。不要将开发人员预览软件用于生产环境或关键业务工作负载。开发人员预览软件提供早期对即将推出的产品软件的访问权限，以将其包括在红帽产品产品中。客户可以使用此软件来测试功能并在开发过程中提供反馈。此软件可能没有任何文档，可以随时更改或删除，并且已获得有限的测试。红帽可能会提供在没有关联 SLA 的情况下对开发者预览软件提交反馈的方法。
有关 Red Hat Developer Preview 软件的支持范围的更多信息，请参阅 开发人员预览支持范围。
如果出现错误，则系统不会丢失任何事件。但是，当从错误中恢复时，连接器可能会发出一些重复的更改事件。在这些常规情况下，Debezium （如 Kafka） 至少提供一次 更改事件。
详情包括在以下部分中：
配置和启动错误
在以下情况下，连接器会在尝试启动时失败，在日志中报告错误/exception，并停止运行：
- 连接器的配置无效。
- 连接器无法使用指定的连接参数成功连接到 PostgreSQL。
- 连接器会从 PostgreSQL WAL 中的之前记录的位置（使用 LSN）中重启，PostgreSQL 不再有该历史记录可用。
在这些情况下，错误消息详细介绍了此问题，并可能是一个推荐的临时解决方案。在更正配置或解决 PostgreSQL 问题后，重启连接器。
PostgreSQL 连接器以 PostgreSQL LSN 的形式存储最后一次处理的偏移量。在连接器重启并连接到服务器实例后，连接器与服务器通信，以继续从该特定偏移流。只要 Debezium 复制插槽保持不变，这个偏移就会可用。永远不会在主服务器中丢弃复制插槽，否则您将丢失数据。有关删除插槽的失败情况的详情，请参考下一部分。
集群故障
从版本 12 开始，PostgreSQL 仅在主服务器中 允许逻辑复制插槽。这意味着，您可以将 Debezium PostgreSQL 连接器指向数据库集群的活跃主服务器。另外，复制插槽本身不会传播到副本。如果主服务器停机，则必须升级新的主服务器。
有些管理的 PostgresSQL 服务（例如，AWS RDS 和 GCP CloudSQL）通过磁盘复制实现复制到待机。这意味着复制插槽会被复制，在故障转移后将保持可用。
新的主设备必须配置供 pgoutput 插件使用的复制插槽，以及您要捕获更改的数据库。然后，您只能将连接器指向新的服务器并重启连接器。
发生故障转移时需要考虑重要的注意事项，您应该暂停 Debezium，直到您能够验证没有丢失数据的复制插槽。故障转移后：
- 在允许应用程序写入 新 主之前，必须有一个重新创建 Debezium 复制插槽的进程。这至关重要。如果没有这个过程，您的应用程序可能会错过更改事件。
- 您可能需要验证 Debezium 是否能够 在旧主失败前读取插槽中的所有更改。
恢复并验证任何更改是否已丢失的可靠方法是，在失败前，立即恢复对故障主点的备份。虽然这可能比较困难，但它允许您检查任何未消耗的更改的复制插槽。
Kafka Connect 进程正常停止
假设 Kafka Connect 正在以分布式模式运行，并且 Kafka Connect 进程安全停止。在关闭该进程前，Kafka Connect 会将进程的连接器任务迁移到该组中的另一个 Kafka Connect 进程。新的连接器任务会准确开始处理之前任务停止的位置。处理过程中会有一个短暂的延迟，而连接器任务被安全停止并在新进程中重启。
Kafka Connect 进程崩溃
如果 Kafka Connector 进程意外停止，则它运行的连接器任务都会终止，而不会记录它们最近处理的偏移量。当 Kafka Connect 在分布式模式下运行时，Kafka Connect 会在其他进程中重启这些连接器任务。但是，PostgreSQL 连接器会从之前进程 记录 的最后偏移量中恢复。这意味着，新的替换任务可能会生成在崩溃前处理的一些相同的更改事件。重复事件的数量取决于偏移清除周期以及崩溃前数据更改的卷。
因为在从失败时恢复过程中可能会重复一些事件，所以消费者应始终预期一些重复的事件。Debezium 更改是幂等的，因此一系列事件始终产生相同的状态。
在每个更改事件记录中，Debezium 连接器会插入有关事件来源的特定于源的信息，包括 PostgreSQL 服务器事件的时间、服务器事务 ID 和写入事务更改的位置。消费者可以跟踪此信息，特别是 LSN，以确定事件是否重复。
连接器在持续时间内停止
如果连接器安全停止，则数据库可以继续使用。所有更改都会记录在 PostgreSQL WAL 中。当连接器重启时，它会恢复其离开的位置流更改。也就是说，它会为所有在连接器停止期间进行的所有数据库更改生成更改事件记录。
正确配置的 Kafka 集群可以处理大量吞吐量。Kafka Connect 根据 Kafka 最佳实践编写，给定 Kafka Connect 连接器可以处理大量数据库更改事件。因此，在停止一段时间后，当 Debezium 连接器重启时，可能会捕获在停止期间进行的数据库更改。发生这种情况的速度取决于 Kafka 的功能和性能，以及对 PostgreSQL 中数据所做的更改卷。
2.7. SQL Server 的 Debezium 连接器
Debezium SQL Server 连接器捕获 SQL Server 数据库 schema 中发生的行级更改。
有关与此连接器兼容的 SQL Server 版本的详情，请参考 Debezium 支持的配置 页面。
有关 Debezium SQL Server 连接器及其使用的详情，请查看以下主题：
- 第 2.7.1 节 “Debezium SQL Server 连接器概述”
- 第 2.7.2 节 “Debezium SQL Server 连接器如何工作”
- 第 2.7.2.11 节 “Debezium SQL Server 连接器数据更改事件的描述”
- 第 2.7.2.13 节 “Debezium SQL Server 连接器如何映射数据类型”
- 第 2.7.3 节 “设置 SQL Server 以运行 Debezium 连接器”
- 第 2.7.4 节 “部署 Debezium SQL Server 连接器”
- 第 2.7.5 节 “在 schema 更改后刷新捕获表”
- 第 2.7.6 节 “监控 Debezium SQL Server 连接器性能”
当 Debezium SQL Server 连接器连接到 SQL Server 数据库或集群时，它会获取数据库中 schema 的一致性快照。初始快照完成后，连接器会持续捕获 INSERT、UPDATE 或 DELETE 操作的行级更改，它们提交到为 CDC 启用的 SQL Server 数据库。连接器为每个数据更改操作生成事件，并将其流传输到 Kafka 主题。连接器将表的所有事件流传输到专用 Kafka 主题。然后，应用程序和服务可以使用来自该主题的数据更改事件记录。
2.7.1. Debezium SQL Server 连接器概述
Debezium SQL Server 连接器基于 SQL Server 2016 Service Pack 1 (SP1)以及更新的 标准版本或企业版本中提供的 更改数据捕获 功能。SQL Server 捕获进程监控指定的数据库和表，并将更改存储在特定创建的 change tables 中。
要启用 Debezium SQL Server 连接器来捕获数据库操作的更改事件记录，您必须首先在 SQL Server 数据库上启用更改数据捕获。在数据库和您要捕获的每个表中都必须启用 CDC。在源数据库上设置 CDC 后，连接器可以捕获数据库中发生的行级 INSERT、UPDATE 和 DELETE 操作。连接器将每个源表的事件记录写入 Kafka 主题，特别是该表。每个捕获的表都有一个主题。客户端应用程序读取其后面的数据库表的 Kafka 主题，并可以响应这些主题中消耗的行级事件。
当连接器连接到 SQL Server 数据库或集群时，它会为它配置为捕获更改的所有表生成一致的模式快照，并将这个状态流传输到 Kafka。快照完成后，连接器会持续捕获发生的后续行级更改。通过首先建立所有数据的一致视图，连接器可以继续读取，而不会丢失快照发生期间所做的任何更改。
Debezium SQL Server 连接器接受故障。当连接器读取更改并生成事件时，它会定期记录数据库日志中事件的位置(LSN / Log Sequence Number)。如果连接器因任何原因（包括通信失败、网络问题或崩溃）停止，重启连接器会从它读取的最后点恢复 SQL Server CDC 表。
偏移会定期提交。它们不会在发生更改事件时提交。因此，在中断后，可能会生成重复的事件。
容错也适用于快照。也就是说，如果连接器在快照过程中停止，连接器会在重启时启动新的快照。
2.7.2. Debezium SQL Server 连接器如何工作
要优化地配置和运行 Debezium SQL Server 连接器，了解连接器如何执行快照、流更改事件、决定 Kafka 主题名称，并使用元数据。
有关连接器如何工作的详情，请查看以下部分：
- 第 2.7.2.1 节 “Debezium SQL Server 连接器如何执行数据库快照”
- 第 2.7.2.2 节 “临时快照”
- 第 2.7.2.3 节 “增量快照”
- 第 2.7.2.5 节 “Debezium SQL Server 连接器如何读取更改数据表”
- 第 2.7.2.8 节 “接收 Debezium SQL Server 更改事件记录的 Kafka 主题的默认名称”
- 第 2.7.2.10 节 “Debezium SQL Server 连接器如何使用 schema 更改主题”
- 第 2.7.2.11 节 “Debezium SQL Server 连接器数据更改事件的描述”
- 第 2.7.2.12 节 “Debezium SQL Server 连接器生成的事件代表事务边界”
2.7.2.1. Debezium SQL Server 连接器如何执行数据库快照
SQL Server CDC 不设计为存储数据库更改的完整历史记录。对于 Debezium SQL Server 连接器，为数据库的当前状态建立基准，它会使用名为 snapshotting 的进程。初始快照捕获数据库中表的结构和数据。
您可以在以下部分中找到有关快照的更多信息：
2.7.2.1.1. Debezium SQL Server 连接器用于执行初始快照的默认工作流
以下工作流列出了 Debezium 创建快照的步骤。这些步骤描述了当 snapshot.mode 配置属性设置为默认值时快照的进程，这是 初始。您可以通过更改 snapshot.mode 属性的值来自定义连接器创建快照的方式。如果您配置不同的快照模式，连接器使用此工作流的修改版本完成快照。
- 建立与数据库的连接。
-
确定要捕获的表。默认情况下，连接器会捕获所有非系统表。要让连接器捕获表或表元素的子集，您可以设置多个
include和exclude属性来过滤数据，如table.include.list或table.exclude.list。 -
在启用了 CDC 的 SQL Server 表上获取锁定，以防止在创建快照期间发生结构更改。锁定的级别由
snapshot.isolation.mode配置属性决定。 - 阅读服务器事务日志中的最大日志序列号(LSN)位置。
捕获所有非系统的结构或指定用于捕获的所有表。连接器在其内部数据库模式历史记录主题中保留此信息。架构历史记录提供有关发生更改事件时所生效的结构的信息。
注意默认情况下，连接器捕获数据库中处于捕获模式的每个表的模式，包括没有为捕获配置的表。如果没有为捕获配置表，则初始快照只捕获其结构；它不会捕获任何表数据。有关您在初始快照中没有包括快照持久模式信息的更多信息，请参阅 了解为什么初始快照捕获所有表的 schema。
- 释放在第 3 步中获取的锁定（如果需要）。其他数据库客户端现在可以写入任何之前锁定的表。
在第 4 步读取的 LSN 位置，连接器会扫描要捕获的表。在扫描过程中，连接器完成以下任务：
- 确认表已在快照开始之前创建。如果在快照开始后创建了表，连接器会跳过该表。快照完成后，连接器过渡到 streaming，它会为快照开始后创建的任何表发出更改事件。
-
为从表中捕获的每行生成一个
读取事件。所有读取事件都包含相同的 LSN 位置，这是在第 4 步中获取的 LSN 位置。 -
向表的 Kafka 主题发出每个
读取事件。
- 在连接器偏移中记录成功完成快照。
生成的初始快照捕获为 CDC 启用的表中的每行的当前状态。在这个基准状态中，连接器会捕获后续更改。
在快照过程开始后，如果进程因为连接器失败、重新平衡或其他原因而中断，进程会在连接器重启后重启。
连接器完成初始快照后，它会从第 4 步中读取的位置继续流传输，以便它不会丢失任何更新。
如果连接器因任何原因再次停止，它会在重启后恢复流更改，从之前离开的位置恢复流更改。
| 设置 | 描述 |
|---|---|
|
| 在每个连接器启动时执行快照。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照，如用于创建初始快照的默认工作流 中所述。快照完成后，连接器将开始流传输后续数据库更改的事件记录。 |
|
| 连接器执行数据库快照并在流传输任何更改事件记录前停止，不允许捕获任何后续更改事件。 |
|
|
弃用，请参阅 |
|
|
连接器捕获所有相关表的结构，执行 默认快照工作流 中描述的所有步骤，但它没有创建 |
|
|
设置这个选项以恢复丢失或损坏的数据库 schema 历史记录主题。重启后，连接器运行一个从源表中重建主题的快照。您还可以设置属性，以定期修剪遇到意外增长的数据库 schema 历史记录主题。 + 警告：如果在最后一个连接器关闭后将架构更改提交到数据库，请不要使用此模式执行快照。 |
|
| 连接器启动后，只有在检测到以下情况之一时才执行快照：
|
如需更多信息，请参阅连接器配置属性表中的 snapshot.mode。
2.7.2.1.2. 有关初始快照捕获所有表的 schema 历史记录的描述
连接器运行的初始快照捕获两种类型的信息：
- 表数据
-
有关
INSERT、UPDATE和DELETE操作的信息，它们在连接器的table.include.list属性中命名。 - 模式数据
- 描述应用到表的结构更改的 DDL 语句。如果配置了 schema 数据，则 schema 数据会被保留到内部模式历史记录主题，以及连接器的 schema 更改主题。
运行初始快照后，您可能会注意到快照捕获了未指定用于捕获的表的模式信息。默认情况下，初始快照旨在捕获数据库中存在的每个表的模式信息，而不仅限于为捕获指定的表。连接器要求表的 schema 在捕获表之前存在于 schema 历史记录主题中。通过启用初始快照来捕获不属于原始捕获集的表，Debezium 准备连接器，以便稍后需要从这些表中读取事件数据。如果初始快照没有捕获表的模式，您必须将 schema 添加到历史记录主题，然后才能从表中捕获数据。
在某些情况下，您可能想要限制初始快照中的模式捕获。当您要减少完成快照所需的时间时，这非常有用。或者，当 Debezium 通过有权访问多个逻辑数据库的用户帐户连接到数据库实例时，但您希望连接器只从特定逻辑数据库中的表捕获更改。
其他信息
- 从初始快照未捕获的表中捕获数据（无模式更改）
- 从没有由初始快照捕获的表捕获数据(schema 更改)
-
设置
schema.history.internal.store.only.captured.tables.ddl属性，以指定要从中捕获模式信息的表。 -
设置
schema.history.internal.store.only.captured.databases.ddl属性，以指定捕获模式更改的逻辑数据库。
2.7.2.1.3. 从初始快照未捕获的表中捕获数据（无模式更改）
在某些情况下，您可能希望连接器从最初快照未捕获其 schema 的表中捕获数据。根据连接器配置，初始快照可能会只捕获数据库中特定表的表模式。如果历史记录主题中没有表模式，连接器无法捕获表，并报告缺少的 schema 错误。
您可能仍然能够从表中捕获数据，但您必须执行额外的步骤来添加表模式。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 在连接器读取的最新更改表条目的 LSNs 和最新的更改表条目之间的表中不会应用架构更改。有关从具有结构化更改的新表捕获数据的详情，请参考 第 2.1.2.1.4 节 “从没有由初始快照捕获的表捕获数据(schema 更改)”。
流程
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
将以下更改应用到连接器配置：
（可选）将
schema.history.internal.store.only.captured.tables.ddl的值设置为false。此设置会导致快照捕获所有表的模式，并保证将来，连接器可以重建所有表的 schema 历史记录。
注意捕获所有表的模式的快照需要更多时间完成。
-
添加您希望连接器捕获到
table.include.list的表。 将
snapshot.mode设置为以下值之一：Initial-
重启连接器时，它会获取获取表数据和表结构的完整数据库快照。
如果您选择这个选项，请考虑将schema.history.internal.store.only.captured.tables.ddl属性的值设置为false，以便连接器捕获所有表的 schema。 schema_only- 重启连接器时，它会使用一个只捕获表模式的快照。与完整数据快照不同，此选项不会捕获任何表数据。如果要比使用完整快照更快重启连接器，请使用这个选项。
-
重启连接器。连接器完成
snapshot.mode指定的快照类型。 （可选）如果连接器在快照完成后执行
schema_only快照，启动 增量快照 以从您添加的表中捕获数据。连接器在继续从表中实时更改时运行快照。运行增量快照会捕获以下数据更改：- 对于之前捕获的连接器的表，增量 snapsot 捕获连接器停机期间发生的更改，即连接器停止的时间和当前重启之间的间隔。
- 对于新添加的表，增量快照会捕获所有现有表行。
2.7.2.1.4. 从没有由初始快照捕获的表捕获数据(schema 更改)
如果将架构更改应用到表，则在架构更改前提交的记录与更改后提交的结构不同。当 Debezium 捕获表中的数据时，它会读取 schema 历史记录，以确保它将正确的模式应用到每个事件。如果 schema 历史记录主题中没有 schema，连接器将无法捕获表，并会产生错误结果。
如果要捕获初始快照未捕获的表中的数据，并修改了表的 schema，您必须将 schema 添加到历史记录主题（如果还没有可用）。您可以通过运行新的模式快照或运行表的初始快照来添加架构。
先决条件
- 您需要使用一个模式来捕获数据，连接器在初始快照过程中不会捕获。
- 对表应用了一个架构更改，因此要捕获的记录没有统一的结构。
流程
- 初始快照捕获了所有表的模式(
storage.only.captured.tables.ddl设置为false) -
编辑
table.include.list属性，以指定您要捕获的表。 - 重启连接器。
- 如果要从新添加的表中捕获现有数据，则启动 增量快照。
-
编辑
- 初始快照没有捕获所有表的模式(storage
.only.captured.tables.ddl设置为true) 如果初始快照没有保存您要捕获的表的模式，请完成以下步骤之一：
- 流程 1：Schema 快照，后跟增量快照
在此过程中，连接器首先执行 schema 快照。然后，您可以启动增量快照，使连接器能够同步数据。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为schema_only。 -
编辑
table.include.list以添加您要捕获的表。
-
将
- 重启连接器。
- 等待 Debezium 捕获新表和现有表的模式。连接器停止后发生的数据更改不会被捕获。
- 为确保没有数据丢失，可启动 增量快照。
- 流程 2：初始快照，后跟可选的增量快照
在此过程中，连接器执行数据库的完整初始快照。与任何初始快照一样，在具有许多大表的数据库中，运行初始快照可能是一个耗时的操作。快照完成后，您可以选择性地触发增量快照，以捕获连接器离线期间发生的任何更改。
- 停止连接器。
-
删除由 schema.history.internal.
kafka.topic 属性指定的内部数据库架构历史记录主题。 清除配置的 Kafka Connect
offset.storage.topic中的偏移量。有关如何删除偏移的更多信息，请参阅 Debezium 社区常见问题解答。警告删除偏移应仅由具有操作内部 Kafka Connect 数据经验的高级用户执行。此操作可能具有破坏性，并且仅应作为最后的手段来执行。
-
编辑
table.include.list以添加您要捕获的表。 为连接器配置中的属性设置值，如以下步骤所述：
-
将
snapshot.mode属性的值设置为initial。 -
（可选）将
schema.history.internal.store.only.captured.tables.ddl设置为false。
-
将
- 重启连接器。连接器使用完整的数据库快照。快照完成后，连接器会过渡到 streaming。
- （可选）要捕获连接器脱机时更改的任何数据，请启动 增量快照。
2.7.2.2. 临时快照
默认情况下，连接器仅在首次启动后运行初始快照操作。按照这个初始快照，在正常情况下，连接器不会重复快照过程。任何以后更改连接器捕获的事件数据都会通过流处理。
然而，在某些情况下，在初始快照中获取的连接器可能会变得过时、丢失或不完整。为了提供总结表数据的机制，Debezium 包含一个执行临时快照的选项。您可能希望在 Debezium 环境中发生以下任何更改后执行临时快照：
- 连接器配置会被修改为捕获不同的表集合。
- Kafka 主题已删除，必须重建。
- 由于配置错误或某些其他问题导致数据损坏。
您可以通过启动所谓的 临时快照，为之前捕获的快照重新运行快照。临时快照需要使用 信号表。您可以通过向 Debezium 信号表发送信号请求来启动临时快照。
当您启动现有表的临时快照时，连接器会将内容附加到表已存在的主题中。如果删除了之前存在的主题，如果启用了 自动主题创建，Debezium 可以自动创建主题。
临时快照信号指定要包含在快照中的表。快照可以捕获数据库的全部内容，或者仅捕获数据库中表的子集。此外，快照也可捕获数据库中表的内容的子集。
您可以通过向信号表发送 execute-snapshot 消息来指定要捕获的表。将 execute-snapshot 信号的类型设置为 incremental 或 blocking，并提供快照中包含的表名称，如下表所述：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
指定您要运行的快照类型。 |
|
| N/A |
包含与快照中包含的表的完全限定域名匹配的正则表达式的数组。 |
|
| N/A |
可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
|
|
| N/A | 可选字符串，用于指定连接器在快照过程中用作表的主键的列名称。 |
触发临时增量快照
您可以通过向信号表添加带有 execute-snapshot 信号类型的条目，或者向 Kafka 信号发送信号消息 来启动临时增量快照。连接器处理消息后，它会开始快照操作。快照进程读取第一个和最后一个主键值，并使用这些值作为每个表的开始和端点。根据表中的条目数量以及配置的块大小，Debezium 会将表分成块，并持续持续对每个块进行快照。
如需更多信息，请参阅 增加快照。
触发临时阻塞快照
您可以通过在信号表或信号主题中添加带有 execute-snapshot 信号类型的条目来启动临时阻塞快照。连接器处理消息后，它会开始快照操作。连接器会临时停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，连接器会恢复流。
如需更多信息，请参阅 块快照。
2.7.2.3. 增量快照
每个 SQL Server 服务器或数据库都配置为使用特定的 collation，它决定了字符数据的存储方式、排序、比较和显示。某些 collation 组的排序规则，如 SQL Server collations (SQLvdsm) 与 Unicode 排序算法不兼容。在某些情况下，不兼容的排序规则可能会导致在连接器运行临时快照时丢失数据。例如，如果 SQL Server 配置为发送字符串为 Unicode （即，连接属性 sendStringParametersAsUnicode 设置为 true），则连接器可在快照期间跳过记录。要在临时快照期间防止丢失的数据，请将 driver.sendStringParametersAsUnicode connection string 属性的值设置为 false。
有关使用 sendStringParametersAsUnicode 属性的更多信息，请参阅 SQL Server 连接属性文档。
为了在管理快照方面提供灵活性，Debezium 包含一个补充快照机制，称为 增量快照。增量快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
在增量快照中，而不是像初始快照一样捕获数据库的完整状态，而是在一系列可配置的块中捕获每个表。您可以指定您希望快照捕获的表 以及每个块的大小。块大小决定了快照在数据库的每个获取操作期间收集的行数。增量快照的默认块大小是 1024 行。
当增量快照进行时，Debezium 使用水位线来跟踪其进度，维护其捕获的每个表行的记录。与标准初始快照过程相比，这个分阶段方法捕获数据具有以下优点：
- 您可以并行运行带有流数据捕获的增量快照，而不是延迟流，直到快照完成为止。连接器将继续在整个快照过程中从更改日志捕获接近实时事件，且操作都会阻止另一个事件。
- 如果增量快照的进度中断，您可以在不丢失任何数据的情况下恢复它。在进程恢复后，快照从它停止的点开始，而不是从开始重新捕获表。
-
您可以随时根据需要运行增量快照，并根据需要重复这个过程以适应数据库更新。例如，您可以在修改连接器配置后重新运行快照，以将表添加到其
table.include.list属性中。
增量快照过程
当您运行增量快照时，Debezium 按主密钥对每个表进行排序，然后根据 配置的块大小 将表分成块。通过块工作的块，然后捕获块中的每个表行。对于它捕获的每行，快照会发出 READ 事件。该事件代表了块开始快照时所在行的值。
当快照进行时，其他进程可能会继续访问数据库，可能会修改表记录。要反映此类更改，INSERT、UPDATE 或 DELETE 操作会按预期提交到事务日志。同样，持续 Debezium 流过程会继续检测到这些更改事件，并将对应的更改事件记录发送到 Kafka。
Debezium 如何处理具有相同主键的记录冲突
在某些情况下，streaming 进程发出的 UPDATE 或 DELETE 事件会按顺序接收。也就是说，流处理可能会发出一个事件，在快照捕获了包含该行的 READ 事件前修改表行。当快照最终为行发出对应的 READ 事件时，其值已经被取代。为确保以正确的逻辑顺序处理出序列的增量快照事件，Debezium 采用缓冲方案来解决冲突。只有在快照事件和流事件之间冲突后，才会解析 Debezium 向 Kafka 发出事件记录。
快照窗口
为了帮助解决 late-arriving READ 事件和修改同一表行之间的冲突，Debezium 会使用一个所谓的 快照窗口。快照窗口分离间隔，在此期间会捕获指定表块的数据。在块的快照窗口打开前，Debezium 会遵循其通常的行为，并将事件从下游直接发送到目标 Kafka 主题。但是，从为特定块的快照打开，直到它关闭为止，Deduplication 会执行重复数据删除步骤来解决具有相同主键的事件之间的冲突。
对于每个数据收集，Debebe 会发出两种类型的事件，并将它们的记录存储在单个目标 Kafka 主题中。它直接从表捕获的快照记录被发送为 READ 操作。同时，当用户继续更新数据收集中的记录，并且更新事务日志以反映每个提交，Debezium 会为每个更改发出 UPDATE 或 DELETE 操作。
当快照窗口打开时，Debebe 开始处理快照块，它会向内存缓冲提供快照记录。在快照窗口中，缓冲区中 READ 事件的主键与传入流事件的主键进行比较。如果没有找到匹配项，则流的事件记录直接发送到 Kafka。如果 Debezium 检测到匹配项，它会丢弃 buffered READ 事件，并将流记录写入目标主题，因为以逻辑方式取代静态快照事件。在块的快照窗口关闭后，缓冲区仅包含没有相关事务日志事件的 READ 事件。Debezium 将这些剩余的 READ 事件发送到表的 Kafka 主题。
连接器会为每个快照块重复这个过程。
目前，您可以使用以下任一方法启动增量快照：
SQL Server 的 Debezium 连接器不支持增量快照运行时的 schema 更改。
2.7.2.3.1. 触发增量快照
要启动增量快照，您可以发送 临时快照信号 到源数据库上的信号表。您可以提交快照信号，作为 SQL INSERT 查询。
在 Debezium 检测到信号表中的更改后，它会读取信号，并运行请求的快照操作。
您提交的查询指定要包含在快照中的表，并可选择性地指定快照操作的类型。Debezium 目前支持 增量 和 阻塞 快照类型。
要指定要包含在快照中的表，提供一个列出表的 data-collections 数组，或用于匹配表的正则表达式数组，例如：
{"data-collections": ["public.MyFirstTable", "public.MySecondTable"]}
增量快照信号的 data-collections 数组没有默认值。如果 data-collections 数组为空，Debebe 会解释空数组，意味着不需要任何操作，且不会执行快照。
如果要包含在快照中的表的名称包含一个点(.)、空格或其它非字母数字字符，则必须使用双引号转义表名称。
例如，若要将 公共 模式中存在的表包含在 db1 数据库中，并且名称为 My.Table，请使用以下格式 ："db1.public.\"My.Table\" "。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道触发增量快照
发送 SQL 查询，将临时增量快照请求添加到信号表中：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
Copy to Clipboard Copied! Toggle word wrap Toggle overflow 命令中的
id、type和data参数的值 与信号表的字段 相对应。
下表描述了示例中的参数：Expand 表 2.162. SQL 命令中的字段描述，用于将增量快照信号发送到信号表 项 值 描述 1
database.schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。相反，在快照过程中，Debebe 会生成自己的id字符串作为水位线信号。3
execute-snapshottype参数指定信号要触发的操作。
4
data-collections信号的必需组件，用于指定表名称或正则表达式数组，以匹配快照中包含的表名称。
数组列出了使用格式database.schema.table的正则表达式，以匹配表的完全限定域名。此格式与您用来指定连接器 信号表的名称相同。5
incrementaldata字段的可选类型组件，用于指定要运行的快照操作类型。
有效值为incremental和blocking值。
如果没有指定值，连接器默认为执行增量快照。6
additional-conditions可选数组，指定连接器评估的一组额外条件，以确定要包含在快照中的记录子集。
每个额外条件都是带有data-collection和filter属性的对象。您可以为每个数据收集指定不同的过滤器。
请参阅data-collection属性是过滤器应用到的数据收集的完全限定域名。有关additional-conditions参数的详情，请参考 第 2.7.2.3.2 节 “使用附加条件运行临时增量快照”。
2.7.2.3.2. 使用附加 条件运行临时增量快照
如果您希望快照只在表中包括内容子集，您可以通过将 additional-conditions 参数附加到快照信号来修改信号请求。
对典型快照的 SQL 查询采用以下格式：
SELECT * FROM <tableName> ....
SELECT * FROM <tableName> ....
通过添加 additional-conditions 参数，您可以在 SQL 查询中附加 WHERE 条件，如下例所示：
SELECT * FROM <data-collection> WHERE <filter> ....
SELECT * FROM <data-collection> WHERE <filter> ....以下示例显示了向信号表发送带有额外条件的临时增量快照请求的 SQL 查询：
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
INSERT INTO <signalTable> (id, type, data) VALUES ('<id>', '<snapshotType>', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"<snapshotType>","additional-conditions":[{"data-collection": "<fullyQualfiedTableName>", "filter": "<additional-condition>"}]}');
例如，假设您有一个包含以下列的 products 表：
-
ID（主密钥） -
color -
quantity
如果您需要 product 表的增量快照，其中只包含 color=blue 的数据项，您可以使用以下 SQL 语句来触发快照：
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue"}]}');
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue"}]}');
additional-conditions 参数还允许您传递基于多个列的条件。例如，使用上例中的 product 表，您可以提交查询来触发增量快照，该快照仅包含 color=blue 和 quantity>10 的项数据：
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue AND quantity>10"}]}');
INSERT INTO db1.myschema.debezium_signal (id, type, data) VALUES('ad-hoc-1', 'execute-snapshot', '{"data-collections": ["db1.schema1.products"],"type":"incremental", "additional-conditions":[{"data-collection": "db1.schema1.products", "filter": "color=blue AND quantity>10"}]}');以下示例显示了连接器捕获的增量快照事件的 JSON。
例 2.48. 增量快照事件消息
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定要运行的快照操作类型。 |
| 2 |
|
指定事件类型。 |
2.7.2.3.3. 使用 Kafka 信号频道触发增量快照
您可以向 配置的 Kafka 主题 发送消息，以请求连接器来运行临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
信号类型是 execute-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 支持 |
|
| N/A |
以逗号分隔的正则表达式，与快照中包含的表的完全限定域名匹配。 |
|
| N/A |
可选的附加条件数组，用于指定连接器评估以指定快照中包含的记录子集的条件。 |
例 2.49. execute-snapshot Kafka 信息
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["{collection-container}.table1", "{collection-container}.table2"], "type": "INCREMENTAL"}}`带有额外条件的临时增量快照
Debezium 使用 additional-conditions 字段来选择表内容的子集。
通常，当 Debezium 运行快照时，它会运行 SQL 查询，例如：
SELECT * FROM < ;tableName> ….
当快照请求包含 additional-conditions 属性时，属性的 data-collection 和 filter 参数会附加到 SQL 查询中，例如：
SELECT * FROM < ;data-collection> WHERE & lt;filter> ….
例如，如果一个带有列 ID （主键）、颜色 和品牌 的 products 表，如果您希望快照只包含 color='blue' 的内容，当请求快照时，您可以添加 additional-conditions 属性来过滤内容：
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue'"}]}}`
您还可以使用 additional-conditions 属性来根据多个列传递条件。例如，使用与上例中的相同 product 表，如果您希望快照只包含 color='blue' 和 brand='MyBrand' 的 表中的内容，您可以发送以下请求：
products
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`
Key = `test_connector`
Value = `{"type":"execute-snapshot","data": {"data-collections": ["db1.schema1.products"], "type": "INCREMENTAL", "additional-conditions": [{"data-collection": "db1.schema1.products" ,"filter":"color='blue' AND brand='MyBrand'"}]}}`2.7.2.3.4. 停止增量快照
在某些情况下，可能需要停止增量快照。例如，您可能意识到快照没有被正确配置，或者您可能要确保资源可用于其他数据库操作。您可以通过向源数据库上的信号发送信号来停止已经运行的快照。
您可以通过在 SQL INSERT 查询中发送停止快照信号，向信号表提交停止快照信号。stop-snapshot 信号将快照操作的类型指定为 增量，并选择性地指定要从当前运行的快照中省略的表。在 Debezium 检测到信号表中的更改后，它会读取信号，并在进行中时停止增量快照操作。
其他资源
您还可以通过向 Kafka 信号发送 JSON 消息来停止增量快照。
先决条件
启用信号。
- 源数据库中存在信号数据收集。
-
信号数据收集在
signal.data.collection属性中指定。
使用源信号频道停止增量快照
发送 SQL 查询以停止临时增量快照到信号表：
INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');INSERT INTO <signalTable> (id, type, data) values ('<id>', 'stop-snapshot', '{"data-collections": ["<fullyQualfiedTableName>","<fullyQualfiedTableName>"],"type":"incremental"}');Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
INSERT INTO db1.myschema.debezium_signal (id, type, data) values ('ad-hoc-1', 'stop-snapshot', '{"data-collections": ["db1.schema1.table1", "db1.schema1.table2"], "type":"incremental"}');INSERT INTO db1.myschema.debezium_signal (id, type, data)1 values ('ad-hoc-1',2 'stop-snapshot',3 '{"data-collections": ["db1.schema1.table1", "db1.schema1.table2"],4 "type":"incremental"}');5 Copy to Clipboard Copied! Toggle word wrap Toggle overflow signal 命令中的
id、type和data参数的值与 信号表的字段相对应。
下表描述了示例中的参数：Expand 表 2.165. SQL 命令中的字段描述，用于将停止增量快照信号发送到信号表 项 值 描述 1
database.schema.debezium_signal指定源数据库上信号表的完全限定名称。
2
ad-hoc-1id参数指定一个任意字符串，它被分配为信号请求的id标识符。
使用此字符串来识别将日志消息记录到信号表中的条目。Debezium 不使用这个字符串。3
stop-snapshot指定
type参数，指定信号要触发的操作。
4
data-collections信号的可选组件，用于指定表名称或正则表达式数组，以匹配要从快照中删除的表名称。
数组列出了正则表达式，该表达式通过其完全限定名称匹配表，格式为database.schema.table如果您从
data字段省略这个组件，信号将停止正在进行的整个增量快照。5
incremental信号的必需组件，用于指定要停止的快照操作类型。
目前，唯一有效的选项为增量。
如果没有指定类型值，信号将无法停止增量快照。
2.7.2.3.5. 使用 Kafka 信号频道停止增量快照
您可以向 配置的 Kafka 信号主题 发送信号消息，以停止临时增量快照。
Kafka 消息的密钥必须与 topic.prefix 连接器配置选项的值匹配。
消息的值是带有 type 和 data 字段的 JSON 对象。
signal 类型是 stop-snapshot，data 字段必须具有以下字段：
| 字段 | 默认 | 值 |
|---|---|---|
|
|
|
要执行的快照的类型。目前 Debezium 只支持 |
|
| N/A |
可选的、以逗号分隔的正则表达式，与表的完全限定名称匹配，表名称或正则表达式，以匹配要从快照中删除的表名称。 |
以下示例显示了典型的 stop-snapshot Kafka 信息：
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.schema1.table1", "db1.schema1.table2"], "type": "INCREMENTAL"}}`
Key = `test_connector`
Value = `{"type":"stop-snapshot","data": {"data-collections": ["db1.schema1.table1", "db1.schema1.table2"], "type": "INCREMENTAL"}}`2.7.2.4. 阻塞快照
为了在管理快照方面提供更多灵活性，Debezium 包含一个额外的临时快照机制，称为 阻塞快照。阻塞快照依赖于 Debezium 机制 向 Debezium 连接器发送信号。
阻塞快照的行为与 初始快照 相似，但您可以在运行时触发快照。
您可能想要在以下情况下运行阻塞快照，而不是使用标准初始快照过程：
- 您可以添加新表，并在连接器运行时完成快照。
- 您可以添加大表，并且您希望快照在短时间内完成，而不是通过增量快照完成。
阻塞快照过程
当您运行阻塞快照时，Debebe 会停止流，然后启动指定表的快照，遵循它在初始快照过程中使用的同一进程。快照完成后，会恢复流。
配置快照
您可以在信号 的数据 组件中设置以下属性：
- data-collections ：指定哪个表必须是快照
additional-conditions ：您可以为不同的表指定不同的过滤器。
-
data-collection属性是要应用过滤器的表的完全限定域名。 -
filter属性将具有与snapshot.select.statement.overrides中使用的相同值
-
例如：
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}
{"type": "blocking", "data-collections": ["schema1.table1", "schema1.table2"], "additional-conditions": [{"data-collection": "schema1.table1", "filter": "SELECT * FROM [schema1].[table1] WHERE column1 = 0 ORDER BY column2 DESC"}, {"data-collection": "schema1.table2", "filter": "SELECT * FROM [schema1].[table2] WHERE column2 > 0"}]}可能的副本
您发送信号触发快照的时间之间可能会有延迟，以及流停止和快照启动时的时间。因此，在快照完成后，连接器可能会发出一些由快照捕获的重复记录的事件记录。
2.7.2.5. Debezium SQL Server 连接器如何读取更改数据表
当连接器首次启动时，它会获取捕获表的结构快照，并将此信息保留至其内部数据库架构历史记录主题。然后，连接器为每个源表标识一个更改表，并完成以下步骤。
- 对于每个更改表，连接器读取最后一次存储的最大 LSN 和当前最大 LSN 之间创建的所有更改。
- 连接器根据其提交 LSN 的值以升序对读取的更改进行排序，并更改 LSN。这种排序顺序确保 Debezium 按照与数据库中发生的相同顺序重新执行更改。
- 连接器传递提交，并将 LSNs 作为偏移改为 Kafka Connect。
- 连接器存储最大 LSN 并从第 1 步中重启进程。
重启后，连接器会从其读取的最后偏移（提交并更改 LSN）中恢复处理。
连接器可以检测是否已为包含的源表启用或禁用 CDC，并调整其行为。
2.7.2.6. 数据库中没有记录的最大 LSN
在某些情况下，没有最大 LSN 在数据库中记录，因为：
- SQL Server Agent 没有运行
- change 表中还没有记录任何更改
- 数据库具有较少的活动，cdc 清理作业会定期清除 cdc 表中的条目
因此，由于运行的 SQL Server Agent 是前提条件，因此不会遇到真正问题（否 2 和 3. 是正常的情况）。
为了缓解此问题并区分 No 1. 和其他用户，SQL Server Agent 的状态通过以下查询 "SELECT CASE WHEN dss.[status]=4 THEN 1 ELSE 0 END AS isRunning FROM [:db].dm_server_services dss WHERE dss WHERE dss.[servicename] LIKE N'SQL Server (%'SQL'SQL Server Agent) （%".如果 SQL Server Agent 未运行，则会在日志中写入一个 ERROR："No maximum LSN record in the database; SQL Server Agent not running"。
运行状态查询的 SQL Server Agent 需要 VIEW SERVER STATE 服务器权限。如果您不想向配置的用户授予这个权限，您可以选择通过 database.sqlserver.agent.status.query 属性配置您自己的查询。您可以定义一个函数，它返回 true 或 1，如果 SQL Server Agent 在运行（其他情况返回 false 或 0）并安全地使用高级别权限而无需对它们进行授权，如 What minimum permissions do I need to provide to a user so that it can check the status of SQL Server Agent Service? 或 Safely and Easily Use High-Level Permissions Without Granting Them to Anyone: Server-level 所述。query 属性的配置应类似：database.sqlserver.agent.status.query=SELECT [#db].func_is_sql_server_agent_running() - 您需要使用 [#db] a作为数据库名称的占位符。
2.7.2.7. Debezium SQL Server 连接器的限制
SQL Server 特别要求基本对象是表，以便创建更改捕获实例。因此，SQL Server 不支持从索引视图(aka. materialized 视图)捕获更改，因此 Debezium SQL Server 连接器。
2.7.2.8. 接收 Debezium SQL Server 更改事件记录的 Kafka 主题的默认名称
默认情况下，SQL Server 连接器将所有 INSERT、UPDATE 和 DELETE 操作的事件写入一个特定于该表的单个 Apache Kafka 主题。连接器使用以下惯例命名更改事件主题： < topicPrefix> . <schemaName& gt; . <tableName>
以下列表提供了默认名称组件的定义：
- topicPrefix
-
服务器的逻辑名称，如
topic.prefix配置属性所指定。 - schemaName
- 发生更改事件的数据库架构的名称。
- tableName
- 发生更改事件的数据库表的名称。
例如，如果 fulfillment 是逻辑服务器名称，dbo 是 schema 名称，数据库包括名为 products, products_on_hand, customers, 和 orders 的表，连接器将更改事件发送到以下 Kafka 主题：
-
fulfillment.testDB.dbo.products -
fulfillment.testDB.dbo.products_on_hand -
fulfillment.testDB.dbo.customers -
fulfillment.testDB.dbo.orders
连接器应用类似的命名约定来标记其内部数据库架构历史记录主题、架构更改主题 和事务元数据主题。
如果默认主题名称不满足您的要求，您可以配置自定义主题名称。要配置自定义主题名称，您可以在逻辑主题路由 SMT 中指定正则表达式。有关使用逻辑主题路由 SMT 自定义主题命名的更多信息，请参阅 主题路由。
2.7.2.9. Debezium SQL Server 连接器如何处理数据库架构更改
当数据库客户端查询数据库时，客户端将使用数据库的当前架构。但是，可以随时更改数据库架构，这意味着连接器必须能够识别每次插入、更新或删除操作时的 schema。另外，连接器不一定将当前模式应用到每个事件。如果事件相对旧，则在应用当前模式之前记录这些事件。
为确保在模式更改后正确处理更改事件，Debezium SQL Server 连接器根据 SQL Server 更改表中的结构存储新模式的快照，这会镜像其关联的数据表的结构。连接器在数据库 schema 历史记录 Kafka 主题中存储表 schema 信息，以及操作的 LSN。连接器使用存储的模式表示来生成更改事件，每次插入、更新或删除操作时都会正确镜像表结构。
当连接器在崩溃或安全停止后重启时，它会从它读取的最后位置恢复 SQL Server CDC 表中的条目。根据连接器从数据库模式历史记录主题读取的架构信息，连接器应用在连接器重启的位置中存在的表结构。
如果您更新处于捕获模式的 Db2 表的 schema，您也可以更新相应更改表的 schema。您必须是一个具有升级权限的 SQL Server 数据库管理员，才能更新数据库架构。有关在 Debezium environmenbts 中更新 SQL Server 数据库模式的更多信息，请参阅 数据库 schema evolution。
数据库架构历史记录主题仅用于内部连接器。另外，连接器也可以将 schema 更改事件发送到面向消费者应用程序的不同主题。
其他资源
- 接收 Debezium 事件记录 的主题的默认名称。
2.7.2.10. Debezium SQL Server 连接器如何使用 schema 更改主题
对于启用了 CDC 的每个表，Debezium SQL Server 连接器存储应用到数据库中表的 schema 更改事件的历史记录。连接器将模式更改事件写入名为 < topicPrefix> 的 Kafka 主题，其中 topicPrefix 是 topic.prefix 配置属性中指定的逻辑服务器名称。
连接器发送到 schema 更改主题的消息包含一个有效负载，并可以选择包含更改事件消息的 schema。
模式更改事件的 schema 具有以下元素：
名称- 模式更改事件消息的名称。
type- 更改事件消息的类型。
version- 架构的版本。version 是一个整数，每次更改 schema 时都会递增。
fields- 更改事件消息中包含的字段。
示例：SQL Server 连接器模式更改主题的 Schema
以下示例显示了 JSON 格式的典型模式。
模式更改事件消息的有效负载包括以下元素：
databaseName-
将语句应用到的数据库的名称。
databaseName的值充当 message 键。 tableChanges-
架构更改后整个表模式的结构化表示。
tableChanges字段包含一个数组，其中包含表的每列条目。由于结构化表示以 JSON 或 Avro 格式显示数据，因此用户可以轻松地读取消息，而无需首先通过 DDL 解析器处理它们。
当连接器被配置为捕获表时，它会存储表的模式更改历史记录，不仅存储在 schema 更改主题中，还存储在内部数据库架构历史记录主题中。内部数据库架构历史记录主题仅用于连接器，它不用于直接使用应用程序。确保需要针对 schema 更改通知的应用程序只消耗了来自 schema 更改主题的信息。
连接器发送到其 schema 更改主题的消息格式处于 outcubating 状态，并可在不通知的情况下更改。
当发生以下事件时，Debebe Debezium 会向 schema 更改主题发送一条消息：
- 您可以为表启用 CDC。
- 您可以为表禁用 CDC。
- 您可以按照 schema evolution 过程更改启用 CDC 的表的结构。
示例：向 SQL Server 连接器模式更改主题发送的消息
以下示例显示了 schema 更改主题中的消息。消息包含表 schema 的逻辑表示。
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 显示连接器处理事件的时间字段。该时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 在源对象中，ts_ms 表示更改在数据库中的时间。通过将 payload.source.ts_ms 的值与 payload.ts_ms 的值进行比较，您可以确定源数据库更新和 Debezium 之间的滞后。 |
| 2 |
| 标识包含更改的数据库和模式。 |
| 3 |
|
对于 SQL Server 连接器，始终为 |
| 4 |
| 包含 DDL 命令生成的架构更改的一个或多个项目的数组。 |
| 5 |
| 描述更改类型。该值是以下之一：
|
| 6 |
| 创建、更改或丢弃的表的完整标识符。 |
| 7 |
| 代表应用的更改后的表元数据。 |
| 8 |
| 编写表主键的列列表。 |
| 9 |
| changed 表中每个列的元数据。 |
| 10 |
| 每个表更改的自定义属性元数据。 |
在连接器发送到 schema 更改主题的消息中，键是包含 schema 更改的数据库的名称。在以下示例中，payload 字段包含键：
2.7.2.11. Debezium SQL Server 连接器数据更改事件的描述
Debezium SQL Server 连接器为每个行级 INSERT、UPDATE 和 DELETE 操作生成数据更改事件。每个事件包含一个键和值。键和值的结构取决于更改的表。
Debezium 和 Kafka Connect 围绕 事件消息的持续流 设计。但是，这些事件的结构可能会随时间变化，用户很难处理。要解决这个问题，每个事件都包含其内容的 schema，或者如果您使用 schema registry，消费者可以用来从 registry 获取 schema 的模式 ID。这使得每个事件自包含。
以下框架 JSON 显示了更改事件的基本四部分。但是，如何配置您选择在应用程序中使用的 Kafka Connect 转换器决定了更改事件中的这四个部分的表示。只有在将转换器配置为生成它时，schema 字段才会处于 change 事件中。同样，只有在将转换器配置为生成它时，事件键和事件有效负载才会处于更改事件中。如果您使用 JSON 转换程序，并将其配置为生成所有四个基本更改事件部分，则更改事件具有此结构：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
第一个 |
| 2 |
|
第一个 |
| 3 |
|
第二个 |
| 4 |
|
第二个 |
默认情况下，连接器流将事件记录改为带有与事件原始表相同的名称的主题。如需更多信息，请参阅 主题名称。
SQL Server 连接器确保所有 Kafka Connect 模式名称都遵循 Avro 模式名称格式。这意味着逻辑服务器名称必须以拉丁字母或下划线开头，即 a-z、A-Z 或 _。逻辑服务器名称和表名称中的每个字符都必须是拉丁字母、数字或下划线，即 a-z、A-Z、0-9 或 \_。如果存在无效的字符，它将被一个下划线字符替代。
如果逻辑服务器名称、数据库名称或表名称包含无效字符，则这可能会导致意外冲突，并且区分名称的唯一字符无效，因此用下划线替换。
有关更改事件的详情，请查看以下主题：
2.7.2.11.1. 关于 Debezium SQL Server 更改事件中的键
更改事件的密钥包含更改表键和更改行的实际键的 schema。在连接器创建事件时，schema 及其对应有效负载都包含更改表的主键（或唯一键约束）中每个列的字段。
请考虑以下 customers 表，后面是此表的更改事件关键示例。
表示例
更改事件键示例
捕获 customer 表更改的每个更改事件都有相同的事件关键模式。只要 customers 表有以前的定义，可以捕获 customer 表更改的事件都有以下关键结构（JSON），它类似于：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
键的 schema 部分指定一个 Kafka Connect 模式，它描述了键的 |
| 2 |
|
指定 |
| 3 |
|
指明事件键是否在其 |
| 4 |
|
定义键有效负载结构的 schema 名称。这个模式描述了更改的表的主密钥的结构。键架构名称的格式是 connector-name.database-schema-name.table-name.
|
| 5 |
|
包含生成此更改事件的行的密钥。在本例中，键包含一个 |
2.7.2.11.2. 关于 Debezium SQL Server 更改事件中的值
更改事件中的值比键复杂一些。与键一样，值也有一个 schema 部分和一个 payload 部分。schema 部分包含描述 payload 部分的 Envelope 结构的 schema，包括其嵌套字段。更改创建、更新或删除数据的操作的事件，它们都有带有 envelope 结构的值 payload。
考虑用于显示更改事件键示例相同的示例表：
每个事件类型都会描述更改此表的值部分。
创建 事件
以下示例显示了一个更改事件的值部分，连接器为在 customer 表中创建数据的操作生成的更改事件的值部分：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
| 值的 schema，它描述了值有效负载的结构。在连接器为特定表生成的更改事件时，更改事件的值 schema 都相同。 |
| 2 |
|
在 |
| 3 |
|
|
| 4 |
|
|
| 5 |
|
值的实际数据。这是更改事件提供的信息。 |
| 6 |
|
指定事件发生前行状态的可选字段。当 |
| 7 |
|
指定事件发生后行状态的可选字段。在本例中， |
| 8 |
| 描述事件源元数据的强制字段。此字段包含可用于将此事件与其他事件进行比较的信息，以及事件的来源、发生事件的顺序以及事件是否是同一事务的一部分。源元数据包括：
|
| 9 |
|
描述导致连接器生成事件的操作类型的强制字符串。在本例中，
|
| 10 |
|
显示连接器处理事件的时间字段。在事件消息 envelope 中，时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新 事件
示例 customers 表中一个更新的改变事件的值有与那个表的 create 事件相同的模式。同样，事件值的有效负载具有相同的结构。但是，事件值 payload 在更新 事件中包含不同的值。以下是当连接器在 customers 表中为更新生成的更改事件值的示例：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行状态的可选字段。在 update 事件值中， |
| 2 |
|
指定事件发生后行状态的可选字段。您可以比较 |
| 3 |
|
描述事件源元数据的强制字段。
|
| 4 |
|
描述操作类型的强制字符串。在 update 事件值中， |
| 5 |
|
显示连接器处理事件的时间字段。在事件消息 envelope 中，时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
更新行主/唯一键的列会更改行键的值。当密钥更改时，Debe be 会输出三个 事件：一个 delete 事件和一个 tombstone 事件，其中包含行的旧键，后跟一个带有行的新键的 create 事件。
删除 事件
delete 更改事件中的值与为同一表的 create 和 update 事件相同的 schema 部分。示例 customer 表的 delete 事件中 payload 部分类似如下：
| 项 | 字段名称 | 描述 |
|---|---|---|
| 1 |
|
指定事件发生前行的状态的可选字段。在一个 delete 事件值中， |
| 2 |
|
可选字段，用于指定事件发生后行的状态。在一个 delete 事件值中， |
| 3 |
|
描述事件源元数据的强制字段。在一个 delete 事件值中，
|
| 4 |
|
描述操作类型的强制字符串。 |
| 5 |
|
显示连接器处理事件的时间字段。在事件消息 envelope 中，时间基于运行 Kafka Connect 任务的 JVM 中的系统时钟。 |
SQL Server 连接器事件设计为与 Kafka 日志压缩 一起使用。日志压缩支持删除一些旧的信息，只要至少保留每个密钥的最新消息。这可让 Kafka 回收存储空间，同时确保主题包含完整的数据集，并可用于重新载入基于密钥的状态。
tombstone 事件
删除行时，delete 事件值仍可用于日志压缩，因为 Kafka 您可以删除具有相同键的所有之前信息。但是，为了使 Kafka 删除具有相同键的所有信息，消息值必须是 null。为了实现此目的，在 Debezium 的 SQL Server 连接器发出 delete 事件后，连接器会发出一个特殊的 tombstone 事件，它具有相同的键但一个 null 值。
2.7.2.12. Debezium SQL Server 连接器生成的事件代表事务边界
Debezium 可以生成代表事务边界的事件，以及丰富的数据更改事件消息。
Debezium 注册并接收部署连接器后发生的事务的元数据。部署连接器前发生的事务元数据不可用。
数据库事务由一个声明块表示，该块包含在 BEGIN 和 END 关键字之间。Debezium 为每个事务中的 BEGIN 和 END 分隔符生成事务边界事件。事务边界事件包含以下字段：
status-
BEGIN或END. id- 唯一事务标识符的字符串表示。
ts_ms-
数据源的事务边界事件(
BEGIN或END事件)的时间。如果数据源没有向 Debezium 提供事件时间，则字段代表 Debezium 处理事件的时间。 event_count（用于END事件）- 事务处理的事件总数。
data_collections（用于END事件）-
一组
data_collection和event_count元素，用于指示连接器为来自数据收集的更改发出的事件数。
Debezium 无法可靠地识别事务何时终止。因此，只有在另一个事务到达的第一个事件后，才会发出事务 结束 标记。在低流量系统中，这可能会导致延迟发布 END 标记。
以下示例显示了典型的事务边界消息：
示例：SQL Server 连接器事务边界事件
除非通过 topic.transaction 选项覆盖，否则事务事件将写入名为 <topic. prefix>。
.transaction 的主题
2.7.2.12.1. 更改数据事件增强
如果启用了事务元数据，数据消息 Envelope 会增加一个新的 transaction 字段。此字段以字段复合的形式提供有关每个事件的信息：
id- 唯一事务标识符的字符串表示
total_order- 事件在事务生成的所有事件中的绝对位置
data_collection_order- 事件在事务发送的所有事件中的 per-data 集合位置
以下示例显示了典型信息是什么：
2.7.2.13. Debezium SQL Server 连接器如何映射数据类型
Debezium SQL Server 连接器通过生成类似行表的事件来代表表行数据的更改。每个事件都包含字段来代表行的列值。事件表示操作的列值的方式取决于列的 SQL 数据类型。在事件中，连接器将每个 SQL Server 数据类型的字段映射到 字面类型和 语义类型 。
连接器可以将 SQL Server 数据类型映射到 字面 和 语义 类型。
- 字面类型
-
描述如何使用 Kafka Connect 模式类型（即
INT8,INT16,INT32,INT64,FLOAT32,FLOAT64,BOOLEAN,STRING,BYTES,ARRAY,MAP, 和STRUCT）来代表值。 - 语义类型
- 描述 Kafka Connect 模式如何使用字段的 Kafka Connect 模式名称捕获字段 的含义。
如果默认数据类型转换不满足您的需要，您可以为连接器 创建自定义转换器。
有关数据类型映射的更多信息，请参阅以下部分：
基本类型
下表显示了连接器如何映射基本 SQL Server 数据类型。
| SQL Server 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
| 不适用 |
|
|
|
|
|
|
|
|
在以下部分中描述了其他数据类型映射。
如果存在，则列的默认值将传播到对应的字段 Kafka Connect 模式。更改消息将包含字段的默认值（除非给出了一个明确的列值），因此应该很少需要从 schema 获取默认值。
临时值
SQL Server 的 DATETIMEOFFSET 数据类型（包含时区信息）以外的其他类型取决于 time.precision.mode 配置属性的值。当 time.precision.mode 配置属性设置为 adaptive （默认值），那么连接器将根据列的数据类型确定 temporal 类型的字面类型和语义类型，以便事件 准确 表示数据库中的值：
| SQL Server 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
当 time.precision.mode 配置属性设置为 connect 时，连接器将使用预定义的 Kafka Connect 逻辑类型。当消费者只了解内置 Kafka Connect 逻辑类型且无法处理变量精度时间值时，这很有用。另一方面，因为 SQL 服务器支持十分之一的微秒精度，带有 connect 时间精度模式的连接器将在有一个大于 3 的 fractional second precision 数据库列时丢失一些精度：
| SQL Server 数据类型 | 字面类型(schema 类型) | 语义类型(schema 名称)和备注 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
时间戳值
DATETIME,SMALLDATETIME 和 DATETIME2 类型代表一个没有时区信息的时间戳。这些列根据 UTC 转换为等同的 Kafka Connect 值。对于实例，DATETIME2 值 "2018-06-20 15:13:16.945104" 由值 "1529507596945104" 为 io.debezium.time.MicroTimestamp 代表。
请注意，运行 Kafka Connect 和 Debezium 的 JVM 时区不会影响此转换。
十进制值
Debezium 连接器根据 decimal.handling.mode 连接器配置属性的 设置来处理十进制。
- decimal.handling.mode=precise
Expand 表 2.174. 当 decimal.handling.mode=precise时映射 SQL Server 类型 字面类型(schema 类型) 语义类型（架构名称） NUMERIC[(P[,S])]BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。DECIMAL[(P[,S])]BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。SMALLMONEYBYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。金钱BYTESorg.apache.kafka.connect.data.Decimal
scale模式参数包括一个整数，它代表了十进制小数点移动了多少位。- decimal.handling.mode=double
Expand 表 2.175. Mappings when decimal.handling.mode=double SQL Server 类型 字面类型 语义类型 NUMERIC[(M[,D])]FLOAT64不适用
DECIMAL[(M[,D])]FLOAT64不适用
SMALLMONEY[(M[,D])]FLOAT64不适用
金钱[(M[,D])]FLOAT64不适用
- decimal.handling.mode=string
Expand 表 2.176. 当 decimal.handling.mode=string时映射 SQL Server 类型 字面类型 语义类型 NUMERIC[(M[,D])]字符串不适用
DECIMAL[(M[,D])]字符串不适用
SMALLMONEY[(M[,D])]字符串不适用
金钱[(M[,D])]字符串不适用
2.7.3. 设置 SQL Server 以运行 Debezium 连接器
要使 Debezium 从 SQL Server 表捕获更改事件，具有所需权限的 SQL Server 管理员必须首先运行查询以便在数据库上启用 CDC。然后，管理员必须为您希望 Debezium 捕获的每个表启用 CDC。
默认情况下，与 Microsoft SQL Server 的 JDBC 连接受 SSL 加密保护。如果没有为 SQL Server 数据库启用 SSL，或者在不使用 SSL 的情况下连接到数据库，您可以通过将连接器配置中的 database.encrypt 属性的值设置为 false 来禁用 SSL。
有关设置用于 Debezium 连接器的 SQL Server 的详情，请参考以下部分：
应用 CDC 后，它会捕获所有 INSERT、UPDATE 和 DELETE 操作，它们提交到启用了 CDC 的表。然后 Debezium 连接器可以捕获这些事件并将其发送到 Kafka 主题。
2.7.3.1. 在 SQL Server 数据库中启用 CDC
在为表启用 CDC 前，您必须为 SQL Server 数据库启用它。SQL Server 管理员通过运行系统存储的步骤启用 CDC。可使用 SQL Server Management Studio 或使用 Transact-SQL 运行系统存储的步骤。
先决条件
- 您是 SQL Server 系统管理员 固定服务器角色的成员。
- 您是数据库的 db_owner。
- SQL Server Agent 正在运行。
SQL Server CDC 功能只处理在用户创建的表中发生的更改。您不能在 SQL Server master 数据库上启用 CDC。
流程
- 在 SQL Server Management Studio 中的 View 菜单中，单击 Template Explorer。
- 在 Template Browser 中，展开 SQL Server Templates。
- 展开 Change Data Capture > Configuration，然后点 Enable Database for CDC。
-
在模板中，将
USE语句中的数据库名称替换为您要为 CDC 启用的数据库的名称。 运行存储的步骤
sys.sp_cdc_enable_db以启用 CDC 的数据库。为 CDC 启用数据库后，会创建一个带有名称
cdc的模式，以及 CDC 用户、元数据表和其他系统对象。以下示例演示了如何为数据库
MyDB启用 CDC：示例：为 CDC 模板启用 SQL Server 数据库
USE MyDB GO EXEC sys.sp_cdc_enable_db GO
USE MyDB GO EXEC sys.sp_cdc_enable_db GOCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.7.3.2. 在 SQL Server 表中启用 CDC
SQL Server 管理员必须在您要捕获的源表上启用更改数据捕获。必须为 CDC 启用数据库。要在表上启用 CDC，SQL Server 管理员为表运行存储的步骤 sys.sp_cdc_enable_table。存储的步骤可以使用 SQL Server Management Studio 运行，或者使用 Transact-SQL 来运行。必须为每个要捕获的表启用 SQL Server CDC。
先决条件
- 在 SQL Server 数据库上启用了 CDC。
- SQL Server Agent 正在运行。
-
您是
db_owner固定数据库角色的成员。
流程
- 在 SQL Server Management Studio 中的 View 菜单中，单击 Template Explorer。
- 在 Template Browser 中，展开 SQL Server Templates。
- 展开 Change Data Capture > Configuration，然后点 Enable Table Specifying Filegroup Option。
-
在模板中，将
USE语句中的表名称替换为您要捕获的表的名称。 运行存储的步骤
sys.sp_cdc_enable_table。以下示例演示了如何为表
MyTable启用 CDC：示例：为 SQL Server 表启用 CDC
Copy to Clipboard Copied! Toggle word wrap Toggle overflow <.> 指定要捕获的表的名称。<.> 指定角色
MyRole，您可以向其中添加您要为源表捕获列授予SELECT权限的用户。sysadmin或db_owner角色的用户还可以访问指定的更改表。将@role_name的值设置为NULL，仅允许sysadmin或db_owner中的成员具有捕获的信息。<.> 指定filegroup，其中 SQL Server 将更改表放在捕获的表。namedfilegroup必须已经存在。最好不要在用于源表的同一filegroup中找到更改表。
2.7.3.3. 验证用户是否可以访问 CDC 表
SQL Server 管理员可以运行系统存储的步骤来查询数据库或表来检索其 CDC 配置信息。存储的步骤可以使用 SQL Server Management Studio 运行，或者使用 Transact-SQL 来运行。
先决条件
-
对捕获实例的所有列都有
SELECT权限。db_owner数据库角色的成员可以查看所有定义的捕获实例的信息。 - 您拥有为查询包含的表信息定义的任何 gating 角色的成员。
流程
- 在 SQL Server Management Studio 中的 View 菜单中，单击 Object Explorer。
- 从 Object Explorer，展开 Databases，然后扩展您的数据库对象，如 MyDB。
- 展开 Programmability > Stored procedures > System Stored procedures。
运行
sys.sp_cdc_help_change_data_capture存储的步骤来查询表。查询应该不会返回空结果。
以下示例在数据库
MyDB上运行存储的步骤sys.sp_cdc_help_change_data_capture：示例：查询 CDC 配置信息表
USE MyDB; GO EXEC sys.sp_cdc_help_change_data_capture GO
USE MyDB; GO EXEC sys.sp_cdc_help_change_data_capture GOCopy to Clipboard Copied! Toggle word wrap Toggle overflow 查询返回为 CDC 启用的数据库中每个表的配置信息，其中包含调用者有权访问的更改数据。如果结果为空，请验证用户是否有访问捕获实例和 CDC 表的权限。
2.7.3.4. Azure 上的 SQL Server
Debezium SQL Server 连接器可用于 Azure 上的 SQL Server。有关在 Azure 上为 SQL Server 配置 CDC 并在 Debezium 中使用它的信息，请参阅此示例。https://learn.microsoft.com/en-us/samples/azure-samples/azure-sql-db-change-stream-debezium/azure-sql%2D%2Dsql-server-change-stream-with-debezium/
2.7.3.5. SQL Server 捕获作业代理配置对服务器负载和延迟的影响
当数据库管理员为源表启用更改数据捕获时，捕获作业代理开始运行。代理从事务日志读取新的更改事件记录，并将事件记录复制到更改数据表中。在源表中提交更改的时间，以及更改出现在相应更改表中的时间，始终有一个小的延迟间隔。这个延迟间隔代表源表中出现更改时的间隔，以及 Debezium 到 Apache Kafka 的流提供时的差距。
理想情况下，对于必须快速响应数据更改的应用程序，您希望在源和更改表之间保持关闭同步。您可能会认为，运行捕获代理以尽可能迅速地处理更改事件，从而导致吞吐量增加，并减少带有新事件记录的更改表（接近实时发生）。然而，这不一定如此。对于更直接的同步，需要支付性能损失。每次捕获作业代理查询数据库以获取新事件记录时，它会增加数据库主机上的 CPU 负载。服务器上的额外负载可能会对整体数据库性能产生负面影响，并可能会降低交易效率，特别是在数据库使用高峰时。
监控数据库指标非常重要，以便您知道数据库是否达到服务器不再支持捕获代理的活动级别。如果您注意到性能问题，有 SQL Server 捕获代理设置，您可以修改它们来帮助平衡数据库主机上的总体 CPU 负载，并具有可容忍的延迟。
2.7.3.6. SQL Server 捕获作业代理配置参数
在 SQL Server 上，控制捕获作业代理行为的参数在 SQL Server 表 msdb.dbo.cdc_jobs 中定义。如果您在运行捕获作业代理时遇到性能问题，请通过运行 sys.sp_cdc_change_job 存储的步骤并提供新值来调整捕获作业设置以降低 CPU 负载。
有关如何配置 SQL Server 捕获作业代理参数的具体指导超出了本文档的范围。
以下参数是修改用于 Debezium SQL Server 连接器的捕获代理行为的最显著：
pollinginterval- 指定捕获代理在日志扫描周期之间等待的秒数。
- 数值越高，可以减少数据库主机上的负载并增加延迟。
-
值
0指定扫描之间没有等待。 -
默认值为
5。
maxtrans-
指定每次日志扫描循环期间要处理的最大事务数。在捕获作业处理指定数量的事务后，它会在下一次扫描开始前暂停
pollinginterval指定的时间长度。 - 较低值可减少数据库主机上的负载并增加延迟。
-
默认值为
500。
-
指定每次日志扫描循环期间要处理的最大事务数。在捕获作业处理指定数量的事务后，它会在下一次扫描开始前暂停
maxscans-
指定捕获作业可以尝试捕获数据库事务日志的所有内容的扫描周期数量的限制。如果将
continuous参数设置为1，则作业会在恢复扫描前暂停pollinginterval指定的时间长度。 - 较低值可减少数据库主机上的负载并增加延迟。
-
默认值为
10。
-
指定捕获作业可以尝试捕获数据库事务日志的所有内容的扫描周期数量的限制。如果将
其他资源
- 有关捕获代理参数的更多信息，请参阅 SQL Server 文档。
2.7.4. 部署 Debezium SQL Server 连接器
您可以使用以下任一方法部署 Debezium SQL Server 连接器：
2.7.4.1. 使用 Streams for Apache Kafka 的 SQL Server 连接器部署
从 Debezium 1.7 开始，部署 Debezium 连接器的首选方法是使用 Streams for Apache Kafka 来构建包含连接器插件的 Kafka Connect 容器镜像。
在部署过程中，您要创建和使用以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR，并包含有关镜像中包含的连接器工件的信息。 -
提供包括连接器用来访问源数据库的信息的
KafkaConnectorCR。在 Apache Kafka 的 Streams 启动 Kafka Connect pod 后，您可以通过应用KafkaConnectorCR 来启动连接器。
在 Kafka Connect 镜像的构建规格中，您可以指定用于部署的连接器。对于每个连接器插件，您还可以指定您的部署可以使用的其他组件。例如，您可以添加 Apicurio Registry 工件或 Debezium 脚本组件。当 Apache Kafka 的 Streams 构建 Kafka Connect 镜像时，它会下载指定的工件，并将其合并到镜像中。
KafkaConnect CR 中的 spec.build.output 参数指定在存储生成的 Kafka Connect 容器镜像的位置。容器镜像可以存储在 Docker registry 中，也可以存储在 OpenShift ImageStream 中。要将镜像存储在 ImageStream 中，您必须在部署 Kafka Connect 前创建 ImageStream。镜像流不会被自动创建。
如果使用 KafkaConnect 资源创建集群，之后您无法使用 Kafka Connect REST API 创建或更新连接器。您仍然可以使用 REST API 来检索信息。
其他资源
- 在 OpenShift 中部署和管理 Apache Kafka Streams 中的配置 Kafka 连接。
- 在 OpenShift 中部署和管理 Apache Kafka 的 Streams 中自动构建新容器镜像。
对于 Apache Kafka 的早期版本，要在 OpenShift 上部署 Debezium 连接器，首先需要为连接器构建 Kafka Connect 镜像。在 OpenShift 上部署连接器的当前首选方法是使用 Apache Kafka 的 Streams 中的构建配置，来自动构建包含您要使用的 Debezium 连接器插件的 Kafka Connect 容器镜像。
在构建过程中，Apache Kafka Operator 的 Streams 将 KafkaConnect 自定义资源中的输入参数（包括 Debezium 连接器定义）转换为 Kafka Connect 容器镜像。构建会从 Red Hat Maven 存储库或其他配置的 HTTP 服务器下载必要的工件。
新创建的容器被推送到 .spec.build.output 中指定的容器 registry，并用于部署 Kafka Connect 集群。在 Apache Kafka 的 Streams 构建 Kafka Connect 镜像后，您可以创建 KafkaConnector 自定义资源来启动构建中包含的连接器。
先决条件
- 您可以访问安装了集群 Operator 的 OpenShift 集群。
- Apache Kafka Operator 的 Streams 正在运行。
- 部署了 Apache Kafka 集群，如 在 OpenShift 中部署和管理 Apache Kafka 的流 中所述。
- Kafka Connect 部署在 Apache Kafka 的 Streams 中
- 您有一个红帽构建的 Debezium 许可证。
-
OpenShift
ocCLI 客户端已安装，或者您可以访问 OpenShift Container Platform Web 控制台。 根据您要存储 Kafka Connect 构建镜像的方式，您需要 registry 权限或您必须创建 ImageStream 资源：
- 将构建镜像存储在镜像 registry 中，如 Red Hat Quay.io 或 Docker Hub
- 在 registry 中创建和管理镜像的帐户和权限。
- 将构建镜像存储为原生 OpenShift ImageStream
- ImageStream 资源部署到集群中，以存储新的容器镜像。您必须为集群显式创建 ImageStream。默认情况下，镜像流不可用。如需有关 ImageStreams 的更多信息，请参阅 OpenShift Container Platform 文档中的管理镜像流。
流程
- 登录 OpenShift 集群。
为连接器创建 Debezium
KafkaConnect自定义资源(CR)，或修改现有的资源。例如，使用名称dbz-connect.yaml创建KafkaConnectCR，用于指定metadata.annotations和spec.build属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
例 2.50. 定义包含 Debezium 连接器的
KafkaConnect自定义资源的dbz-connect.yaml文件在以下示例中，自定义资源被配置为下载以下工件：
- Debezium SQL Server 连接器存档。
- 红帽构建的 Apicurio Registry 归档。Apicurio Registry 是一个可选组件。只有在打算将 Avro serialization 与连接器一起使用时，才添加 Apicurio Registry 组件。
- Debezium 脚本 SMT 归档以及您要用于 Debezium 连接器的相关脚本引擎。SMT 归档和脚本语言依赖项是可选组件。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才添加这些组件。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.177. Kafka Connect 配置设置的描述 项 描述 1
将
strimzi.io/use-connector-resources注解设置为"true"，以便 Cluster Operator 使用KafkaConnector资源在此 Kafka Connect 集群中配置连接器。2
spec.build配置指定存储构建镜像的位置，并列出镜像中包含的插件，以及插件工件的位置。3
build.output指定存储新构建的镜像的 registry。4
指定镜像输出的名称和镜像名称。
output.type的有效值为docker，可推送到容器 registry （如 Docker Hub 或 Quay）或镜像流（用于将镜像推送到内部 OpenShift ImageStream）。要使用 ImageStream，必须将 ImageStream 资源部署到集群中。有关在 KafkaConnect 配置中指定build.output的更多信息，请参阅 {Name configuringStreamsOpenShift} 中的 Apache Kafka Build schema 参考。5
插件配置列出了您要包含在 Kafka Connect 镜像中的所有连接器。对于列表中的每个条目，指定一个插件名称，以及有关构建连接器所需的工件的信息。另外，对于每个连接器插件，您可以包括要用于连接器的其他组件。例如，您可以添加 Service Registry 工件或 Debezium 脚本组件。6
artifacts.type的值指定artifacts.url中指定的工件的文件类型。有效类型是zip、tgz、或jar。Debezium 连接器存档以.zip文件格式提供。type值必须与url字段中引用的文件类型匹配。7
artifacts.url的值指定 HTTP 服务器的地址，如 Maven 存储库，用于存储连接器工件的文件。Red Hat Maven 存储库中提供了 Debezium 连接器工件。OpenShift 集群必须有权访问指定的服务器。8
（可选）指定下载 Apicurio Registry 组件的工件
类型和url。包括 Apicurio Registry 工件，只有在您希望连接器使用 Apache Avro 来序列化事件键和值，使用红帽构建的 Apicurio Registry 的值，而不是使用默认的 JSON 转换。9
（可选）指定 Debezium 脚本 SMT 归档的工件
类型和url，以用于 Debezium 连接器。只有在打算使用 Debezium 的基于内容的路由 SMT 或 过滤 SMT 时才包括脚本 SMT。要使用脚本 SMT，您还必须部署 JSR 223 兼容脚本实施，如 groovy。10
（可选）指定与 JSR 223 脚本实施的 JAR 文件的工件
类型和url，这是 Debezium 脚本 SMT 所需的。重要如果您使用 Streams for Apache Kafka 将连接器插件合并到 Kafka Connect 镜像中，对于每个所需的脚本语言组件
artifacts.url必须指定 JAR 文件的位置，并且artifacts.type的值也必须设置为jar。无效的值会导致连接器在运行时失败。要启用将 Apache Groovy 语言与脚本 SMT 搭配使用，示例中的自定义资源会检索以下库的 JAR 文件：
-
groovy -
groovy-jsr223（脚本代理） -
groovy-json（用于解析 JSON 字符串的模块）
作为替代方案，Debezium 脚本 SMT 还支持使用 GraalVM JavaScript 的 JSR 223 实施。
输入以下命令将
KafkaConnect构建规格应用到 OpenShift 集群：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 根据自定义资源中指定的配置，Streams Operator 准备要部署的 Kafka Connect 镜像。
构建完成后，Operator 将镜像推送到指定的 registry 或 ImageStream，并启动 Kafka Connect 集群。您在配置中列出的连接器工件在集群中可用。创建一个
KafkaConnector资源来定义您要部署的每个连接器的实例。
例如，创建以下KafkaConnectorCR，并将它保存为sqlserver-inventory-connector.yaml例 2.51.
sqlserver-inventory-connector.yaml文件，为 Debezium 连接器定义KafkaConnector自定义资源Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.178. 连接器配置设置的描述 项 描述 1
要注册到 Kafka Connect 集群的连接器名称。
2
连接器类的名称。
3
可同时操作的任务数量。
4
连接器的配置。
5
主机数据库实例的地址。
6
数据库实例的端口号。
7
Debezium 用来连接到数据库的帐户名称。
8
Debezium 用来连接到数据库用户帐户的密码。
9
数据库实例或集群的主题前缀。
指定的名称只能从字母数字字符或下划线构成。
因为主题前缀用作从此连接器接收更改事件的 Kafka 主题的前缀，因此该名称在集群中的连接器中必须是唯一的。
如果您将连接器与 Avro 连接器集成，则此命名空间也用于相关的 Kafka Connect 模式的名称，以及对应的 Avro 模式的命名空间。10
连接器捕获更改事件的表列表。
运行以下命令来创建连接器资源：
oc create -n <namespace> -f <kafkaConnector>.yaml
oc create -n <namespace> -f <kafkaConnector>.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc create -n debezium -f sqlserver-inventory-connector.yaml
oc create -n debezium -f sqlserver-inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 连接器注册到 Kafka Connect 集群，并开始针对
KafkaConnectorCR 中的spec.config.database.dbname指定的数据库运行。连接器 pod 就绪后，Debezium 正在运行。
要部署 Debezium SQL Server 连接器，您必须构建包含 Debezium 连接器存档的自定义 Kafka Connect 容器镜像，然后将此容器镜像推送到容器 registry。然后，您需要创建以下自定义资源(CR)：
-
定义 Kafka Connect 实例的
KafkaConnectCR。CR 中的image属性指定您创建的容器镜像的名称，以运行 Debezium 连接器。您可以将此 CR 应用到部署 Red Hat Streams for Apache Kafka 的 OpenShift 实例。Apache Kafka 的流提供将 Apache Kafka 到 OpenShift 的 operator 和镜像。 -
定义 Debezium SQL Server 连接器的
KafkaConnectorCR。将此 CR 应用到应用KafkaConnectCR 的同一 OpenShift 实例。
先决条件
- SQL Server 正在运行，并且您完成了 设置 SQL Server 以使用 Debezium 连接器 的步骤。
- Apache Kafka 的流部署在 OpenShift 中，它正在运行 Apache Kafka 和 Kafka Connect。如需更多信息，请参阅在 OpenShift 中部署和管理 Apache Kafka的流
- podman 或 Docker 已安装。
-
您有在容器 registry （如
quay.io或docker.io）中创建和管理容器的帐户和权限，您要添加将运行 Debezium 连接器的容器。
流程
为 Kafka Connect 创建 Debezium SQL Server 容器：
创建一个 Dockerfile，它使用
registry.redhat.io/amq-streams-kafka-35-rhel8:2.5.0作为基础镜像。例如，在终端窗口中输入以下命令：Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
您可以指定您想要的任何文件名。
2
指定 Kafka Connect 插件目录的路径。如果您的 Kafka Connect 插件目录位于不同的位置，请将此路径替换为您的目录的实际路径。
该命令在当前目录中创建一个名为
debezium-container-for-sqlserver.yaml的 Dockerfile。从您在上一步中创建的
debezium-container-for-sqlserver.yamlDocker 文件中构建容器镜像。在包含该文件的目录中，打开终端窗口并输入以下命令之一：podman build -t debezium-container-for-sqlserver:latest .
podman build -t debezium-container-for-sqlserver:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow docker build -t debezium-container-for-sqlserver:latest .
docker build -t debezium-container-for-sqlserver:latest .Copy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令使用名称
debezium-container-for-sqlserver构建容器镜像。将自定义镜像推送到容器 registry，如 quay.io 或内部容器 registry。容器镜像仓库必须可供您要部署镜像的 OpenShift 实例使用。输入以下命令之一：
podman push <myregistry.io>/debezium-container-for-sqlserver:latest
podman push <myregistry.io>/debezium-container-for-sqlserver:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow docker push <myregistry.io>/debezium-container-for-sqlserver:latest
docker push <myregistry.io>/debezium-container-for-sqlserver:latestCopy to Clipboard Copied! Toggle word wrap Toggle overflow 创建新的 Debezium SQL Server KafkaConnect 自定义资源(CR)。例如，使用名称
dbz-connect.yaml创建KafkaConnectCR，用于指定注解和镜像属性。以下示例显示了描述KafkaConnect自定义资源的dbz-connect.yaml文件摘录。
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 项 描述 1
metadata.annotations表示KafkaConnector资源用于配置在这个 Kafka Connect 集群中使用的 Cluster Operator。2
spec.image指定为运行 Debezium 连接器而创建的镜像的名称。此属性覆盖 Cluster Operator 中的STRIMZI_DEFAULT_KAFKA_CONNECT_IMAGE变量。输入以下命令将
KafkaConnectCR 应用到 OpenShift Kafka Connect 环境：oc create -f dbz-connect.yaml
oc create -f dbz-connect.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令添加一个 Kafka Connect 实例，用于指定为运行 Debezium 连接器而创建的镜像的名称。
创建一个
KafkaConnector自定义资源，用于配置 Debezium SQL Server 连接器实例。您可以在
.yaml文件中配置 Debezium SQL Server 连接器，该文件指定连接器的配置属性。连接器配置可能会指示 Debezium 为模式和表的子集生成事件，或者可能会设置属性，以便 Debezium 忽略、掩码或截断指定列中的值，这些值是敏感、太大或不需要的。以下示例配置了在端口
1433上连接到 SQL 服务器主机192.168.99.100的 Debezium 连接器。此主机有一个名为testDB的数据库，名为customer的表，inventory-connector-sqlserver是服务器的逻辑名称。SQL Server
inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow Expand 表 2.179. 连接器配置设置的描述 项 描述 1
当使用 Kafka Connect 服务注册时，连接器的名称。
2
此 SQL Server 连接器类的名称。
3
SQL Server 实例的地址。
4
SQL Server 实例的端口号。
5
SQL Server 用户的名称。
6
SQL Server 用户的密码。
7
SQL Server instance/cluster 的主题前缀，它组成一个命名空间，并在使用 Avro converter 时，用于连接器写入的 Kafka 主题、Kafka Connect 模式名称和对应 Avro 模式的命名空间的名称。
8
连接器只捕获
dbo.customers表中的更改。9
此连接器将用于写入和恢复 DDL 语句的 Kafka 代理列表到数据库 schema 历史记录主题。
10
连接器将写入和恢复 DDL 语句的数据库架构历史记录主题的名称。本主题仅用于内部使用，不应供消费者使用。
11
存储服务器的 signer 证书的 SSL 信任存储路径。此属性是必需的，除非禁用数据库加密(
database.encrypt=false)。12
SSL truststore 密码。此属性是必需的，除非禁用数据库加密(
database.encrypt=false)。使用 Kafka Connect 创建连接器实例。例如，如果您在
inventory-connector.yaml文件中保存KafkaConnector资源，您将运行以下命令：oc apply -f inventory-connector.yaml
oc apply -f inventory-connector.yamlCopy to Clipboard Copied! Toggle word wrap Toggle overflow 前面的命令注册
inventory-connector，连接器开始针对KafkaConnectorCR 中定义的testDB数据库运行。
验证 Debezium SQL Server 连接器是否正在运行
如果连接器正确启动且没有错误，它会为每个表创建一个主题，这些表配置为捕获连接器。下游应用程序可以订阅这些主题，以检索源数据库中发生的信息事件。
要验证连接器是否正在运行，您可以从 OpenShift Container Platform Web 控制台或 OpenShift CLI 工具(oc)执行以下操作：
- 验证连接器状态。
- 验证连接器是否生成主题。
- 验证主题是否填充了用于读取操作的事件("op":"r")，连接器在每个表的初始快照过程中生成的。
先决条件
- 在 OpenShift 中，Debezium 连接器部署到 Streams for Apache Kafka。
-
已安装 OpenShift
ocCLI 客户端。 - 访问 OpenShift Container Platform web 控制台。
流程
使用以下方法之一检查
KafkaConnector资源的状态：在 OpenShift Container Platform Web 控制台中：
- 导航到 Home → Search。
-
在 Search 页面中，点 Resources 打开 Select Resource 框，然后键入
KafkaConnector。 - 在 KafkaConnectors 列表中，点您要检查的连接器名称，如 inventory-connector-sqlserver。
- 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc describe KafkaConnector <connector-name> -n <project>
oc describe KafkaConnector <connector-name> -n <project>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc describe KafkaConnector inventory-connector-sqlserver -n debezium
oc describe KafkaConnector inventory-connector-sqlserver -n debeziumCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.52.
KafkaConnector资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
验证连接器是否已创建 Kafka 主题：
通过 OpenShift Container Platform Web 控制台。
- 导航到 Home → Search。
-
在 Search 页面上，单击 Resources 以打开 Select Resource 框，然后键入
KafkaTopic。 -
从 KafkaTopics 列表中，点您要检查的主题名称，如
inventory-connector-sqlserver.inventory.orders---ac5e98ac6a5d91e04d8ec0dc9078a1ece439081d。 - 在 Conditions 部分中，验证 Type 和 Status 列中的值是否已设置为 Ready 和 True。
在终端窗口中：
使用以下命令：
oc get kafkatopics
oc get kafkatopicsCopy to Clipboard Copied! Toggle word wrap Toggle overflow 该命令返回与以下输出类似的状态信息：
例 2.53.
KafkaTopic资源状态Copy to Clipboard Copied! Toggle word wrap Toggle overflow
检查主题内容。
- 在终端窗口中输入以下命令：
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>
oc exec -n <project> -it <kafka-cluster> -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=<topic-name>Copy to Clipboard Copied! Toggle word wrap Toggle overflow 例如，
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-sqlserver.inventory.products_on_hand
oc exec -n debezium -it debezium-kafka-cluster-kafka-0 -- /opt/kafka/bin/kafka-console-consumer.sh \ > --bootstrap-server localhost:9092 \ > --from-beginning \ > --property print.key=true \ > --topic=inventory-connector-sqlserver.inventory.products_on_handCopy to Clipboard Copied! Toggle word wrap Toggle overflow 指定主题名称的格式与步骤 1 中返回
的格式相同，例如inventory-connector-sqlserver.inventory.addresses。对于主题中的每个事件，命令会返回类似以下输出的信息：
例 2.54. Debezium 更改事件的内容
{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.sqlserver.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"sqlserver","name":"inventory-connector-sqlserver","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"sqlserver-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}{"schema":{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"}],"optional":false,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Key"},"payload":{"product_id":101}} {"schema":{"type":"struct","fields":[{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Value","field":"before"},{"type":"struct","fields":[{"type":"int32","optional":false,"field":"product_id"},{"type":"int32","optional":false,"field":"quantity"}],"optional":true,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Value","field":"after"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"version"},{"type":"string","optional":false,"field":"connector"},{"type":"string","optional":false,"field":"name"},{"type":"int64","optional":false,"field":"ts_ms"},{"type":"int64","optional":false,"field":"ts_us"},{"type":"int64","optional":false,"field":"ts_ns"},{"type":"string","optional":true,"name":"io.debezium.data.Enum","version":1,"parameters":{"allowed":"true,last,false"},"default":"false","field":"snapshot"},{"type":"string","optional":false,"field":"db"},{"type":"string","optional":true,"field":"sequence"},{"type":"string","optional":true,"field":"table"},{"type":"int64","optional":false,"field":"server_id"},{"type":"string","optional":true,"field":"gtid"},{"type":"string","optional":false,"field":"file"},{"type":"int64","optional":false,"field":"pos"},{"type":"int32","optional":false,"field":"row"},{"type":"int64","optional":true,"field":"thread"},{"type":"string","optional":true,"field":"query"}],"optional":false,"name":"io.debezium.connector.sqlserver.Source","field":"source"},{"type":"string","optional":false,"field":"op"},{"type":"int64","optional":true,"field":"ts_ms"},{"type":"int64","optional":true,"field":"ts_us"},{"type":"int64","optional":true,"field":"ts_ns"},{"type":"struct","fields":[{"type":"string","optional":false,"field":"id"},{"type":"int64","optional":false,"field":"total_order"},{"type":"int64","optional":false,"field":"data_collection_order"}],"optional":true,"field":"transaction"}],"optional":false,"name":"inventory-connector-sqlserver.inventory.products_on_hand.Envelope"},"payload":{"before":null,"after":{"product_id":101,"quantity":3},"source":{"version":"2.7.3.Final-redhat-00001","connector":"sqlserver","name":"inventory-connector-sqlserver","ts_ms":1638985247805,"ts_us":1638985247805000000,"ts_ns":1638985247805000000,"snapshot":"true","db":"inventory","sequence":null,"table":"products_on_hand","server_id":0,"gtid":null,"file":"sqlserver-bin.000003","pos":156,"row":0,"thread":null,"query":null},"op":"r","ts_ms":1638985247805,"ts_us":1638985247805102,"ts_ns":1638985247805102588,"transaction":null}}Copy to Clipboard Copied! Toggle word wrap Toggle overflow 在前面的示例中，
有效负载值显示连接器快照从表inventory.products_on_hand生成一个读取("op" ="r")事件。product_id记录的"before"状态为null，表示记录没有之前的值。"after"状态对于product_id为101的项目的quantity显示为3。
有关您可以为 Debezium SQL Server 连接器设置的配置属性的完整列表，请参阅 SQL Server 连接器属性。
结果
当连接器启动时，它会执行为连接器配置的 SQL Server 数据库的一致性快照。然后，连接器开始为行级操作生成数据更改事件，并将更改事件记录流传输到 Kafka 主题。
2.7.4.4. Debezium SQL Server 连接器配置属性的描述
Debezium SQL Server 连接器有许多配置属性，您可以使用它们来实现应用程序的正确连接器行为。许多属性具有默认值。
有关属性的信息按如下方式进行组织：
- 所需的连接器配置属性
- 高级连接器配置属性
- 数据库架构历史记录连接器配置属性，用于控制 Debezium 如何处理从数据库架构历史记录主题读取的事件。
所需的 Debezium SQL Server 连接器配置属性
除非默认值可用 ， 否则需要以下配置属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器的唯一名称。尝试使用相同名称再次注册将失败。（所有 Kafka 连接连接器都需要此属性。） | |
| 没有默认值 |
连接器的 Java 类的名称。对于 SQL Server 连接器，始终使用 | |
|
| 指定连接器用于从数据库实例捕获数据的最大任务数。 | |
| 没有默认值 | SQL Server 数据库服务器的 IP 地址或主机名。 | |
|
|
SQL Server 数据库服务器的整数端口号。如果同时指定了 | |
| 没有默认值 | 连接到 SQL Server 数据库服务器时使用的用户名。在使用 Kerberos 身份验证时可以省略，可以使用 直通属性进行配置。 | |
| 没有默认值 | 连接到 SQL Server 数据库服务器时要使用的密码。 | |
| 没有默认值 |
指定 SQL 服务器名称实例的实例名称。如果同时指定了 | |
| 没有默认值 |
为您要捕获的 SQL Server 数据库服务器提供命名空间的主题前缀。前缀应该在所有其他连接器之间唯一，因为它用作从这个连接器接收记录的所有 Kafka 主题名称的前缀。数据库服务器逻辑名称中只能使用字母数字字符、连字符、点和下划线。 警告 不要更改此属性的值。如果您更改了 name 值，重启后，而不是继续向原始主题发送事件，连接器会将后续事件发送到名称基于新值的主题。连接器也无法恢复其数据库架构历史记录主题。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与您要 捕获更改的模式名称匹配。没有包含在 schema.
要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 schema 的整个名称字符串匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的、以逗号分隔的正则表达式列表，与 您不想 捕获更改的模式名称匹配。任何名称不包含在 schema.
要匹配模式的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与 schema 的整个名称字符串匹配，它与 schema 名称中可能存在的子字符串不匹配。 | |
| 没有默认值 |
可选的正则表达式列表，它匹配您希望 Debezium 捕获的表的完全限定表标识符。默认情况下，连接器捕获指定模式的所有非系统表。当设置此属性时，连接器只从指定的表中捕获更改。每个标识符都是 schemaName.tableName 的形式。
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
| 没有默认值 |
可选的正则表达式列表，其与您要从捕获中排除的表的完全限定表标识符匹配。Debezium 捕获
要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
| 空字符串 |
可选的正则表达式列表，与 change 事件消息值中包含的列的完全限定域名匹配。列的完全限定域名格式为 schemaName.tableName.columnName。 注意 Debezium 为表发出的每个更改事件记录都包含一个事件键，其中包含表的主键或唯一键中每个列的字段。为确保正确生成事件密钥，如果您设置了此属性，请务必明确列出任何捕获的表的主键列。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。 | |
| 空字符串 |
可选的正则表达式列表，与应排除在更改事件消息值中排除的列的完全限定名称匹配。列的完全限定域名格式为 schemaName.tableName.columnName。请注意，主键列始终包含在事件的键中，也会从值中排除。
要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列中的整个名称字符串匹配，它与列名称中可能存在的子字符串不匹配。 | |
|
|
指定在包含的列中没有更改时跳过发布消息。如果列没有包括每个 | |
|
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。列的完全限定域名格式为 `<schemaName>.<tableName>.<columnName>`.
一个 pseudonym，它包括了通过应用指定的 hashAlgorithm 和 salt 的结果的哈希值。根据使用的 hash 功能，引用完整性会被维护，而列值则替换为 pseudonyms。Java 加密架构标准算法 文档的 MessageDigest 部分中 描述了支持的哈希功能。 column.mask.hash.SHA-256.with.salt.CzQMA0cB5K = inventory.orders.customerName, inventory.shipment.customerName
如有必要，pseudonym 会自动缩短到列的长度。连接器配置可以包含多个属性，以指定不同的哈希算法和 salt。 |
|
|
时间、日期和时间戳可以以不同的精度类型代表： | |
|
|
指定连接器如何处理 | |
|
|
布尔值指定连接器是否应该将数据库模式中的更改发布到与数据库服务器 ID 名称相同的 Kafka 主题。每个架构更改都使用一个键记录，其中包含数据库名称和一个 JSON 结构，用于描述 schema 更新。这独立于连接器内部记录数据库架构历史记录。默认值是 | |
|
|
控制 删除 事件是否后跟 tombstone 事件。 | |
| 不适用 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果在列中的数据超过了在属性名中的 length 指定的字符长度时删节数据，设置此属性。将
一个列的完全限定名称会观察以下格式：< 您可以在单个配置中指定多个长度不同的属性。 | |
| n/a Fully-qualified name 的格式为 schemaName.tableName.columnName。 |
可选的、以逗号分隔的正则表达式列表，与基于字符的列的完全限定域名匹配。如果您希望连接器屏蔽一组列的值，例如，如果它们包含敏感数据，则设置此属性。将 列的完全限定域名观察以下格式： schemaName.tableName.columnName。要匹配列的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与列的整个名称字符串匹配；表达式不匹配列名称中可能存在的子字符串。 您可以在单个配置中指定多个长度不同的属性。 | |
| 不适用 | 可选的、以逗号分隔的正则表达式列表，与您希望连接器发送代表列元数据的额外参数匹配。当设置此属性时，连接器将以下字段添加到事件记录的 schema 中：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
列的完全限定域名观察以下格式： schemaName.tableName.columnName。 | |
| 不适用 | 可选的、以逗号分隔的正则表达式列表，用于指定为数据库中列定义的数据类型的完全限定名称。当设置此属性时，对于带有匹配数据类型的列，连接器会发出事件记录，该记录在其 schema 中包含以下额外字段：
这些参数分别传播列的原始类型名称和长度（用于变量宽度类型）。
列的完全限定域名观察以下格式： schemaName.tableName.typeName。 有关 SQL Server 特定数据类型名称列表，请参阅 SQL Server 数据类型映射。 | |
| 不适用 | 一个表达式列表，用于指定连接器用来组成自定义消息键的表达式列表，用于更改它发布到指定表的 Kafka 主题。
默认情况下，Debebe 使用表的主键列作为发出的记录的消息键。使用默认键，或者为缺少主密钥的表指定一个键，您可以根据一个或多个列配置自定义消息密钥。
每个完全限定表名称都是以下格式的正则表达式： 对用来创建自定义消息键的列数量没有限制。但是，最好使用指定唯一密钥所需的最小数量。 | |
| bytes |
指定在更改事件中二进制（二进制 , | |
| none |
指定应该如何调整模式名称，以便与连接器使用的消息转换器兼容。可能的设置：
| |
| none |
指定应如何调整字段名称，以便与连接器使用的消息转换器兼容。可能的设置：
如需更多信息，请参阅 Avro 命名。 |
高级 SQL Server 连接器配置属性
以下 高级配置 属性具有在大多数情况下可以正常工作的良好默认值，因此很少需要在连接器配置中指定。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
枚举连接器可以使用的 自定义转换器 实例的符号链接名称列表。例如，
您必须设置
对于您为连接器配置的每个转换器，还必须添加一个
例如， isbn.type: io.debezium.test.IsbnConverter
如果要进一步控制配置的转换器的行为，您可以添加一个或多个配置参数来将值传递给转换器。要将任何其他配置参数与转换器关联，请为参数名称添加转换器符号名称作为前缀。例如， isbn.schema.name: io.debezium.sqlserver.type.Isbn | |
| Initial | 对结构的初始快照以及捕获的表（可选）数据的模式。快照完成后，连接器将继续从数据库的红色日志中读取更改事件。支持以下值：
| |
| exclusive | 控制连接器保存表锁定的时长。表锁定可防止在连接器执行快照时发生某些类型的更改表操作。您可以设置以下值：
| |
|
|
指定连接器在执行快照时如何查询数据。
与使用 | |
|
|
一个可选的、以逗号分隔的正则表达式列表，匹配表的完全限定名 ( 要匹配表的名称，Debebe 会使用正则表达式，它由您作为 anchored 正则表达式指定。也就是说，指定的表达式与表的整个名称字符串匹配；它不匹配表名称中可能存在的子字符串。 | |
| repeatable_read | 模式，控制使用哪个事务隔离级别，以及连接器锁定用于捕获的时长。支持以下值：
模式选择也会影响数据一致性。只有 | |
|
|
指定连接器在处理事件时应如何响应异常。 | |
|
| 正整数值指定连接器在每次迭代过程中应等待的毫秒数，以便出现新的更改事件。默认值为 500 毫秒，或 0.5 秒。 | |
|
|
正整数值，用于指定阻塞队列可以保存的最大记录数。当 Debezium 从数据库读取事件时，它会在将事件写入 Kafka 前将事件放在阻塞队列中。当连接器比将信息写入 Kafka 的速度或 Kafka 不可用时，阻塞队列可能会提供从数据库读取更改事件的情况。当连接器定期记录偏移时，队列中保存的事件会被忽略。始终将 | |
|
|
指定阻塞队列的最大卷的长整数值，以字节为单位。默认情况下，没有为阻塞队列指定卷限制。要指定队列可以使用的字节数，请将此属性设置为正长值。 | |
|
| 正整数值，用于指定应在每个迭代此连接器期间处理的每个批处理事件的最大值。 | |
|
|
控制发送心跳消息的频率。 | |
| 没有默认值 |
指定当连接器发送心跳消息时连接器在源数据库上执行的查询。 | |
| 没有默认值 |
连接器在启动后执行快照前应等待的时间间隔； | |
| 0 |
指定连接器在完成快照后延迟流过程启动的时间（以毫秒为单位）。设置延迟间隔有助于防止连接器在快照完成后马上重启快照，但在流传输过程开始前。设置一个延迟值，它高于为 Kafka Connect worker 设置的 | |
|
| 指定在拍摄快照时应在每个表中读取的最大行数。连接器将在这个大小的多个批处理中读取表内容。默认值为 2000。 | |
| 没有默认值 | 指定给定查询的每个数据库往返获取的行数。默认为 JDBC 驱动程序的默认获取大小。 | |
|
|
整数值，用于指定在执行快照时等待获取表锁定的最大时间（以毫秒为单位）。如果无法在这个时间段内获取表锁定，则快照将失败（也查看 快照）。 | |
| 没有默认值 | 指定要包含在快照中的表行。如果您希望快照只包括表中的行的子集，请使用该属性。此属性仅影响快照。它不适用于连接器从日志读取的事件。
属性包含以逗号分隔的完全限定表名称列表，格式为 <
从包括软删除列 "snapshot.select.statement.overrides": "customer.orders", "snapshot.select.statement.overrides.customer.orders": "SELECT * FROM customers.orders WHERE delete_flag = 0 ORDER BY id DESC"
在生成的快照中，连接器只包含 | |
|
|
当设置为 | |
| 10000 (10 秒) | 在发生可分配错误后重启连接器前要等待的 milli-seconds 数量。 | |
|
|
在流过程中跳过的操作类型的逗号分隔列表。操作包括： | |
| 没有默认值 |
用于向连接器发送信号的数据收集的完全限定名称。https://docs.redhat.com/documentation/en/red_hat_build_of_debezium/2.7.3/html-single/debezium_user_guide/index#debezium-signaling-enabling-source-signaling-channel | |
| source | 为连接器启用的信号通道名称列表。默认情况下，以下频道可用：
| |
| 没有默认值 | 为连接器启用的通知频道名称列表。默认情况下，以下频道可用：
| |
|
|
允许增量快照期间进行 schema 更改。启用连接器后，连接器将在增量快照期间检测到模式变化，并重新选择当前块以避免锁定 DDLs。 | |
|
| 连接器在增量快照块期间获取并读取的最大行数。增加块大小可提供更高的效率，因为快照会减少对更大大小的快照查询。但是，较大的块大小还需要更多内存来缓冲快照数据。将块大小调整为可在您的环境中提供最佳性能的值。 | |
|
|
指定连接器在增量快照中使用的水位线机制，以重复数据删除事件，这些事件可能会被增量快照捕获，然后在流恢复后重新捕获。
| |
| 500 |
指定每个迭代的最大事务数，以便在从数据库中的多个表流传输更改时减少内存占用量。当设置为 | |
|
| 将 OPTION (RECOMPILE)查询选项用于增量快照期间使用的所有 SELECT 语句。这有助于解决可能出现的参数嗅探问题，但可能会导致源数据库上的 CPU 负载增加，具体取决于查询执行的频率。 | |
|
|
应用于确定数据更改的主题名称、模式更改、事务、心跳事件等主题名称，默认为 | |
|
|
指定主题名称的分隔符，默认为 | |
|
| 在绑定的并发散列映射中保存主题名称的大小。此缓存将有助于确定与给定数据收集对应的主题名称。 | |
|
|
控制连接器发送心跳消息的主题名称。主题名称具有此模式： | |
|
|
控制连接器发送事务元数据消息的主题名称。主题名称具有此模式： 如需更多信息，请参阅 事务元数据。 | |
|
| 指定连接器在执行初始快照时使用的线程数量。要启用并行初始快照，请将 属性设置为大于 1 的值。在并行初始快照中，连接器同时处理多个表。 重要 并行初始快照只是一个技术预览功能。技术预览功能不受红帽产品服务等级协议（SLA）支持，且功能可能并不完整。红帽不推荐在生产环境中使用它们。这些技术预览功能可以使用户提早试用新的功能，并有机会在开发阶段提供反馈意见。有关红帽技术预览功能支持范围的更多信息，请参阅技术预览功能支持范围。 | |
|
|
通过添加提供上下文信息的元数据来定义自定义 MBean 对象名称的标签。指定以逗号分隔的键值对列表。每个键代表 MBean 对象名称的标签，对应的值代表键的值，例如 连接器将指定的标签附加到基础 MBean 对象名称。标签可帮助您组织和分类指标数据。您可以定义标签来标识特定的应用程序实例、环境、区域、版本等。如需更多信息，请参阅自定义 MBean 名称。 | |
|
|
指定连接器如何在生成 Retriable 错误的操作后响应，如连接错误。
| |
|
| 控制连接器查询 CDC 数据的方式。支持以下模式：
| |
|
|
指定连接器等待查询完成的时间（以毫秒为单位）。将值设为 |
Debezium SQL Server 连接器数据库模式历史记录配置属性
Debezium 提供了一组 schema.history.internal.* 属性，用于控制连接器如何与 schema 历史记录主题进行交互。
下表描述了用于配置 Debezium 连接器的 schema.history.internal 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 | 连接器存储数据库 schema 历史记录的 Kafka 主题的完整名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机/端口对列表。此连接用于检索之前由连接器存储的数据库架构历史记录，以及写入从源数据库读取的每个 DDL 语句。每个对都应该指向 Kafka Connect 进程使用的相同 Kafka 集群。 | |
|
| 整数值，指定连接器在启动/恢复期间应等待的最大毫秒数，同时轮询持久数据。默认值为 100ms。 | |
|
| 指定连接器在使用 Kafka admin 客户端获取集群信息时应等待的最大毫秒数。 | |
|
| 指定连接器在使用 Kafka admin 客户端创建 kafka 历史记录主题时应等待的最大毫秒数。 | |
|
|
连接器在连接器恢复失败前尝试读取持久性历史记录数据的次数上限，并显示错误。没有数据后等待的最长时间是 | |
|
|
指定连接器是否应该忽略不正确的或未知数据库语句的布尔值，或停止处理，以便用户可以解决这个问题。安全默认为 | |
|
|
指定连接器是否记录模式或数据库中所有表的布尔值，或者仅从指定为捕获的表记录。
| |
|
|
指定连接器是否从数据库实例中的所有逻辑数据库记录模式结构的布尔值。
|
透传 SQL Server 连接器配置属性
连接器支持 通过传递 属性，使 Debezium 指定自定义配置选项来微调 Apache Kafka producer 和消费者的行为。有关 Kafka 生成者和消费者的完整配置属性范围的详情，请参考 Kafka 文档。
直通属性，用于配置生成者和消费者客户端如何与 schema 历史记录主题交互
Debezium 依赖于 Apache Kafka producer 将 schema 更改写入数据库 schema 历史记录主题。同样，它依赖于 Kafka 使用者在连接器启动时从数据库 schema 历史记录主题中读取。您可以通过将值分配给一组以 schema.history.internal.producer和 schema.history.internal.consumerPromQL 前缀开头的 pass-through 配置属性来定义 Kafka producer 和 消费者 客户端的配置。pass-through producer 和 consumer 数据库模式历史记录属性控制一系列行为，如这些客户端如何与 Kafka 代理安全连接，如下例所示：
Debezium 在将属性传递给 Kafka 客户端前从属性名称中剥离前缀。
有关 Kafka producer 配置属性和 Kafka 使用者配置属性的更多信息，请参阅 Apache Kafka 文档。
用于配置 SQL Server 连接器如何与 Kafka 信号交互的直通属性
Debezium 提供了一组 signal.* 属性，用于控制连接器如何与 Kafka 信号主题进行交互。
下表描述了 Kafka 信号 属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| <topic.prefix>-signal | 连接器监控用于临时信号的 Kafka 主题的名称。 注意 如果禁用 自动主题创建，您必须手动创建所需的信号主题。需要信号主题来保留信号顺序。信号主题必须具有单个分区。 | |
| kafka-signal | Kafka 用户使用的组 ID 的名称。 | |
| 没有默认值 | 连接器用来建立到 Kafka 集群的初始连接的主机和端口对列表。每个对引用 Debezium Kafka Connect 进程使用的 Kafka 集群。 | |
|
| 整数值，用于指定连接器在轮询信号时等待的最大毫秒数。 | |
|
| 指定 Kafka 使用者是否在从信号主题读取消息后写入偏移提交。分配给此属性的值决定了连接器是否可以处理在连接器离线时收到信号主题接收的请求。选择以下设置之一：
|
为信号频道配置 Kafka 消费者客户端的属性
Debezium 连接器提供信号 Kafka 使用者的直通配置。透传信号属性以 signals.consumer.* 前缀开始。例如，连接器将 signal.consumer.security.protocol=SSL 等属性传递给 Kafka 使用者。
Debezium 在将属性传递给 Kafka 信号消费者前从属性中剥离前缀。
用于配置 SQL Server 连接器接收器通知频道的直通属性
下表描述了可用于配置 Debezium sink 通知 频道的属性。
| 属性 | 默认 | 描述 |
|---|---|---|
| 没有默认值 |
从 Debezium 接收通知的主题名称。当您将 |
Debezium 连接器传递数据库驱动程序配置属性
Debezium 连接器提供数据库驱动程序的直通配置。透传数据库属性以前缀 driverPROFILE 开头。例如，连接器将 driver.foobar=false 等属性传递给 JDBC URL。
Debezium 在将属性传递给数据库驱动程序前从属性中剥离前缀。
2.7.5. 在 schema 更改后刷新捕获表
当为 SQL Server 表启用数据捕获时，如表中的更改，事件记录会被保留到服务器上的捕获表中。如果您引入源表更改的结构的变化，例如，通过添加新列，则该更改不会动态反映在更改表中。只要捕获表继续使用过时的模式，Debezium 连接器无法正确为表发送数据更改事件。您必须干预来刷新捕获表，以便连接器恢复处理更改事件。
由于在 SQL Server 中实现 CDC 的方式，您无法使用 Debezium 更新捕获表。要刷新捕获表，必须是具有升级权限的 SQL Server 数据库 operator。作为 Debezium 用户，您必须使用 SQL Server 数据库 operator 协调任务，以完成 schema 刷新并恢复到 Kafka 主题。
您可以使用以下任一方法在模式更改后更新捕获表：
- 在更新捕获表前，离线 schema 更新 要求您停止 Debezium 连接器。
- 在线 schema 更新 可以在 Debezium 连接器运行时更新捕获表。
使用每种流程都有优点和缺点。
无论您使用在线还是离线更新方法，在在同一源表中应用后续模式更新前，您必须完成整个架构更新过程。最佳实践是在单一批处理中执行所有 DDL，以便只能运行一次。
在启用了 CDC 的源表上不支持一些模式更改。例如，如果在表上启用了 CDC，如果您重命名了其中一个列或更改列类型，则 SQL Server 不允许您更改表的模式。
在将源表中的列从 NULL 改为 NOT NULL 或 versa 后，SQL Server 连接器无法正确捕获更改的信息，直到您创建新的捕获实例为止。如果您在列设计后没有创建新的捕获表，请更改连接器发出的事件记录没有正确地指示列是否是可选的。也就是说，之前定义为可选（或 NULL）的列仍然是，尽管现在定义为 NOT NULL。同样，已根据需要定义的列(不是 NULL)，保留这种设计，尽管它们现在定义为 NULL。
使用 sp_rename 功能重命名表后，它将继续在旧源表名称下发出更改，直到连接器重启为止。在连接器重启后，它将在新源表名称下发出更改。
2.7.5.1. 在 schema 更改后运行离线更新
离线 schema 更新提供了更新捕获表的安全方法。但是，离线更新可能不适用于需要高可用性的应用程序。
先决条件
- 更新已提交到启用了 CDC 的 SQL Server 表的 schema。
- 您是一个具有升级权限的 SQL Server 数据库 operator。
流程
- 暂停更新数据库的应用程序。
- 等待 Debezium 连接器流所有未流的更改事件记录。
- 停止 Debezium 连接器。
- 将所有更改应用到源表模式。
-
使用
sys.sp_cdc_enable_table程序为 update 源表创建一个新的捕获表，其参数为@capture_instance。 - 恢复您在第 1 步中暂停的应用程序。
- 启动 Debezium 连接器。
-
在 Debezium 连接器从新捕获表开始流后，通过运行存储的步骤
sys.sp_cdc_disable_table来丢弃旧的捕获表，并将参数@capture_instance设置为旧的捕获实例名称。
2.7.5.2. 在 schema 更改后运行在线更新
完成在线模式更新的过程比运行离线模式更新的步骤简单，您可以完成它，而无需应用程序和数据处理中的停机。但是，随着在线架构更新，在更新源数据库中的 schema 后可能会发生潜在的处理差距，但在创建新的捕获实例之前。在这个间隔中，更改事件将继续被更改表的旧实例捕获，保存至旧表的更改数据会保留之前模式的结构。因此，例如，如果您向源表添加了新列，请在新捕获表前生成的更改事件就绪，请不要包含新列的字段。如果您的应用程序不容许这样的过渡周期，最好使用离线 schema 更新过程。
先决条件
- 更新已提交到启用了 CDC 的 SQL Server 表的 schema。
- 您是一个具有升级权限的 SQL Server 数据库 operator。
流程
- 将所有更改应用到源表模式。
-
通过运行
sys.sp_cdc_enable_table存储并具有参数@capture_instance的唯一值，为更新源表创建一个新的捕获表。 -
当 Debezium 从新的捕获表中开始流时，您可以通过运行
sys.sp_cdc_disable_table存储的步骤来丢弃旧的捕获表，并将参数@capture_instance设置为旧的捕获实例名称。
示例：在数据库架构更改后运行在线模式更新
以下示例演示了如何在将列 phone_number 添加到 customer 源表后，在更改表中完成在线模式更新。
运行以下查询来修改
customers源表的模式，以添加phone_number字段：ALTER TABLE customers ADD phone_number VARCHAR(32);
ALTER TABLE customers ADD phone_number VARCHAR(32);Copy to Clipboard Copied! Toggle word wrap Toggle overflow 通过运行
sys.sp_cdc_enable_table存储的步骤创建新捕获实例。EXEC sys.sp_cdc_enable_table @source_schema = 'dbo', @source_name = 'customers', @role_name = NULL, @supports_net_changes = 0, @capture_instance = 'dbo_customers_v2'; GO
EXEC sys.sp_cdc_enable_table @source_schema = 'dbo', @source_name = 'customers', @role_name = NULL, @supports_net_changes = 0, @capture_instance = 'dbo_customers_v2'; GOCopy to Clipboard Copied! Toggle word wrap Toggle overflow 运行以下查询将新数据插入到
customers表中：INSERT INTO customers(first_name,last_name,email,phone_number) VALUES ('John','Doe','john.doe@example.com', '+1-555-123456'); GOINSERT INTO customers(first_name,last_name,email,phone_number) VALUES ('John','Doe','john.doe@example.com', '+1-555-123456'); GOCopy to Clipboard Copied! Toggle word wrap Toggle overflow Kafka Connect 日志通过类似以下消息的条目报告配置更新：
connect_1 | 2019-01-17 10:11:14,924 INFO || Multiple capture instances present for the same table: Capture instance "dbo_customers" [sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_CT, startLsn=00000024:00000d98:0036, changeTableObjectId=1525580473, stopLsn=00000025:00000ef8:0048] and Capture instance "dbo_customers_v2" [sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL] [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource] connect_1 | 2019-01-17 10:11:14,924 INFO || Schema will be changed for ChangeTable [captureInstance=dbo_customers_v2, sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL] [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource] ... connect_1 | 2019-01-17 10:11:33,719 INFO || Migrating schema to ChangeTable [captureInstance=dbo_customers_v2, sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL] [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource]
connect_1 | 2019-01-17 10:11:14,924 INFO || Multiple capture instances present for the same table: Capture instance "dbo_customers" [sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_CT, startLsn=00000024:00000d98:0036, changeTableObjectId=1525580473, stopLsn=00000025:00000ef8:0048] and Capture instance "dbo_customers_v2" [sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL] [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource] connect_1 | 2019-01-17 10:11:14,924 INFO || Schema will be changed for ChangeTable [captureInstance=dbo_customers_v2, sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL] [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource] ... connect_1 | 2019-01-17 10:11:33,719 INFO || Migrating schema to ChangeTable [captureInstance=dbo_customers_v2, sourceTableId=testDB.dbo.customers, changeTableId=testDB.cdc.dbo_customers_v2_CT, startLsn=00000025:00000ef8:0048, changeTableObjectId=1749581271, stopLsn=NULL] [io.debezium.connector.sqlserver.SqlServerStreamingChangeEventSource]Copy to Clipboard Copied! Toggle word wrap Toggle overflow 最后，
phone_number字段添加到 schema 中，其值会出现在写入 Kafka 主题的消息中。Copy to Clipboard Copied! Toggle word wrap Toggle overflow 通过运行
sys.sp_cdc_disable_table存储的步骤丢弃旧的捕获实例。EXEC sys.sp_cdc_disable_table @source_schema = 'dbo', @source_name = 'dbo_customers', @capture_instance = 'dbo_customers'; GO
EXEC sys.sp_cdc_disable_table @source_schema = 'dbo', @source_name = 'dbo_customers', @capture_instance = 'dbo_customers'; GOCopy to Clipboard Copied! Toggle word wrap Toggle overflow
2.7.6. 监控 Debezium SQL Server 连接器性能
Debezium SQL Server 连接器提供三种类型的指标，除了对 Zookeeper、Kafka 和 Kafka Connect 提供的 JMX 指标的支持外。连接器提供以下指标：
- 在执行快照时监控连接器的快照 指标。
- 在读取 CDC 表数据时监控连接器的 流传输指标。
- 用于监控连接器 架构历史记录状态的 schema 历史记录指标。
有关如何通过 JMX 公开上述指标的详情，请参考 Debezium 监控文档。
2.7.6.1. SQL Server 连接器快照和流 MBean 对象的自定义名称
Debezium 连接器通过 MBean 名称为连接器公开指标。这些指标（特定于每个连接器实例）提供有关连接器快照、流和架构历史记录进程行为的数据。
默认情况下，当您部署正确配置的连接器时，Debezium 会为每个不同的连接器指标生成一个唯一的 MBean 名称。要查看连接器进程的指标，您可以将可观察性堆栈配置为监控其 MBean。但是，这些默认 MBean 名称取决于连接器配置，但配置更改可能会导致对 MBean 名称的更改。对 MBean 名称的更改会破坏连接器实例和 MBean 之间的链接，并破坏监控活动。在这种情况下，如果要恢复监控，您必须重新配置 observability 堆栈以使用新的 MBean 名称。
要防止监控 MBean 名称更改结果的中断，您可以配置自定义指标标签。您可以通过在连接器配置中添加 custom.metric.tags 属性来配置自定义指标。属性接受键值对，其中每个键代表 MBean 对象名称的标签，对应的值代表该标签的值。例如： k1=v1,k2=v2。Debezium 将指定的标签附加到连接器的 MBean 名称中。
为连接器配置 custom.metric.tags 属性后，您可以配置 observability 堆栈以检索与指定标签关联的指标。然后，可观察性堆栈使用指定的标签，而不是可变 MBean 名称来唯一标识连接器。之后，如果 Debezium 重新定义了它如何构建 MBean 名称，或者连接器配置更改中的 topic.prefix，则指标集合不会中断，因为指标提取任务使用指定的标签模式来识别连接器。
使用自定义标签的更多优点是，您可以使用反映数据管道架构的标签，以便以适合您操作需求的方式组织指标。例如，您可以使用声明连接器活动类型、应用程序上下文或数据源的值来指定标签，如 db1-streaming-for-application-abc。如果您指定多个键值对，则所有指定的对都会附加到连接器的 MBean 名称中。
以下示例演示了标签如何修改默认的 MBean 名称。
例 2.55. 自定义标签如何修改连接器 MBean 名称
默认情况下，SQL Server 连接器使用以下 MBean 名称进行流传输指标：
debezium.sqlserver:type=connector-metrics,context=streaming,server=<topic.prefix>
debezium.sqlserver:type=connector-metrics,context=streaming,server=<topic.prefix>
如果将 custom.metric.tags 的值设置为 database=salesdb-streaming,table=inventory，Debezium 会生成以下自定义 MBean 名称：
debezium.sqlserver:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory
debezium.sqlserver:type=connector-metrics,context=streaming,server=<topic.prefix>,database=salesdb-streaming,table=inventory2.7.6.2. Debezium SQL Server 连接器快照指标
MBean 为 debezium.sql_server:type=connector-metrics,server= <topic.prefix& gt; ,task= <task.id>,context=snapshot。
快照指标不会被公开，除非快照操作活跃，或者快照自上次连接器开始以来发生了某种情况。
下表列出了可用的快照指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个快照事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 此连接器自上一次启动或重置以来看到的事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在快照和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在快照和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 包括在快照中的表的总数。 | |
|
| 快照必须复制的表数。 | |
|
| 快照是否已启动。 | |
|
| 快照是否已暂停。 | |
|
| 快照是中止的。 | |
|
| 快照是否完成。 | |
|
| 快照到目前为止需要的秒数，即使未完成也是如此。也包括快照暂停的时间。 | |
|
| 快照暂停的秒数。如果快照暂停了多次，暂停的时间会增加。 | |
|
| 包含快照中每个表扫描的行数的映射。在处理过程中，表会以递增方式添加到映射中。更新每 10,000 行扫描并完成表后。 | |
|
|
队列的最大数量（以字节为单位）。如果将 | |
|
| 队列中记录的当前卷（以字节为单位）。 |
连接器还会在执行增量快照时提供以下附加快照指标：
2.7.6.3. Debezium SQL Server 连接器流指标
MBean 为 debezium.sql_server:type=connector-metrics,server= <topic.prefix& gt; ,task= <task.id>,context=streaming。
下表列出了可用的流指标。
| 属性 | 类型 | 描述 |
|---|---|---|
|
| 连接器读取的最后一个流事件。 | |
|
| 因为连接器已读取和处理最新事件，因此毫秒数。 | |
|
| 源数据库自上次连接器启动后报告的数据更改事件总数，或者因为指标重置后。代表 Debezium 处理的数据更改工作负载。 | |
|
| 自上次启动或指标重置以来，连接器处理的创建事件总数。 | |
|
| 自上次启动或指标重置以来，连接器处理的更新事件总数。 | |
|
| 自上次启动或指标重置后，连接器处理的删除事件总数。 | |
|
| 已根据连接器上配置的 include/exclude 列表过滤规则过滤的事件数量。 | |
|
| 连接器捕获的表列表。 | |
|
| 在流器和主 Kafka Connect 循环之间传递事件的队列长度。 | |
|
| 用于在流程序和主 Kafka Connect 循环之间传递事件的队列的可用容量。 | |
|
| 表示连接器当前是否已连接到数据库服务器的标记。 | |
|
| 最后一次更改事件的时间戳和连接器处理之间的毫秒数。这些值将纳入运行数据库服务器和连接器的机器上时钟之间的差别。 | |
|
| 已提交的已处理事务的数量。 | |
|
| 最后一次接收的事件的协调。 | |
|
| 最后一次处理的事务的事务标识符。 | |
|
|
队列的最大数量（以字节为单位）。如果将 |