7.4. Debezium PostgreSQL 连接器如何映射数据类型


PostgreSQL 连接器代表对带有结构的事件的更改,这些事件与行存在的表类似。事件包含每个列值的一个字段。在事件中如何代表该值取决于列的 PostgreSQL 数据类型。以下小节描述了连接器如何将 PostgreSQL 数据类型映射到 字面类型以及 事件字段中 的语义类型

  • literal type 代表值如何被代表,使用 Kafka Connect schema 类型:INT8, INT16, INT32, INT64, FLOAT32, FLOAT64, BOOLEAN, STRING, BYTES, ARRAY, MAP, 和 STRUCT
  • 语义类型 描述了 Kafka Connect 模式如何使用字段名称来捕获字段 的含义

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

以下部分详情:

基本类型

下表描述了连接器如何映射基本类型。

Expand
表 7.14. PostgreSQL 基本数据类型的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

布尔值

布尔值

不适用

BIT(1)

布尔值

不适用

BIT( > 1)

BYTES

io.debezium.data.Bits

length 模式参数包含一个代表位数的整数。生成的 byte[] 包含 little-endian 格式的位,并的大小包含指定的位数。例如,numBytes = n/8 +(n % 8 == 0 ?0 : 1) 其中 n 是位数。

位不同[(M)]

BYTES

io.debezium.data.Bits

length 模式参数包含一个整数,代表位数(2^31 - 1,如果没有为列提供长度)。生成的 byte[] 包含 little-endian 表单中的位,并根据内容的大小。指定的大小 (M) 存储在 io.debezium.data.Bits 类型的 length 参数中。

SMALLINT,SMALLSERIAL

INT16

不适用

整数, 串行

INT32

不适用

BIGINT,BIGSERIAL OID

INT64

不适用

REAL

FLOAT32

不适用

双精度

FLOAT64

不适用

CHAR[(M)]

字符串

不适用

VARCHAR[(M)]

字符串

不适用

CHARACTER[(M)]

字符串

不适用

CHARACTER VARYING[(M)]

字符串

不适用

TIMESTAMPTZ ,带有时区的时间戳

字符串

io.debezium.time.ZonedTimestamp

是带有时区信息的时间戳的字符串,其中时区为 GMT。

TIMETZ ,带有时区的时间

字符串

io.debezium.time.ZonedTime

是时区信息的字符串,其中时区为 GMT。

间隔 [P]

INT64

io.debezium.time.MicroDuration
(默认)

使用每月平均值的 365.25 / 12.0 公式的间隔的大约微秒数。

间隔 [P]

字符串

io.debezium.time.Interval
(当 interval.handling.mode 设置为 字符串

遵循特征 P<years>Y<months>Y<months>M<days>DT<hours>H<minutes>M<seconds>S 的间隔值的字符串表示,例如 P1Y2M3DT4H5M6.78S

BYTEA

BYTESSTRING

N/a

遵循原始字节(默认)、base64 编码的字符串或 base64-url-safe-encoded 字符串或十六进制编码的字符串,具体取决于连接器 的二进制处理模式 设置。

Debezium 只支持 Postgres bytea_output 配置值 hex。有关 PostgreSQL 二进制文件数据类型的更多信息,请参阅 PostgreSQL 文档

JSON, JSONB

字符串

io.debezium.data.Json

包含 JSON 文档、数组或 scalar 的字符串表示。

XML

字符串

io.debezium.data.Xml

包含 XML 文档的字符串表示。

UUID

字符串

io.debezium.data.Uuid

包含 PostgreSQL UUID 值的字符串表示。

STRUCT

io.debezium.data.geometry.Point

包含有两个 FLOAT64 字段的结构,(x,y)。每个字段代表 geometric 点的协调。

LTREE

字符串

io.debezium.data.Ltree

包含 PostgreSQL LTREE 值的字符串表示。

CITEXT

字符串

不适用

INET

字符串

不适用

INT4RANGE

字符串

N/a

整数范围。

INT8RANGE

字符串

N/A

range of bigint.

NUMRANGE

字符串

N/A

范围 数字.

TSRANGE

字符串

n/a

包含时间戳范围的字符串表示,没有时区。

TSTZRANGE

字符串

n/a

包含带有本地系统时区的时间戳范围的字符串表示。

DATERANGE

字符串

n/a

包括代表一个日期范围的字符串。它始终具有专用的上限。

ENUM

字符串

io.debezium.data.Enum

包含 PostgreSQL ENUM 值的字符串表示。允许的值集合在 允许的 schema 参数中维护。

时序类型

除 PostgreSQL 的 TIMESTAMPTZTIMETZ 数据类型外,包含时区信息,临时类型是如何映射的,具体类型取决于 time.precision.mode 连接器配置属性的值。以下小节描述了这些映射:

time.precision.mode=adaptive

当将 time.precision.mode 属性设置为 adaptive 时,连接器会根据列的数据类型定义确定字面类型和语义类型。这样可确保事件 完全 代表数据库中的值。

Expand
表 7.15. time.precision.mode 为 adaptive时的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

DATE

INT32

io.debezium.time.Date

代表自时期起的天数。

TIME (1 )、TIME (2), TIME (3)

INT32

io.debezium.time.Time

代表过去的毫秒数,不包括时区信息。

TIME (4), TIME (5), TIME (6)

INT64

io.debezium.time.MicroTime

代表过去的微秒数,不包括时区信息。

TIMESTAMP (1), TIMESTAMP (2), TIMESTAMP (3)

INT64

io.debezium.time.Timestamp

代表自 epoch 后的毫秒数,不包括时区信息。

TIMESTAMP (4), TIMESTAMP (5), TIMESTAMP (6), TIMESTAMP

INT64

io.debezium.time.MicroTimestamp

代表自 epoch 起的微秒数,不包括时区信息。

time.precision.mode=adaptive_time_microseconds

当将 time.precision.mode 配置属性设置为 adaptive_time_microseconds 时,连接器会根据列的数据类型确定 temporal 类型的字面类型和 semantic 类型。这样可确保事件 准确 代表数据库中的值,但所有 TIME 字段都捕获为微秒。

Expand
表 7.16. 当 time.precision.mode 为 adaptive_time_microseconds时映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

DATE

INT32

io.debezium.time.Date

代表自时期起的天数。

TIME([P])

INT64

io.debezium.time.MicroTime

以微秒为单位代表时间值,不包括时区信息。PostgreSQL 允许精度 P 在范围 0-6 中存储最多 microsecond 精度。

TIMESTAMP (1) , TIMESTAMP (2), TIMESTAMP (3)

INT64

io.debezium.time.Timestamp

代表 epoch 过的毫秒数,不包括时区信息。

TIMESTAMP (4) , TIMESTAMP (5), TIMESTAMP (6), TIMESTAMP

INT64

io.debezium.time.MicroTimestamp

代表 epoch 过的微秒数,不包括时区信息。

time.precision.mode=connect

当将 time.precision.mode 配置属性设为 connect 时,连接器会使用 Kafka Connect 逻辑类型。当消费者只能处理内置的 Kafka Connect 逻辑类型,且无法处理变量-precision 时间值时,这非常有用。但是,由于 PostgreSQL 支持 microsecond 精度,因此当数据库列具有大于 3 fractional second precision 值时,带有 connect 时间精度的连接器会导致 精度丢失。

Expand
表 7.17. 当 time.precision.mode 为 connect时映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

DATE

INT32

org.apache.kafka.connect.data.Date

代表自 epoch 后的天数。

TIME([P])

INT64

org.apache.kafka.connect.data.Time

代表自午夜起的毫秒数,不包括时区信息。PostgreSQL 允许 P 在范围 0-6 中存储到 microsecond 精度,但当 P 大于 3 时,这个模式会导致精度丢失。

TIMESTAMP([P])

INT64

org.apache.kafka.connect.data.Timestamp

代表自 epoch 起的毫秒数,不包括时区信息。PostgreSQL 允许 P 在范围 0-6 中存储到 microsecond 精度,但当 P 大于 3 时,这个模式会导致精度丢失。

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,NUMERICMONEY 列。这是默认的模式。

Expand
表 7.18. 当 decimal.handling.mode 准确时映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

NUMERIC[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

scale schema 参数包含一个整数,代表十进制点被转换了多少位。

DECIMAL[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

scale schema 参数包含一个整数,代表十进制点被转换了多少位。

MONEY[(M[,D])]

BYTES

org.apache.kafka.connect.data.Decimal

scale schema 参数包含一个整数,代表十进制点被转换了多少位。scale 模式参数由 money.fraction.digits 连接器配置属性决定。

此规则例外。当在没有扩展限制的情况下使用 NUMERICDECIMAL 类型时,来自数据库的值会为每个值有不同的(变量)扩展。在这种情况下,连接器使用 io.debezium.data.VariableScaleDecimal,其中包含传输的值和扩展。

Expand
表 7.19. 没有扩展限制时 DECIMAL 和 NUMERIC 类型的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

数字

STRUCT

io.debezium.data.VariableScaleDecimal

Contains 一个结构,它有两个字段:类型为 INT32 的扩展,其中包含未 扩展 格式的传输 和值 BYTES

十进制

STRUCT

io.debezium.data.VariableScaleDecimal

Contains 一个结构,它有两个字段:类型为 INT32 的扩展,其中包含未 扩展 格式的传输 和值 BYTES

当将 decimal.handling.mode 属性设置为 double 时,连接器代表所有 DECIMALNUMERICMONEY 值作为 Java 双值,并对它们进行编码,如下表所示。

Expand
表 7.20. 当 decimal.handling.mode 为 双时的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(schema name)

NUMERIC[(M[,D])]

FLOAT64

 

DECIMAL[(M[,D])]

FLOAT64

 

MONEY[(M[,D])]

FLOAT64

 

decimal.handling.mode 配置属性的最后可能设置为 字符串。在这种情况下,连接器代表 DECIMALNUMERICMONEY 值作为其格式化的字符串表示,并对它们进行编码,如下表所示。

Expand
表 7.21. 当 decimal.handling.mode 是 字符串时的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(schema name)

NUMERIC[(M[,D])]

字符串

 

DECIMAL[(M[,D])]

字符串

 

MONEY[(M[,D])]

字符串

 

当将 decimal.handling.mode字符串 时,PostgreSQL 支持 NaN (不是数字)作为存储在 DECIMAL/NUMERIC 值中的特殊值。在这种情况下,连接器将 NaN 编码为 Double.NaN 或字符串常量 NAN

HSTORE 类型

PostgreSQL 连接器配置属性 hstore.handling.mode 的设置决定了连接器如何映射 HSTORE 值。

dhstore.handling.mode 属性设置为 json (默认值)时,连接器将 HSTORE 值表示为 JSON 值的字符串表示,如下表所示。当 hstore.handling.mode 属性设置为 map 时,连接器使用 HSTORE 值的 MAP 模式类型。

Expand
表 7.22. HSTORE 数据类型的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

HSTORE

字符串

io.debezium.data.Json

示例:使用 JSON 转换的输出表示为 {"key" : "val"}

HSTORE

MAP

n/a

示例:使用 JSON 转换程序的输出表示为 {"key" : "val"}

域类型

PostgreSQL 支持基于其他底层类型的用户定义的类型。使用此类列类型时,Debezium 会根据完整的类型层次结构公开列的表示。

重要

捕获使用 PostgreSQL 域类型的列的更改需要特别考虑。当定义列以包含扩展默认数据库类型的域类型,并且域类型定义了自定义长度或规模时,生成的模式将继承该定义长度或规模的模式。

当定义列包含扩展自定义长度或规模的另一个域类型的域类型时,生成的模式 不会继承 定义的长度或扩展,因为 PostgreSQL 驱动程序的列元数据中没有这些信息。

网络地址类型

PostgreSQL 具有可以存储 IPv4、IPv6 和 MAC 地址的数据类型。最好使用这些类型而不是纯文本类型来存储网络地址。网络地址类型提供输入错误检查和专用操作器和功能。

Expand
表 7.23. 网络地址类型的映射
PostgreSQL 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

INET

字符串

N/a

IPv4 和 IPv6 网络

CIDR

字符串

N/a

IPv4 和 IPv6 主机和网络

MACADDR

字符串

N/A

MAC 地址

MACADDR8

字符串

N/a

MAC 地址( EUI-64 格式)

PostGIS 类型

PostgreSQL 连接器支持所有 PostGIS 数据类型

Expand
表 7.24. PostGIS 数据类型的映射
PostGIS 数据类型字面类型(schema 类型)语义类型(模式名称)和备注

GEOMETRY
(计划)

STRUCT

io.debezium.data.geometry.Geometry

包含有两个字段的结构:

  • srid (INT32) - Spatial Reference System Identifier,用于定义存储在结构中的 geometry 对象类型。
  • wkb (BYTES) - 以 Well-Known-Binary 格式编码的 geometry 对象的二进制表示。

有关格式详情,请参阅 Open Geospatial Consortium Simple Features Access specification

GEOGRAPHY
(设备)

STRUCT

io.debezium.data.geometry.Geography

包含有两个字段的结构:

  • srid (INT32) - Spatial Reference System Identifier,用于定义存储在结构中的geography 对象类型。
  • wkb (BYTES) - 以 Well-Known-Binary 格式编码的 geometry 对象的二进制表示。

有关格式详情,请参阅 Open Geospatial Consortium Simple Features Access specification

要粘贴的值

PostgreSQL 对页面大小具有硬限制。这意味着,大于 8 KB 的值需要使用 TOAST 存储来存储。这会影响来自数据库的复制消息。使用 TOAST 机制存储的值且尚未更改的值不会包含在消息中,除非它们是表的副本身份的一部分。Debezium 无法安全地从数据库读取缺少的值,因为这可能导致竞争条件。因此,Debezium 遵循这些规则来处理粘贴值:

  • 具有 REPLICA IDENTITY FULL 的表 - TOAST 列值是更改事件的 beforeafter 字段的一部分,就像任何其他列一样。
  • 带有 REPLICA IDENTITY DEFAULT 的表 - 从数据库接收 UPDATE 事件时,任何没有包括在事件中的 TOAST 列值。同样,在收到 DELETE 事件时,如果是 TOAST,则没有 TOAST 列(若有)。因为 Debezium 无法安全地提供列值,因此连接器会返回一个占位符值,如连接器配置属性 unavailable.value.placeholder 定义。

默认值

如果为数据库模式中的列指定了默认值,PostgreSQL 连接器将尽可能尝试将此值传播到 Kafka 模式。最常见的数据类型受到支持,包括:

  • 布尔值
  • 数字类型(INTFLOATNUMERIC 等)
  • 文本类型(CHARVARCHARTEXT 等)
  • 时序类型(DATE,TIME,INTERVAL,TIMESTAMP,TIMESTAMPTZ)
  • JSON,JSONB,XML
  • UUID

请注意,对于临时类型,对默认值的解析由 PostgreSQL 库提供;因此,PostgreSQL 通常支持的任何字符串表示也应该被连接器支持。

如果默认值由函数生成,而不是直接指定,则连接器将为给定的数据类型导出等效的 0。这些值包括:

  • FALSE for BOOLEAN
  • 0 带有适当的精度,用于数字类型
  • text/XML 类型的空字符串
  • JSON 类型的 {}
  • 1970-01-01 for DATE,TIMESTAMP,TIMESTAMPTZ 类型
  • TIME00:00
  • INTERVALEPOCH
  • 00000000-0000-0000-0000-000000000000 用于 UUID

目前,这个支持只扩展到明确使用功能。例如,CURRENT_TIMESTAMP (6) 支持括号,但 CURRENT_TIMESTAMP 不支持。

重要

当将 PostgreSQL 连接器与强制实施模式版本间兼容的模式 registry 时,支持对默认值的传播主要允许安全模式演进。由于这个主要关注,以及不同插件的刷新行为,Kafka 模式中存在的默认值无法保证始终与数据库模式中的默认值同步。

  • 默认值可能会在 Kafka 模式中显示"late",具体取决于给定插件触发刷新内存模式的时间/方式。如果默认更改多次更改,则值永远不会在 Kafka 模式中显示/被跳过
  • 如果在连接器等待处理记录时触发模式刷新,则默认值可能会在 Kafka 模式中出现 'early'。这是因为列元数据在刷新时从数据库读取,而不是在复制消息中存在。如果连接器后端并出现刷新,或者如果连接器在更新继续写入源数据库时停止了连接器,则可能会发生这种情况。

此行为可能是意外的,但它仍然是安全的。只有架构定义会受到影响,而消息中存在的实际值将与写入源数据库的实际值保持一致。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2025 Red Hat