Debezium日常分享系列之：Debezium2.5稳定版本之数据类型映射

Debezium MySQL 连接器表示对带有事件的行的更改，这些事件的结构类似于该行所在的表。该事件包含每个列值的字段。该列的 MySQL 数据类型决定 Debezium 如何表示事件中的值。

MySQL 中使用字符集和排序规则定义存储字符串的列。 MySQL 连接器在读取二进制日志事件中列值的二进制表示形式时使用列的字符集。

连接器可以将 MySQL 数据类型映射到文字类型和语义类型。

• 文字类型：如何使用 Kafka Connect 模式类型表示值。
• 语义类型：Kafka Connect 模式如何捕获字段（模式名称）的含义。

如果默认的数据类型转换不能满足您的需求，您可以为连接器创建自定义转换器。

一、基本类型

下表显示了连接器如何映射基本 MySQL 数据类型。

表 13. 基本类型映射的描述

MySQL type	文字类型	语义类型
BOOLEAN, BOOL	BOOLEAN	n/a
BIT(1)	BOOLEAN	n/a
BIT(>1)	BYTES	io.debezium.data.Bits长度模式参数包含一个表示位数的整数。 byte[] 包含小尾数形式的位，并调整大小以包含指定的位数。例如，其中 n 是位：字节数 = n/8 + (n%8== 0 ? 0 : 1)
TINYINT	INT16	n/a
SMALLINT[(M)]	INT16	n/a
MEDIUMINT[(M)]	INT32	n/a
INT, INTEGER[(M)]	INT32	n/a
BIGINT[(M)]	INT64	n/a
REAL[(M,D)]	FLOAT32	n/a
FLOAT[§]	FLOAT32 or FLOAT64	精度仅用于确定存储大小。从 0 到 23 的精度 P 会生成 4 字节单精度 FLOAT32 列。从 24 到 53 的精度 P 会生成 8 字节双精度 FLOAT64 列。
FLOAT(M,D)	FLOAT64	从 MySQL 8.0.17 开始，非标准 FLOAT(M,D) 和 DOUBLE(M,D) 语法已被弃用，并且应该期望在 MySQL 的未来版本中删除对其的支持，将 FLOAT64 设置为默认值。
DOUBLE[(M,D)]	FLOAT64	n/a
CHAR(M)]	STRING	n/a
VARCHAR(M)]	STRING	n/a
BINARY(M)]	BYTES or STRING	n/a 原始字节（默认）、base64 编码的字符串、base64-url-safe-encoded 的字符串或十六进制编码的字符串，具体取决于 binary.handling.mode 连接器配置属性设置。
VARBINARY(M)]	BYTES or STRING	n/a 原始字节（默认）、base64 编码的字符串、base64-url-safe-encoded 的字符串或十六进制编码的字符串，具体取决于 binary.handling.mode 连接器配置属性设置。
TINYBLOB	BYTES or STRING	n/a 原始字节（默认）、base64 编码的字符串、base64-url-safe-encoded 的字符串或十六进制编码的字符串，具体取决于 binary.handling.mode 连接器配置属性设置。
TINYTEXT	STRING	n/a
BLOB	BYTES or STRING	n/a 原始字节（默认）、base64 编码的字符串、base64-url-safe-encoded 的字符串或十六进制编码的字符串，具体取决于 binary.handling.mode 连接器配置属性设置。仅支持大小最大为 2GB 的值。建议使用声明检查模式外部化大列值。
TEXT	STRING	n/a 仅支持大小最大为 2GB 的值。建议使用声明检查模式外部化大列值。
MEDIUMBLOB	BYTES or STRING	n/a 原始字节（默认）、base64 编码的字符串、base64-url-safe-encoded 的字符串或十六进制编码的字符串，具体取决于 binary.handling.mode 连接器配置属性设置。
MEDIUMTEXT	STRING	n/a
LONGBLOB	BYTES or STRING	n/a 原始字节（默认）、base64 编码的字符串、base64-url-safe-encoded 的字符串或十六进制编码的字符串，具体取决于 binary.handling.mode 连接器配置属性设置。仅支持大小最大为 2GB 的值。建议使用声明检查模式外部化大列值。
LONGTEXT	STRING	n/a 仅支持大小最大为 2GB 的值。建议使用声明检查模式外部化大列值。
JSON	STRING	io.debezium.data.Json包含 JSON 文档、数组或标量的字符串表示形式。
ENUM	STRING	io.debezium.data.Enum允许的架构参数包含以逗号分隔的允许值列表。
SET	STRING	io.debezium.data.EnumSet允许的架构参数包含以逗号分隔的允许值列表。
YEAR[(2	4)]	INT32
TIMESTAMP[(M)]	STRING	io.debezium.time.ZonedTimestamp采用 ISO 8601 格式，精度为微秒。 MySQL允许M的范围是0-6。

二、时间类型

除 TIMESTAMP 数据类型外，MySQL 时间类型取决于 time. precision.mode 连接器配置属性的值。对于默认值指定为 CURRENT_TIMESTAMP 或 NOW 的 TIMESTAMP 列，值 1970-01-01 00:00:00 将用作 Kafka Connect 架构中的默认值。

MySQL 允许 DATE、DATETIME 和 TIMESTAMP 列使用零值，因为有时零值优于空值。当列定义允许空值时，MySQL 连接器将零值表示为空值；当列定义不允许空值时，MySQL 连接器将零值表示为纪元日。

没有时区的时间值

DATETIME 类型表示本地日期和时间，例如“2018-01-13 09:48:27”。如您所见，没有时区信息。此类列将使用 UTC 根据列的精度转换为纪元毫秒或微秒。 TIMESTAMP 类型表示没有时区信息的时间戳。写入时，MySQL 将其从服务器（或会话）的当前时区转换为 UTC；读回该值时，MySQL 将其从 UTC 转换为服务器（或会话）的当前时区。例如：

• 值为 2018-06-20 06:37:03 的 DATETIME 变为 1529476623000。
• 值为 2018-06-20 06:37:03 的 TIMESTAMP 变为 2018-06-20T13:37:03Z。

此类列将根据服务器（或会话的）当前时区转换为 UTC 格式的等效 io.debezium.time.ZonedTimestamp。默认情况下将从服务器查询时区。如果失败，则必须通过数据库连接TimeZone MySQL 配置选项显式指定。例如，如果数据库的时区（全局时区或通过 connectionTimeZone 选项为连接器配置）为“America/Los_Angeles”，则 TIMESTAMP 值“2018-06-20 06:37:03”由 ZonedTimestamp 表示值为“2018-06-20T13:37:03Z”。

运行 Kafka Connect 和 Debezium 的 JVM 时区不会影响这些转换。

time.precision.mode=adaptive_time_microseconds(default)

• MySQL 连接器根据列的数据类型定义确定文字类型和语义类型，以便事件准确表示数据库中的值。所有时间字段均以微秒为单位。只能正确捕获 00:00:00.000000 到 23:59:59.999999 范围内的正 TIME 字段值。

表 14. time. precision.mode=adaptive_time_microseconds 时的映射

MySQL type	文字类型	语义类型
DATE	INT32	io.debezium.time.Date表示自纪元以来的天数。
TIME[(M)]	INT64	io.debezium.time.MicroTime表示以微秒为单位的时间值，不包含时区信息。 MySQL允许M的范围是0-6。
DATETIME, DATETIME(0), DATETIME(1), DATETIME(2), DATETIME(3)	INT64	io.debezium.time.Timestamp 表示经过纪元的毫秒数，不包括时区信息。
DATETIME(4), DATETIME(5), DATETIME(6)	INT64	io.debezium.time.MicroTimestamp 表示经过纪元的微秒数，不包括时区信息。

time.precision.mode=connect

MySQL 连接器使用定义的 Kafka Connect 逻辑类型。此方法的精确度低于默认方法，并且如果数据库列的小数秒精度值大于 3，则事件的精确度可能会降低。只有在00:00:00.000 到 23:59:59.999 范围内的值可以被处理。仅当您可以确保表中的 TIME 值永远不会超出支持的范围时，才设置 time. precision.mode=connect。connect设置预计将在 Debezium 的未来版本中删除。

表 15. time. precision.mode=connect 时的映射

MySQL type	文字类型	语义类型
DATE	INT32	org.apache.kafka.connect.data.Date 表示自纪元以来的天数。
TIME[(M)]	INT64	org.apache.kafka.connect.data.Time 表示自午夜以来的时间值（以微秒为单位），不包含时区信息。
DATETIME[(M)]	INT64	org.apache.kafka.connect.data.Timestamp 表示自纪元以来的毫秒数，不包含时区信息。

三、Decimal类型

Debezium 连接器根据decimal.handling.mode 连接器配置属性的设置处理小数。

decimal.handling.mode=precise

表 16.decimal.handling.mode=precise 时的映射

MySQL type	文字类型	语义类型
NUMERIC[(M[,D])]	BYTES	org.apache.kafka.connect.data.Decimal 比例模式参数包含一个整数，表示小数点移动了多少位。
DECIMAL[(M[,D])]	BYTES	org.apache.kafka.connect.data.Decimal 比例模式参数包含一个整数，表示小数点移动了多少位。

decimal.handling.mode=double

表 17.decimal.handling.mode=double 时的映射

MySQL type	文字类型	语义类型
NUMERIC[(M[,D])]	FLOAT64	n/a
DECIMAL[(M[,D])]	FLOAT64	n/a

decimal.handling.mode=string

表 18.decimal.handling.mode=string 时的映射

MySQL type	文字类型	语义类型
NUMERIC[(M[,D])]	STRING	n/a
DECIMAL[(M[,D])]	STRING	n/a

四、Boolean values布尔值

MySQL 在内部以特定方式处理 BOOLEAN 值。 BOOLEAN 列在内部映射到 TINYINT(1) 数据类型。当表在流式传输期间创建时，它会使用正确的 BOOLEAN 映射，因为 Debezium 接收原始 DDL。在快照期间，Debezium 执行 SHOW CREATE TABLE 来获取为 BOOLEAN 和 TINYINT(1) 列返回 TINYINT(1) 的表定义。 Debezium 无法获取原始类型映射，因此映射到 TINYINT(1)。

为了使您能够将源列转换为布尔数据类型，Debezium 提供了一个 TinyIntOneToBooleanConverter 自定义转换器，您可以通过以下方式之一使用它：

• 将所有 TINYINT(1) 或 TINYINT(1) UNSIGNED 列映射到 BOOLEAN 类型。
• 使用逗号分隔的正则表达式列表枚举列的子集。

要使用这种类型的转换，您必须使用选择器参数设置转换器配置属性，如以下示例所示：

converters=boolean
boolean.type=io.debezium.connector.mysql.converters.TinyIntOneToBooleanConverter
boolean.selector=db1.table1.*, db1.table2.column1

• 注意：当快照执行SHOW CREATE TABLE时，MySQL8不显示tinyint无符号类型的长度，这意味着该转换器不起作用。新选项length.checker可以解决这个问题，默认值为true。禁用 length.checker 并指定需要转换为选择器属性的列，而不是根据类型转换所有列，如下例所示：

converters=boolean
boolean.type=io.debezium.connector.mysql.converters.TinyIntOneToBooleanConverter
boolean.length.checker=false
boolean.selector=db1.table1.*, db1.table2.column1

五、Spatial types空间类型

目前，Debezium MySQL 连接器支持以下空间数据类型。

表 19. 空间类型映射的描述

MySQL type	文字类型	语义类型
GEOMETRY, LINESTRING, POLYGON, MULTIPOINT, MULTILINESTRING, MULTIPOLYGON, GEOMETRYCOLLECTION	STRUCT	io.debezium.data.geometry.Geometry包含一个具有两个字段的结构：srid（INT32：空间参考系统ID，定义结构体中存储的几何对象的类型，wkb (BYTES)：以众所周知的二进制 (wkb) 格式编码的几何对象的二进制表示形式。

六、Debezium技术总结

更多Debezium技术请参考：

• Debezium技术专栏