TiDB Data Migration 兼容性目录

TiDB Data Migration (DM) 数据迁移工具可以将数据从不同类型的数据源迁移到 TiDB 集群。针对各种数据源类型，DM 定义了以下四种兼容性级别：

• 正式支持 (GA)：该场景已经过验证，并且通过了完整的测试流程。
• 实验支持：常见的应用场景已验证，但覆盖范围有限，或仅涉及少量用户。可能会偶发问题，因此需要在你的具体场景中验证兼容性。
• 未测试：DM 尽量保证兼容 MySQL 协议和 binlog，但并非所有 MySQL 分支或版本都包含在 DM 的测试矩阵中。如果某个分支或版本使用了与 MySQL 兼容的协议和 binlog 格式，理论上应能正常工作，但在使用前必须在你自己的环境中验证兼容性。
• 不兼容：DM 存在已知不兼容的情况，不建议在生产环境中使用。

数据源

外键 CASCADE 操作

i

警告：

该功能为实验特性。不建议在生产环境中使用。该功能可能会在未事先通知的情况下发生变化或删除。如果发现 bug，请在 GitHub 上提 issue 反馈。

从 v8.5.6 开始，DM 以实验特性支持同步包含外键约束的表。该支持包括以下改进：

• 安全模式：在安全模式执行期间，DM 会在每个批次中设置 foreign_key_checks=0，并对未修改主键或唯一键值的 UPDATE 语句跳过冗余的 DELETE 步骤。这可以防止 REPLACE INTO（其内部执行为 DELETE + INSERT）在子表行上触发非预期的 ON DELETE CASCADE 效果。详情参见 DM 安全模式。
• 多 worker 因果关系：当 foreign_key_checks=1 且 worker-count > 1 时，DM 会在任务启动时从下游 schema 中读取外键关系并注入因果键。这可确保父表行的 DML 操作先于其依赖的子表行操作完成，从而在多个 worker 之间保持 binlog 顺序。从 v8.5.7 开始，在此模式下，DM 支持静态的一对一路由，例如 schema 或表重命名。

i

注意

在迁移包含外键的表之前，请确保上游 schema 使用标准的外键定义。例如，子表外键应引用父表中的完整主键或唯一键。非标准定义（例如仅引用复合主键的一部分）可能会导致上游数据库中的级联行为不一致。DM 不会在同步过程中修正此类 schema 问题。

同步包含外键约束的表存在以下限制：

• 当你在安全模式下启用 foreign_key_checks=1 时，DM 不支持修改主键或唯一键值的 UPDATE 语句。DM 会暂停任务，并报错：safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported。如需同步此类语句，请将 safe-mode 设置为 false。
• 当 foreign_key_checks=1 时，DM 不支持在同步过程中执行创建、修改或删除外键约束的 DDL 语句。
• 从 v8.5.7 开始，当 foreign_key_checks=1 且 worker-count > 1 时，DM 仅支持对包含外键的表使用静态一对一路由规则。在此模式下，DM 仍会拒绝将任务中的多个源表映射到同一个目标表的路由规则。对于非一对一路由，请将 worker-count 设置为 1 或修改路由规则。
• 当 foreign_key_checks=1 时，DM 不支持 syncer.compact 或 syncer.multiple-rows，因为这些选项可能会改变 DML 语句边界和外键执行语义。
• 当 foreign_key_checks=1 且 worker-count > 1 时，DM 会拒绝可能改变外键因果关系语义的热更新配置，包括更新 worker-count、case-sensitive、路由规则、block-allow-list 或 black-white-list 规则、binlog 事件过滤规则以及 foreign_key_checks。如需更改这些设置，请停止任务并使用修改后的配置重新启动任务。
• 当 foreign_key_checks=1 时，block-allow-list 必须包含外键依赖链中的所有祖先表。如果过滤掉祖先表，DM 会在增量复制期间报错并暂停任务。
• 当 foreign_key_checks=1 时，源端与下游的外键元信息必须保持一致。如果 DM 检测到不一致，请运行 binlog-schema update --from-target 以重新同步元信息。
• 当你在安全模式下启用 foreign_key_checks=1 时，如果某个 UPDATE 修改了主键或唯一键值，DM 无法正确同步 ON UPDATE CASCADE。这是因为 DM 会将此类语句改写为 DELETE + REPLACE，从而触发 ON DELETE 行为而不是 ON UPDATE 行为。在这种情况下，DM 会拒绝该语句并暂停任务。DM 可以正确同步未修改键值的 UPDATE 语句。

在 v8.5.6 之前的版本中，DM 会在下游创建外键约束，但由于其将会话变量 foreign_key_checks=OFF，这些约束不会被强制执行。因此，级联操作不会被同步到下游。

MariaDB 说明

• 对于 MariaDB 10.5.11 及更高版本，由于权限名称发生变化（例如 BINLOG MONITOR、REPLICATION SLAVE ADMIN、REPLICATION MASTER ADMIN），DM 前置检查会失败。报错信息显示为 [code=26005] fail to check synchronization configuration，出现在复制权限、导出权限和导出连接数检查中。
• 你可以通过在 DM 任务中添加 ignore-checking-items: ["all"] 来绕过前置检查。详情参见 DM 前置检查。

目标数据库

i

警告：

不建议使用 DM v5.3.0。在 DM v5.3.0 中启用 GTID 复制但未启用 relay log 时，尽管概率较低，但可能会导致数据复制失败。