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 foreign_key_checks=1 and 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. Starting from v8.5.7, in this mode, DM supports static one-to-one table routing, such as schema or table renaming.

The following limitations apply to foreign key replication:

• When you enable foreign_key_checks=1 in safe mode, DM does not support UPDATE statements that modify primary key or unique key values. DM pauses the task 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 to false.
• When foreign_key_checks=1, DM does not support DDL statements that create, modify, or drop foreign key constraints during replication.
• Starting from v8.5.7, when foreign_key_checks=1 and worker-count > 1, DM supports only static one-to-one routing rules for tables with foreign keys. In this mode, DM still rejects routing rules that map multiple source tables in the task to the same target table. For non-one-to-one routing, set worker-count to 1 or modify the routing rules.
• When foreign_key_checks=1, DM does not support syncer.compact or syncer.multiple-rows, because these options can change DML statement boundaries and foreign key execution semantics.
• When foreign_key_checks=1 and worker-count > 1, DM rejects hot configuration updates that can change foreign key causality semantics, including updates to worker-count, case-sensitive, routing rules, block-allow-list or black-white-list rules, binlog event filtering rules, and foreign_key_checks. To change these settings, stop the task and restart it with the modified configuration.
• When foreign_key_checks=1, the block-allow-list must include all ancestor tables in the foreign key dependency chain. If you filter out ancestor tables, DM pauses the task with an error during incremental replication.
• When foreign_key_checks=1, foreign key metadata must be consistent between the source and downstream. If DM detects inconsistencies, run binlog-schema update --from-target to resynchronize the metadata.
• When you enable foreign_key_checks=1 in safe mode, DM does not correctly replicate ON UPDATE CASCADE if 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. DM correctly replicates UPDATE statements that do not modify key values.

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