master: clarify DM foreign key support for one-to-one routing (#23153)

Author: OliverS929

dm/dm-compatibility-catalog.md

@@ -36,16 +36,22 @@ DM supports migrating data from different sources to TiDB clusters. Based on the
 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](/dm/dm-safe-mode.md#foreign-key-handling-new-in-v856).
-- **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.
+- **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.
+
+> **Note:**
+>
+> Before you migrate tables with foreign keys, make sure that the upstream schema uses standard foreign key definitions. For example, a child foreign key should reference a complete primary key or unique key in the parent table. Non-standard definitions, such as referencing only part of a composite primary key, can cause inconsistent cascade behavior in the upstream database. DM does not correct such schema issues during replication.
 
 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 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.
-- 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.
+- 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`](/system-variables.md#foreign_key_checks). As a result, cascading operations are not replicated to the downstream.
 

dm/dm-safe-mode.md

@@ -136,7 +136,9 @@ This session-level setting introduces a small overhead per batch (two `SET SESSI
 
 ### Multi-worker foreign key causality
 
-When you set `worker-count` to a value greater than 1 and the replication task includes tables with foreign keys, DM reads foreign key relationships from the downstream `CREATE TABLE` schema when the task starts. For each DML operation, DM injects causality keys based on these relationships. This ensures that operations on parent rows and their dependent child rows are assigned to the same DML worker queue.
+If `foreign_key_checks=1`, `worker-count > 1`, and the replication task includes tables with foreign keys, DM reads foreign key relationships from the downstream `CREATE TABLE` schema when the task starts. For each DML operation, DM injects causality keys based on these relationships. This ensures that DM assigns operations on parent rows and their dependent child rows to the same DML worker queue.
+
+Starting from v8.5.7, in this mode, DM supports static one-to-one table routing, such as schema or table renaming. DM still rejects routing rules that map multiple source tables in the task to the same target table.
 
 For detailed constraints, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations).