Compatibility Catalog of TiDB Data Migration

DM supports migrating data from different sources to TiDB clusters. Based on the data source type, DM has four compatibility levels:

• Generally available (GA): The application scenario has been verified and passed GA testing.
• Experimental: Common application scenarios have been verified, but coverage is limited or involves only a small number of users. Occasional issues are possible, so you need to verify compatibility in your specific scenario.
• Not tested: DM aims to be compatible with the MySQL protocol and binlog. However, not all MySQL forks or versions are included in the DM test matrix. If a fork or version uses MySQL-compatible protocols and binlog formats, it is expected to work, but you must verify compatibility in your own environment before use.
• Incompatible: DM has known blocking issues, so production use is not recommended.

Data sources

Foreign key CASCADE operations

Starting from v8.5.6, DM provides experimental support for replicating tables that use foreign key constraints. This support includes the following improvements:

• Safe mode: during safe mode execution, DM sets foreign_key_checks=0 for each batch and skips the redundant DELETE step for UPDATE statements that do not modify primary key or unique key values. This prevents REPLACE INTO (which internally performs DELETE + INSERT) from triggering unintended ON DELETE CASCADE effects on child rows. For more information, see DM safe mode.
• Multi-worker causality: when worker-count > 1, DM reads foreign key relationships from the downstream schema at task start and injects causality keys. This ensures that DML operations on parent rows complete before operations on dependent child rows, preserving binlog order across workers.

The following limitations apply to foreign key replication:

• In safe mode, DM does not support UPDATE statements that modify primary key or unique key values. The task is paused with the error safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported. To replicate such statements, set safe-mode: false.
• When foreign_key_checks=1, DM does not support DDL statements that create, modify, or drop foreign key constraints during replication.
• Table routing is not supported when worker-count > 1. If you use table routing with tables that include foreign keys, set worker-count to 1.
• The block-allow list must include all ancestor tables in the foreign key dependency chain. If ancestor tables are filtered out, the task is paused with an error during incremental replication.
• Foreign key metadata must be consistent between the source and downstream. If inconsistencies are detected, run binlog-schema update --from-target to resynchronize metadata.
• ON UPDATE CASCADE is not correctly replicated in safe mode when an UPDATE modifies primary key or unique key values. DM rewrites such statements as DELETE + REPLACE, which triggers ON DELETE actions instead of ON UPDATE actions. In this case, DM rejects the statement and pauses the task. UPDATE statements that do not modify key values are replicated correctly.

In versions earlier than v8.5.6, DM creates foreign key constraints in the downstream but does not enforce them because it sets the session variable foreign_key_checks=OFF. As a result, cascading operations are not replicated to the downstream.

MariaDB notes

• For MariaDB 10.5.11 and later, the DM precheck fails due to privilege name changes (for example, BINLOG MONITOR, REPLICATION SLAVE ADMIN, REPLICATION MASTER ADMIN). The error appears as [code=26005] fail to check synchronization configuration in the replication privilege, dump privilege, and dump connection number checkers.
• You can bypass the precheck by adding ignore-checking-items: ["all"] in the DM task. See DM precheck for details.

Target databases