📣
TiDB Cloud Essential 开放公测中。立即试用 →
​
AI
应用开发
最佳实践
API
​

TiCDC 兼容性

本文介绍了与 TiCDC 有关的一系列兼容性问题及其处理方案。

TiCDC 新架构与 TiDB 集群的兼容性

TiCDC 新架构支持 v7.5.0 及以上版本的 TiDB 集群，部分特殊的兼容性说明可参考：TiCDC 兼容性说明。

TiCDC 与 TiDB Lightning 的兼容性

TiDB Lightning 支持逻辑导入模式和物理导入模式两种数据导入模式。本章节介绍这两种模式与 TiCDC 的兼容性，以及同时使用 TiDB Lightning 和 TiCDC 时的操作步骤。

在逻辑导入模式下，TiDB Lightning 通过执行 SQL 语句导入数据。此模式与 TiCDC 兼容。你可以按照以下步骤同时使用 TiDB Lightning 逻辑导入模式和 TiCDC 进行数据同步：

  1. 创建 changefeed，详情参考创建同步任务。
  2. 启动 TiDB Lightning 并使用逻辑模式模式导入数据，详情参考使用逻辑导入模式。

在物理导入模式下，TiDB Lightning 通过向 TiKV 插入 SST 文件的方式导入数据。TiCDC 与此模式不兼容，不支持同步通过物理模式导入的数据。如果你需要同时使用 TiDB Lightning 物理导入模式和 TiCDC，可以根据 TiCDC 下游系统的类型选择以下解决方案：

  • 下游系统是 TiDB 集群：

    1. 使用 TiDB Lightning 分别向上下游 TiDB 集群导入数据，以确保两个集群的数据一致性。
    2. 创建 changefeed，用于同步后续通过 SQL 写入的增量数据。详情参考创建同步任务。

  • 下游系统不是 TiDB 集群：

    1. 使用下游系统提供的离线导入工具，将 TiDB Lightning 的输入文件导入到下游系统。
    2. 创建 changefeed，用于同步后续通过 SQL 写入的增量数据。详情参考创建同步任务。

TiCDC 与 TiFlash 的兼容性

目前，使用 TiCDC 同步表到下游 TiDB 集群时，不支持为表创建 TiFlash 副本，即 TiCDC 不支持同步 TiFlash 相关的 DDL，例如：

  • ALTER TABLE table_name SET TIFLASH REPLICA count;
  • ALTER DATABASE db_name SET TIFLASH REPLICA count;

历史版本升级的兼容性说明

TiCDC 依赖 TiDB、TiKV 和 PD 提供的上游变更数据及相关接口。随着 TiDB 及相关组件的持续演进，这些数据格式和接口可能发生变化，例如 TiDB 的并行 DDL、快速建表等功能会修改相关逻辑和数据处理流程，TiCDC 需要进行相应适配。因此，老架构 TiCDC 不保证在跨版本的 TiDB/TiKV/PD 混合部署环境中提供正式的向上和向下兼容性。新架构 TiCDC 支持对 v7.5.0 及以上版本的 TiDB 集群提供向下兼容性。

老架构 TiCDC 升级建议

对于老架构 TiCDC，不建议在 TiDB 滚动升级期间持续运行 Changefeed。升级时，建议按以下顺序执行：

  1. 暂停所有 Changefeed。
  2. 先升级 TiCDC。
  3. 再升级 TiDB 集群中的其他组件。
  4. 升级完成后，恢复 Changefeed。

例如，假设将集群从 v8.5.4 升级到 v8.5.5，如果使用 TiUP 管理集群，可以参考以下命令（以下示例以 linux-amd64 为例，其他平台请根据实际环境替换包名中的平台信息）：

# 1. 暂停所有 Changefeed（需对每个 Changefeed 分别执行一次）。
tiup cdc:v8.5.4 cli changefeed pause \
  --server=http://<ticdc-host>:8300 \
  --changefeed-id=<changefeed-id>

# 2. 先升级 TiCDC。
wget https://tiup-mirrors.pingcap.com/cdc-v8.5.5-linux-amd64.tar.gz \
  -O /tmp/cdc-v8.5.5-linux-amd64.tar.gz
tiup cluster patch <cluster-name> /tmp/cdc-v8.5.5-linux-amd64.tar.gz -R cdc

# 3. 再升级 TiDB 集群中的其他组件。
#    需根据集群中实际存在的组件分别执行。以下示例包括 PD、TiKV 和 TiDB。
wget https://tiup-mirrors.pingcap.com/pd-v8.5.5-linux-amd64.tar.gz \
  -O /tmp/pd-v8.5.5-linux-amd64.tar.gz
wget https://tiup-mirrors.pingcap.com/tikv-v8.5.5-linux-amd64.tar.gz \
  -O /tmp/tikv-v8.5.5-linux-amd64.tar.gz
wget https://tiup-mirrors.pingcap.com/tidb-v8.5.5-linux-amd64.tar.gz \
  -O /tmp/tidb-v8.5.5-linux-amd64.tar.gz

tiup cluster patch <cluster-name> /tmp/pd-v8.5.5-linux-amd64.tar.gz -R pd
tiup cluster patch <cluster-name> /tmp/tikv-v8.5.5-linux-amd64.tar.gz -R tikv
tiup cluster patch <cluster-name> /tmp/tidb-v8.5.5-linux-amd64.tar.gz -R tidb

# 如果集群中还包含 TiFlash、TiProxy、TiKV-CDC 等组件，也需按相同方式分别执行 patch。

# 4. 升级完成后，恢复所有 Changefeed（需对每个 Changefeed 分别执行一次）。
tiup cdc:v8.5.5 cli changefeed resume \
  --server=http://<ticdc-host>:8300 \
  --changefeed-id=<changefeed-id>

新架构 TiCDC 升级建议

新架构 TiCDC 在 TiDB 集群滚动升级期间能够持续运行 Changefeed，但前提是升级之前的 TiCDC 已经是新架构 TiCDC。

如果需要在 TiCDC 新老架构之间进行升级或切换，请参阅 TiCDC 新架构升级指南。

命令行参数和配置文件兼容性

  • TiCDC v4.0.0 中移除了 ignore-txn-commit-ts，添加了 ignore-txn-start-ts，使用 start_ts 过滤事务。
  • TiCDC v4.0.2 中移除了 db-dbs/db-tables/ignore-dbs/ignore-tables，添加了 rules，使用新版的数据库和数据表过滤规则，详细语法参考表库过滤。
  • 从 TiCDC v6.2.0 开始，cdc cli 将通过 TiCDC 的 Open API 直接与 TiCDC server 进行交互，而不再需要访问 PD。cdc cli 子命令中的 --pd 参数被废除，增加了 --server 参数，用于指定 TiCDC Server 地址。请使用 --server 参数替代 --pd 参数。
  • 从 v6.4.0 开始，TiCDC 使用 Syncpoint 功能需要同步任务拥有下游集群的 SYSTEM_VARIABLES_ADMIN 或者 SUPER 权限。

兼容性问题处理

本节介绍了兼容性相关的问题。

使用 TiCDC v5.0.0-rc 版本的 cdc cli 工具操作 v4.0.x 集群导致不兼容问题

使用 TiCDC v5.0.0-rc 版本的 cdc cli 工具操作 v4.0.x 版本的 TiCDC 集群时，可能会遇到如下异常情况：

  • 若 TiCDC 集群版本为 v4.0.8 或以下，使用 v5.0.0-rc 版本的 cdc cli 创建同步任务 changefeed 时，可能导致 TiCDC 集群陷入异常状态，导致同步卡住。
  • 若 TiCDC 集群版本为 v4.0.9 或以上，使用 v5.0.0-rc 版本的 cdc cli 创建同步任务 changefeed，会导致 Old Value 和 Unified Sorter 特性被非预期地默认开启。

处理方案：

使用和 TiCDC 集群版本对应的 cdc 可执行文件进行如下操作：

  1. 删除使用 v5.0.0-rc 版本创建的 changefeed，例如：tiup cdc:v4.0.9 cli changefeed remove -c xxxx --pd=xxxxx --force。
  2. 如果 TiCDC 同步已经卡住，重启 TiCDC 集群，例如：tiup cluster restart <cluster_name> -R cdc。
  3. 重新创建 changefeed，例如：tiup cdc:v4.0.9 cli changefeed create --sink-uri=xxxx --pd=xxx。

sort-dir 及 data-dir 配置项的兼容性说明

sort-dir 配置项用于给 TiCDC 内部的排序器指定临时文件目录，其作用在各版本有过如下兼容性更改：

版本sort-engine 的使用说明使用建议
v4.0.11 及之前的 v4.0 版本，v5.0.0-rc作为 changefeed 配置项，给 file sorter 和 unified Sorter 指定临时文件目录在这些版本中，file sorter 和 unified sorter 均不是正式功能 (GA)，不推荐在生产环境中使用。

如果有多个 changefeed 被配置使用了 unified 作为 sort-engine，那么实际使用的临时文件目录可能是任何一个 changefeed 的 sort-dir 配置，且每个 TiCDC 节点上使用的目录可能不一致。		不推荐在生产环境中使用 Unified Sorter
v4.0.12，v4.0.13，v5.0.0 及 v5.0.1作为 changefeed 配置项或 cdc server 配置项在默认情况下 changefeed 的 sort-dir 配置不会生效，而 cdc server 的 sort-dir 配置默认为 /tmp/cdc_sort。建议生产环境下仅配置 cdc server 的相关配置。

如果你使用 TiUP 部署 TiCDC，建议升级到最新的 TiUP 版本并在 TiCDC server 配置中设置 sorter.sort-dir 一项。

在 v4.0.13、v5.0.0 和 v5.0.1 中 unified sorter 是默认开启的，如果要将集群升级至这些版本，请确保 TiCDC server 配置中的 sorter.sort-dir 已经被正确配置。		需要通过 cdc server 命令行参数（或 TiUP）配置 sort-dir
v4.0.14 及之后的 v4.0 版本，v5.0.3 及之后的 v5.0 版本，更新的版本sort-dir 被弃用，建议配置 data-dirdata-dir 可以通过最新版本的 TiUP 进行配置。这些版本中 unified sorter 是默认开启的，升级时请确保 data-dir 已经被正确配置，否则将默认使用 /tmp/cdc_data。

如果该目录所在设备空间不足，有可能出现硬盘空间不足的问题。之前配置的 changefeed 的 sort-dir 配置将会失效。		需要通过 cdc server 命令行参数（或 TiUP）配置 data-dir
v6.0.0 及之后版本data-dir 被用来存放 TiCDC 生成的临时文件在该版本之后，TiCDC 默认采用 db sorter 作为内部的排序引擎，它使用 data-dir 作为磁盘目录。需要通过 cdc server 命令行参数（或 TiUP）配置 data-dir

全局临时表兼容性说明

TiCDC 从 v5.3.0 开始支持全局临时表。

你需要使用 TiCDC v5.3.0 及以上版本同步全局临时表到下游。低于该版本，会导致表定义错误。

如果 TiCDC 的上游集群包含全局临时表，下游集群也必须是 TiDB 5.3.0 及以上版本，否则同步报错。

向量数据类型兼容性说明

从 v8.4.0 开始，TiCDC 支持同步包含向量数据类型的表到下游（实验特性）。

当下游为 Kafka 或者存储服务（如：Amazon S3、GCS、Azure Blob Storage 和 NFS）时，TiCDC 会将向量数据类型转为字符串类型进行写入。

当下游为不支持向量类型的 MySQL 兼容数据库时，涉及向量类型的 DDL 事件无法成功写入。在这种情况下，请在 sink-url 中添加配置参数 has-vector-type=true，然后 TiCDC 会将向量数据类型转为 LONGTEXT 类型进行写入。

文档内容是否有帮助？