v8.5.6: dm experimentally supports foreign key (#22616)#22740
Merged
ti-chi-bot[bot] merged 6 commits intopingcap:feature/preview-v8.5.6from Apr 13, 2026
Merged
Conversation
Update four docs pages to reflect DM's experimental FK support shipping in v8.5.6 (PRs pingcap#12351, pingcap#12414, pingcap#12329). All behaviors validated against a live build (v8.5.5-12-gd6d53adbe, 13 test scenarios, all passing). dm/dm-safe-mode.md: - Add "Foreign key handling (experimental)" section with three subsections: non-key UPDATE optimization, session-level foreign_key_checks toggle, and multi-worker FK causality - Add forward-reference from Working principle section to FK handling - Document PK/UK guardrail: task pauses, not silent cascade dm/dm-compatibility-catalog.md: - Rename section from "Incompatibility with foreign key CASCADE operations" to "Foreign key CASCADE operations" - Add experimental support description with safe mode and causality details - List validated constraints: PK/UK guardrail, DDL rejection, routing limitation, BAL ancestor requirement, ON UPDATE CASCADE mismatch - Preserve pre-v8.5.6 behavior description for older versions dm/dm-precheck.md: - Update FK warning: TiDB supports FKs (GA since v8.5.0), DM has experimental support since v8.5.6. Link to compatibility catalog. foreign-key.md: - Replace blanket "DM does not support foreign keys" with experimental v8.5.6 support, warning block, and backward-compat note
All 10 suggestions accepted:
- Sentence case headings with backticks for SQL keywords/variables:
CASCADE, UPDATE, foreign_key_checks
- Second person ("you") in constraint bullets, safe mode intro,
and foreign-key.md DM section
- Active voice: "DM returns/rejects" instead of passive "is returned"
- Bridge sentence for pre-v8.5.6 backward compat note
Style and clarity improvements across four files per Oreoxmt's review on pingcap#22616: active voice, second person, sentence-case headings, consistent terminology (modify/unique key values), anchor fix (foreign-key-handling), and version-mark span for the new section.
Co-authored-by: Grace Cai <qqzczy@126.com>
ti-chi-bot
added
lgtm
size/M
14 tasks
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces documentation for the experimental support of foreign key constraint replication in DM starting from version 8.5.6. The updates cover safe mode optimizations, multi-worker causality, and various operational limitations across several files. The review feedback suggests improving clarity and readability by consistently using the active voice and addressing the user directly as "you," in accordance with the repository's style guide.
Comment on lines
+43
to
+48
| - 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. |
Contributor
There was a problem hiding this comment.
This list of limitations contains several sentences that use passive voice, such as "The task is paused" and "ON UPDATE CASCADE is not correctly replicated". According to the style guide (lines 43-46), it's better to use active voice for clarity. Addressing the user with "you" where appropriate would also improve readability, as per line 22 of the style guide.
Suggested change
| - 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 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: 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, DM pauses the task with an error during incremental replication. | |
| - Foreign key metadata must be consistent between the source and downstream. If you detect inconsistencies, run `binlog-schema update --from-target` to resynchronize metadata. | |
| - DM does not correctly replicate `ON UPDATE CASCADE` 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. DM replicates `UPDATE` statements that do not modify key values correctly. |
References
- The style guide recommends using active voice instead of passive voice (e.g., 'TiUP starts the cluster' instead of 'The cluster is started by TiUP'). It also recommends addressing users in the second person ('you'). (link)
| - 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`](/system-variables.md#foreign_key_checks). As a result, cascading operations are not replicated to the downstream. |
Contributor
There was a problem hiding this comment.
The phrase "cascading operations are not replicated to the downstream" uses passive voice. According to the style guide (lines 43-46), it's better to use active voice.
Suggested change
| 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. | |
| 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, DM does not replicate cascading operations to the downstream. |
References
- The style guide recommends using active voice instead of passive voice (e.g., 'TiUP starts the cluster' instead of 'The cluster is started by TiUP'). (link)
|
|
||
| ### Non-key `UPDATE` optimization | ||
|
|
||
| For `UPDATE` statements that do not modify primary key or unique key values, DM skips the `DELETE` step and executes only `REPLACE INTO`. Because the primary key remains unchanged, `REPLACE INTO` overwrites the existing row without triggering foreign key cascade deletes. This optimization is applied automatically in safe mode. |
Contributor
There was a problem hiding this comment.
The sentence "This optimization is applied automatically in safe mode" uses passive voice. According to the style guide (lines 43-46), it's better to use active voice.
Suggested change
| For `UPDATE` statements that do not modify primary key or unique key values, DM skips the `DELETE` step and executes only `REPLACE INTO`. Because the primary key remains unchanged, `REPLACE INTO` overwrites the existing row without triggering foreign key cascade deletes. This optimization is applied automatically in safe mode. | |
| For `UPDATE` statements that do not modify primary key or unique key values, DM skips the `DELETE` step and executes only `REPLACE INTO`. Because the primary key remains unchanged, `REPLACE INTO` overwrites the existing row without triggering foreign key cascade deletes. DM applies this optimization automatically in safe mode. |
References
- The style guide recommends using active voice instead of passive voice (e.g., 'TiUP starts the cluster' instead of 'The cluster is started by TiUP'). (link)
|
|
||
| > **Warning:** | ||
| > | ||
| > When `foreign_key_checks=1`, DM does not support replicating `UPDATE` statements that modify primary key or unique key values. In this case, the replication task is paused with the error `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate such `UPDATE` statements on tables with foreign keys, set `safe-mode: false`. |
Contributor
There was a problem hiding this comment.
The phrase "the replication task is paused" uses passive voice. The style guide (lines 43-46) recommends using active voice. Also, addressing the user directly with "you" would improve clarity, as per line 22 of the style guide.
Suggested change
| > When `foreign_key_checks=1`, DM does not support replicating `UPDATE` statements that modify primary key or unique key values. In this case, the replication task is paused with the error `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate such `UPDATE` statements on tables with foreign keys, set `safe-mode: false`. | |
| > When `foreign_key_checks=1`, DM does not support replicating `UPDATE` statements that modify primary key or unique key values. In this case, DM pauses the replication task with the error `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate such `UPDATE` statements on tables with foreign keys, you need to set `safe-mode: false`. |
References
- The style guide recommends using active voice instead of passive voice (e.g., 'TiUP starts the cluster' instead of 'The cluster is started by TiUP'). It also recommends addressing users in the second person ('you'). (link)
|
|
||
| ### 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. |
Contributor
There was a problem hiding this comment.
The phrase "are assigned to the same DML worker queue" uses passive voice. The style guide (lines 43-46) recommends using active voice for better clarity.
Suggested change
| 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. | |
| 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 DM assigns operations on parent rows and their dependent child rows to the same DML worker queue. |
References
- The style guide recommends using active voice instead of passive voice (e.g., 'TiUP starts the cluster' instead of 'The cluster is started by TiUP'). (link)
| <CustomContent platform="tidb"> | ||
|
|
||
| - [DM](/dm/dm-overview.md) does not support foreign keys. DM disables the [`foreign_key_checks`](/system-variables.md#foreign_key_checks) of the downstream TiDB when replicating data to TiDB. Therefore, the cascading operations caused by foreign keys are not replicated from the upstream to the downstream, which might cause data inconsistency. | ||
| - [DM](/dm/dm-overview.md): starting from v8.5.6, DM supports replicating tables that use foreign key constraints as an experimental feature. For supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). In versions earlier than v8.5.6, DM disables the [`foreign_key_checks`](/system-variables.md#foreign_key_checks) system variable when replicating data to TiDB, so cascading operations are not replicated to the downstream cluster. |
Contributor
There was a problem hiding this comment.
The phrase "cascading operations are not replicated to the downstream cluster" uses passive voice. According to the style guide (lines 43-46), it's better to use active voice.
Suggested change
| - [DM](/dm/dm-overview.md): starting from v8.5.6, DM supports replicating tables that use foreign key constraints as an experimental feature. For supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). In versions earlier than v8.5.6, DM disables the [`foreign_key_checks`](/system-variables.md#foreign_key_checks) system variable when replicating data to TiDB, so cascading operations are not replicated to the downstream cluster. | |
| - [DM](/dm/dm-overview.md): starting from v8.5.6, DM supports replicating tables that use foreign key constraints as an experimental feature. For supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). In versions earlier than v8.5.6, DM disables the [`foreign_key_checks`](/system-variables.md#foreign_key_checks) system variable when replicating data to TiDB, so DM does not replicate cascading operations to the downstream cluster. |
References
- The style guide recommends using active voice instead of passive voice (e.g., 'TiUP starts the cluster' instead of 'The cluster is started by TiUP'). (link)
Collaborator
|
/cc @Oreoxmt |
Oreoxmt
approved these changes
Apr 13, 2026
Collaborator
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Oreoxmt The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
ti-chi-bot
bot
merged commit 08a4a89
into
pingcap:feature/preview-v8.5.6
12 checks passed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is an automated cherry-pick of #22616
First-time contributors' checklist
What is changed, added or deleted? (Required)
v8.5.5-12-gd6d53adbe) with 13 test scenarios, all passingdm/dm-safe-mode.mddm/dm-compatibility-catalog.mddm/dm-precheck.mdforeign-key.mdWhich TiDB version(s) do your changes apply to? (Required)
Tips for choosing the affected version(s):
By default, CHOOSE MASTER ONLY so your changes will be applied to the next TiDB major or minor releases. If your PR involves a product feature behavior change or a compatibility change, CHOOSE THE AFFECTED RELEASE BRANCH(ES) AND MASTER.
For details, see tips for choosing the affected versions.
What is the related PR or file link(s)?
Do your changes match any of the following descriptions?