v8.5.6: dm experimentally supports foreign key#22616
Open
alastori wants to merge 3 commits intopingcap:masterfrom
Open
v8.5.6: dm experimentally supports foreign key#22616alastori wants to merge 3 commits intopingcap:masterfrom
alastori wants to merge 3 commits intopingcap:masterfrom
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
ti-chi-bot
bot
added
missing-translation-status
Contributor
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request updates the documentation for DM (Data Migration) to introduce and explain the experimental support for foreign keys in version 8.5.6. The changes detail how DM now handles foreign key constraints, including optimizations for safe mode and multi-worker causality, along with important limitations and compatibility notes, providing users with comprehensive information on this new capability. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. Footnotes
|
![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 updates the documentation to include experimental support for foreign keys in DM v8.5.6. The changes are well-structured across four documents, covering compatibility, pre-checks, safe mode behavior, and general foreign key information. My review focuses on improving clarity and adhering to the documentation style guide, particularly by using active voice and addressing the user in the second person. I have provided several suggestions to make the text more direct and easier for users to understand.
dm/dm-compatibility-catalog.md
Outdated
| | MariaDB > 10.5.10 | Not tested | Expected to work in most cases after bypassing the [precheck](/dm/dm-precheck.md). See [MariaDB notes](#mariadb-notes). | | ||
|
|
||
| ### Incompatibility with foreign key CASCADE operations | ||
| ### Foreign key CASCADE operations |
Contributor
dm/dm-compatibility-catalog.md
Outdated
Comment on lines
+43
to
+45
| > - Table routing combined with `worker-count > 1` is not supported. Set `worker-count=1` when using routing with foreign key tables. | ||
| > - The block-allow-list must include all ancestor tables in the foreign key chain. Filtered ancestor tables cause the task to pause with an error during incremental sync. | ||
| > - Source and downstream foreign key metadata must match. If a mismatch is detected, use `binlog-schema update --from-target` to resync. |
Contributor
There was a problem hiding this comment.
To improve clarity and adhere to the style guide (#22), I suggest rephrasing these instructions to address the user directly.
Suggested change
| > - Table routing combined with `worker-count > 1` is not supported. Set `worker-count=1` when using routing with foreign key tables. | |
| > - The block-allow-list must include all ancestor tables in the foreign key chain. Filtered ancestor tables cause the task to pause with an error during incremental sync. | |
| > - Source and downstream foreign key metadata must match. If a mismatch is detected, use `binlog-schema update --from-target` to resync. | |
| - Table routing combined with `worker-count > 1` is not supported. When using table routing with foreign key tables, you must set `worker-count` to `1`. | |
| - Your block-allow-list must include all ancestor tables in the foreign key chain. If you filter out ancestor tables, the task pauses with an error during incremental sync. | |
| - Your source and downstream foreign key metadata must match. If you detect a mismatch, use `binlog-schema update --from-target` to resync. |
References
- Documentation should address users in the second person ('you'). (link)
dm/dm-precheck.md
Outdated
| - Compatibility of the upstream MySQL table schema | ||
|
|
||
| - Check whether the upstream tables have foreign keys, which are not supported by TiDB. A warning is returned if a foreign key is found in the precheck. | ||
| - Check whether the upstream tables have foreign keys. TiDB supports foreign keys (GA since v8.5.0), and DM has experimental support for replicating tables with foreign key constraints starting from v8.5.6. A warning is returned if a foreign key is found in the precheck. For details on supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
Contributor
There was a problem hiding this comment.
For consistency with other items in this list, this should start with "Checks". Also, using active voice makes the sentence clearer.
Suggested change
| - Check whether the upstream tables have foreign keys. TiDB supports foreign keys (GA since v8.5.0), and DM has experimental support for replicating tables with foreign key constraints starting from v8.5.6. A warning is returned if a foreign key is found in the precheck. For details on supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). | |
| - Checks whether the upstream tables have foreign keys. TiDB supports foreign keys (GA since v8.5.0), and DM has experimental support for replicating tables with foreign key constraints starting from v8.5.6. DM returns a warning if it finds a foreign key in the precheck. For details on supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
References
- Prefer active voice for clarity. (link)
dm/dm-safe-mode.md
Outdated
|
|
||
| * `INSERT` statements are rewritten to `REPLACE` statements. | ||
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. | ||
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. Starting from v8.5.6, when the task session sets `foreign_key_checks=1`, DM skips the `DELETE` step for `UPDATE` statements that do not change any primary key or unique key value. See [Foreign key handling](#foreign-key-handling-experimental) for details. |
Contributor
There was a problem hiding this comment.
The style guide (#22) recommends addressing the user in the second person ("you"). This change makes the sentence more direct.
Suggested change
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. Starting from v8.5.6, when the task session sets `foreign_key_checks=1`, DM skips the `DELETE` step for `UPDATE` statements that do not change any primary key or unique key value. See [Foreign key handling](#foreign-key-handling-experimental) for details. | |
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. Starting from v8.5.6, when you set `foreign_key_checks=1` in the task session, DM skips the `DELETE` step for `UPDATE` statements that do not change any primary key or unique key value. See [Foreign key handling](#foreign-key-handling-experimental) for details. |
References
- Documentation should address users in the second person ('you'). (link)
dm/dm-safe-mode.md
Outdated
| > | ||
| > This feature is available starting from v8.5.6 and is experimental. | ||
|
|
||
| When safe mode is enabled and the downstream task session sets `foreign_key_checks=1`, the standard `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` side effects on child rows. Starting from v8.5.6, DM includes two improvements to address this: |
Contributor
There was a problem hiding this comment.
The style guide (#22) recommends addressing the user in the second person ("you"). This change makes the sentence more direct and active.
Suggested change
| When safe mode is enabled and the downstream task session sets `foreign_key_checks=1`, the standard `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` side effects on child rows. Starting from v8.5.6, DM includes two improvements to address this: | |
| When you enable safe mode and set `foreign_key_checks=1` in the downstream task session, the standard `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` side effects on child rows. Starting from v8.5.6, DM includes two improvements to address this: |
References
- Documentation should address users in the second person ('you'). (link)
dm/dm-safe-mode.md
Outdated
|
|
||
| When safe mode is enabled and the downstream task session sets `foreign_key_checks=1`, the standard `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` side effects on child rows. Starting from v8.5.6, DM includes two improvements to address this: | ||
|
|
||
| ### Non-key UPDATE optimization |
Contributor
dm/dm-safe-mode.md
Outdated
| > | ||
| > `UPDATE` statements that change primary key or unique key values are rejected by a guardrail when `foreign_key_checks=1`. The task pauses with the error: `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate PK/UK-changing UPDATEs on tables with foreign keys, use `safe-mode: false`. | ||
|
|
||
| ### Session-level foreign_key_checks |
Contributor
There was a problem hiding this comment.
foreign-key.md
Outdated
| <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 has experimental support for replicating tables with foreign key constraints. In safe mode, DM sets `foreign_key_checks=0` per batch and skips the redundant `DELETE` for non-key `UPDATE` rewrites, preventing unintended `ON DELETE CASCADE` side effects on child rows. When using `worker-count > 1`, DM discovers foreign key relations at task start and injects causality keys so that parent row operations complete before dependent child row operations. For limitations and configuration details, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental) and [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
Contributor
There was a problem hiding this comment.
The style guide (#22) recommends addressing the user in the second person ("you").
Suggested change
| - [DM](/dm/dm-overview.md): Starting from v8.5.6, DM has experimental support for replicating tables with foreign key constraints. In safe mode, DM sets `foreign_key_checks=0` per batch and skips the redundant `DELETE` for non-key `UPDATE` rewrites, preventing unintended `ON DELETE CASCADE` side effects on child rows. When using `worker-count > 1`, DM discovers foreign key relations at task start and injects causality keys so that parent row operations complete before dependent child row operations. For limitations and configuration details, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental) and [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). | |
| - [DM](/dm/dm-overview.md): Starting from v8.5.6, DM has experimental support for replicating tables with foreign key constraints. In safe mode, DM sets `foreign_key_checks=0` per batch and skips the redundant `DELETE` for non-key `UPDATE` rewrites, preventing unintended `ON DELETE CASCADE` side effects on child rows. When you use `worker-count > 1`, DM discovers foreign key relations at task start and injects causality keys so that parent row operations complete before dependent child row operations. For limitations and configuration details, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental) and [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
References
- Documentation should address users in the second person ('you'). (link)
foreign-key.md
Outdated
|
|
||
| > **Warning:** | ||
| > | ||
| > This feature is experimental. `UPDATE` statements that change primary key or unique key values in safe mode are rejected when `foreign_key_checks=1` (the task pauses). DDL operations that create, alter, or drop foreign key constraints during replication are also rejected. For the full list of constraints, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
Contributor
There was a problem hiding this comment.
Using active voice ("DM rejects...") is clearer and more direct than passive voice.
Suggested change
| > This feature is experimental. `UPDATE` statements that change primary key or unique key values in safe mode are rejected when `foreign_key_checks=1` (the task pauses). DDL operations that create, alter, or drop foreign key constraints during replication are also rejected. For the full list of constraints, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). | |
| > This feature is experimental. DM rejects `UPDATE` statements that change primary key or unique key values in safe mode when `foreign_key_checks=1` (the task pauses). DDL operations that create, alter, or drop foreign key constraints during replication are also rejected. For the full list of constraints, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
References
- Prefer active voice for clarity. (link)
foreign-key.md
Outdated
| > | ||
| > This feature is experimental. `UPDATE` statements that change primary key or unique key values in safe mode are rejected when `foreign_key_checks=1` (the task pauses). DDL operations that create, alter, or drop foreign key constraints during replication are also rejected. For the full list of constraints, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). | ||
|
|
||
| In versions earlier than v8.5.6, DM does not support foreign keys and disables [`foreign_key_checks`](/system-variables.md#foreign_key_checks) when replicating data to TiDB. Cascading operations are not replicated from upstream to downstream, which might cause data inconsistency. |
Contributor
There was a problem hiding this comment.
This rephrasing adds a bit more context and improves the flow from the previous sentence.
Suggested change
| In versions earlier than v8.5.6, DM does not support foreign keys and disables [`foreign_key_checks`](/system-variables.md#foreign_key_checks) when replicating data to TiDB. Cascading operations are not replicated from upstream to downstream, which might cause data inconsistency. | |
| In versions earlier than v8.5.6, DM does not support foreign keys and disables [`foreign_key_checks`](/system-variables.md#foreign_key_checks) when replicating data to TiDB. This means that cascading operations from the upstream are not replicated to the downstream, which might cause data inconsistency. |
References
- Improve clarity and readability. (link)
Oreoxmt
added
translation/doing
ti-chi-bot
bot
removed
the
missing-translation-status
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
Collaborator
Author
|
/retest-required |
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
@OliverS929: adding LGTM is restricted to approvers and reviewers in OWNERS files. DetailsIn response to this:
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. |
Oreoxmt
changed the title
Oreoxmt
reviewed
Mar 30, 2026
| - Compatibility of the upstream MySQL table schema | ||
|
|
||
| - Check whether the upstream tables have foreign keys, which are not supported by TiDB. A warning is returned if a foreign key is found in the precheck. | ||
| - Checks whether the upstream tables have foreign keys. TiDB supports foreign keys (GA since v8.5.0), and DM has experimental support for replicating tables with foreign key constraints starting from v8.5.6. DM returns a warning if it finds a foreign key in the precheck. For details on supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
Collaborator
There was a problem hiding this comment.
Suggested change
| - Checks whether the upstream tables have foreign keys. TiDB supports foreign keys (GA since v8.5.0), and DM has experimental support for replicating tables with foreign key constraints starting from v8.5.6. DM returns a warning if it finds a foreign key in the precheck. For details on supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). | |
| - Check whether the upstream tables have foreign keys. TiDB supports foreign keys (GA since v8.5.0), and DM provides experimental support for replicating tables with foreign key constraints starting from v8.5.6. During the precheck, DM returns a warning if foreign keys are detected. For supported scenarios and limitations, see [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). |
Oreoxmt
reviewed
Mar 30, 2026
| <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 has experimental support for replicating tables with foreign key constraints. In safe mode, DM sets `foreign_key_checks=0` per batch and optimizes non-key `UPDATE` rewrites to prevent unintended `ON DELETE CASCADE` side effects. When you use `worker-count > 1`, DM injects causality keys so that parent row operations complete before child row operations. This feature is experimental; DM rejects PK/UK-changing UPDATEs and FK-related DDL in safe mode. For the full list of constraints, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental) and [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). In versions earlier than v8.5.6, DM disables [`foreign_key_checks`](/system-variables.md#foreign_key_checks) when replicating data to TiDB, so cascading operations are not replicated from upstream to downstream. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - [DM](/dm/dm-overview.md): Starting from v8.5.6, DM has experimental support for replicating tables with foreign key constraints. In safe mode, DM sets `foreign_key_checks=0` per batch and optimizes non-key `UPDATE` rewrites to prevent unintended `ON DELETE CASCADE` side effects. When you use `worker-count > 1`, DM injects causality keys so that parent row operations complete before child row operations. This feature is experimental; DM rejects PK/UK-changing UPDATEs and FK-related DDL in safe mode. For the full list of constraints, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental) and [DM Compatibility Catalog](/dm/dm-compatibility-catalog.md#foreign-key-cascade-operations). In versions earlier than v8.5.6, DM disables [`foreign_key_checks`](/system-variables.md#foreign_key_checks) when replicating data to TiDB, so cascading operations are not replicated from upstream to downstream. | |
| - [DM](/dm/dm-overview.md): starting from v8.5.6, DM provides experimental support for replicating tables that use foreign key constraints. 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. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| * `INSERT` statements are rewritten to `REPLACE` statements. | ||
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. | ||
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. Starting from v8.5.6, when you set `foreign_key_checks=1` in the task session, DM skips the `DELETE` step for `UPDATE` statements that do not change any primary key or unique key value. See [Foreign key handling](#foreign-key-handling-experimental) for details. |
Collaborator
There was a problem hiding this comment.
Suggested change
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. Starting from v8.5.6, when you set `foreign_key_checks=1` in the task session, DM skips the `DELETE` step for `UPDATE` statements that do not change any primary key or unique key value. See [Foreign key handling](#foreign-key-handling-experimental) for details. | |
| * `UPDATE` statements are analyzed to obtain the value of the primary key or the unique index of the row updated. `UPDATE` statements are then rewritten to `DELETE` + `REPLACE` statements in the following two steps: DM deletes the old record using the primary key or unique index, and inserts the new record using the `REPLACE` statement. | |
| Starting from v8.5.6, when you set `foreign_key_checks=1` in the task session, DM skips the `DELETE` step for `UPDATE` statements that do not modify primary key or unique index values. For more information, see [Foreign key handling](#foreign-key-handling). |
Oreoxmt
reviewed
Mar 30, 2026
| syncer-config-name: "global" # Name of the syncers configuration. | ||
| ``` | ||
|
|
||
| ## Foreign key handling (experimental) |
Collaborator
There was a problem hiding this comment.
Suggested change
| ## Foreign key handling (experimental) | |
| ## Foreign key handling <span class="version-mark">New in v8.5.6</span> |
Oreoxmt
reviewed
Mar 30, 2026
Comment on lines
+96
to
+98
| > **Note:** | ||
| > | ||
| > This feature is available starting from v8.5.6 and is experimental. |
Collaborator
There was a problem hiding this comment.
Suggested change
| > **Note:** | |
| > | |
| > This feature is available starting from v8.5.6 and is experimental. | |
| > **Warning:** | |
| > | |
| > This feature is introduced in v8.5.6 and is experimental. |
Oreoxmt
reviewed
Mar 30, 2026
| > | ||
| > This feature is available starting from v8.5.6 and is experimental. | ||
|
|
||
| When you enable safe mode and set `foreign_key_checks=1` in the downstream task session, the standard `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` side effects on child rows. Starting from v8.5.6, DM includes two improvements to address this: |
Collaborator
There was a problem hiding this comment.
Suggested change
| When you enable safe mode and set `foreign_key_checks=1` in the downstream task session, the standard `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` side effects on child rows. Starting from v8.5.6, DM includes two improvements to address this: | |
| When you enable safe mode and set `foreign_key_checks=1` in the downstream task session, the default `DELETE` + `REPLACE` rewrite for `UPDATE` statements can trigger unintended `ON DELETE CASCADE` effects on child rows. Starting from v8.5.6, DM introduces the following improvements to address this issue. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| ### Non-key `UPDATE` optimization | ||
|
|
||
| For `UPDATE` statements that do not change any primary key or unique key value, DM skips the `DELETE` step and emits only `REPLACE INTO`. Because the primary key is unchanged, `REPLACE INTO` overwrites the existing row without triggering a cascade delete. This optimization applies automatically in safe mode. |
Collaborator
There was a problem hiding this comment.
Suggested change
| For `UPDATE` statements that do not change any primary key or unique key value, DM skips the `DELETE` step and emits only `REPLACE INTO`. Because the primary key is unchanged, `REPLACE INTO` overwrites the existing row without triggering a cascade delete. This optimization applies 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 cascade deletes. This optimization is applied automatically in safe mode. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| For `UPDATE` statements that do not change any primary key or unique key value, DM skips the `DELETE` step and emits only `REPLACE INTO`. Because the primary key is unchanged, `REPLACE INTO` overwrites the existing row without triggering a cascade delete. This optimization applies automatically in safe mode. | ||
|
|
||
| For example, given the following upstream statement where `id` is the primary key: |
Collaborator
There was a problem hiding this comment.
Suggested change
| For example, given the following upstream statement where `id` is the primary key: | |
| For example, consider the following upstream statement, where `id` is the primary key: |
Oreoxmt
reviewed
Mar 30, 2026
| UPDATE dummydb.dummytbl SET int_value = 888999 WHERE id = 123; | ||
| ``` | ||
|
|
||
| In previous versions, safe mode rewrites this as: |
Collaborator
There was a problem hiding this comment.
Suggested change
| In previous versions, safe mode rewrites this as: | |
| In versions earlier than v8.5.6, safe mode rewrites this statement as follows: |
Oreoxmt
reviewed
Mar 30, 2026
| In previous versions, safe mode rewrites this as: | ||
|
|
||
| ```sql | ||
| DELETE FROM dummydb.dummytbl WHERE id = 123; -- triggers ON DELETE CASCADE |
Collaborator
There was a problem hiding this comment.
Suggested change
| DELETE FROM dummydb.dummytbl WHERE id = 123; -- triggers ON DELETE CASCADE | |
| DELETE FROM dummydb.dummytbl WHERE id = 123; -- Triggers ON DELETE CASCADE |
Oreoxmt
reviewed
Mar 30, 2026
| REPLACE INTO dummydb.dummytbl (id, int_value, ...) VALUES (123, 888999, ...); | ||
| ``` | ||
|
|
||
| Starting from v8.5.6, safe mode rewrites this as: |
Collaborator
There was a problem hiding this comment.
Suggested change
| Starting from v8.5.6, safe mode rewrites this as: | |
| Starting from v8.5.6, safe mode rewrites the statement as follows: |
Oreoxmt
reviewed
Mar 30, 2026
| Starting from v8.5.6, safe mode rewrites this as: | ||
|
|
||
| ```sql | ||
| REPLACE INTO dummydb.dummytbl (id, int_value, ...) VALUES (123, 888999, ...); -- no cascade |
Collaborator
There was a problem hiding this comment.
Suggested change
| REPLACE INTO dummydb.dummytbl (id, int_value, ...) VALUES (123, 888999, ...); -- no cascade | |
| REPLACE INTO dummydb.dummytbl (id, int_value, ...) VALUES (123, 888999, ...); -- No cascade |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| > **Warning:** | ||
| > | ||
| > `UPDATE` statements that change primary key or unique key values are rejected by a guardrail when `foreign_key_checks=1`. The task pauses with the error: `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate PK/UK-changing UPDATEs on tables with foreign keys, use `safe-mode: false`. |
Collaborator
There was a problem hiding this comment.
Suggested change
| > `UPDATE` statements that change primary key or unique key values are rejected by a guardrail when `foreign_key_checks=1`. The task pauses with the error: `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate PK/UK-changing UPDATEs on tables with foreign keys, use `safe-mode: false`. | |
| > When `foreign_key_checks=1`, DM does not support `UPDATE` statements that modify primary key or unique key values. In this case, 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 `UPDATE` statements on tables with foreign keys, set `safe-mode: false`. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| ### Session-level `foreign_key_checks` | ||
|
|
||
| During safe mode batch execution, DM sets `SET SESSION foreign_key_checks=0` before executing `INSERT` and `UPDATE` batches, and restores the original value afterward. This prevents `REPLACE INTO` (internally `DELETE` + `INSERT`) from triggering cascade operations in the downstream. |
Collaborator
There was a problem hiding this comment.
Suggested change
| During safe mode batch execution, DM sets `SET SESSION foreign_key_checks=0` before executing `INSERT` and `UPDATE` batches, and restores the original value afterward. This prevents `REPLACE INTO` (internally `DELETE` + `INSERT`) from triggering cascade operations in the downstream. | |
| During batch execution in safe mode, DM executes `SET SESSION foreign_key_checks=0` before executing `INSERT` and `UPDATE` batches, and restores the original value afterward. This prevents `REPLACE INTO` (which internally performs `DELETE` + `INSERT`) from triggering cascade operations in the downstream. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| During safe mode batch execution, DM sets `SET SESSION foreign_key_checks=0` before executing `INSERT` and `UPDATE` batches, and restores the original value afterward. This prevents `REPLACE INTO` (internally `DELETE` + `INSERT`) from triggering cascade operations in the downstream. | ||
|
|
||
| The session variable toggle adds a small overhead per batch flush (two `SET SESSION` round-trips). This overhead is negligible for most workloads. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The session variable toggle adds a small overhead per batch flush (two `SET SESSION` round-trips). This overhead is negligible for most workloads. | |
| This session-level setting introduces a small overhead per batch (two `SET SESSION` round trips). In most workloads, this overhead is negligible. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| ### Multi-worker foreign key causality | ||
|
|
||
| When using `worker-count > 1` with foreign key tables, DM discovers foreign key relations from the downstream `CREATE TABLE` schema at task start. For each DML operation, DM injects causality keys derived from the foreign key relationships, ensuring that parent row operations and dependent child row operations are assigned to the same DML worker queue. This preserves binlog order across workers and prevents foreign key constraint violations. |
Collaborator
There was a problem hiding this comment.
Suggested change
| When using `worker-count > 1` with foreign key tables, DM discovers foreign key relations from the downstream `CREATE TABLE` schema at task start. For each DML operation, DM injects causality keys derived from the foreign key relationships, ensuring that parent row operations and dependent child row operations are assigned to the same DML worker queue. This preserves binlog order across workers and prevents foreign key constraint violations. | |
| When you set `worker-count` to a value greater than 1 and the 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. |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| ### Incompatibility with foreign key CASCADE operations | ||
| ### Foreign key `CASCADE` operations | ||
|
|
Collaborator
There was a problem hiding this comment.
Suggested change
| > **Warning:** | |
| > | |
| > This feature is experimental. | |
Oreoxmt
reviewed
Mar 30, 2026
|
|
||
| - DM creates foreign key **constraints** on the target, but they are not enforced while applying transactions because DM sets the session variable [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks). | ||
| - DM does **not** support `ON DELETE CASCADE` or `ON UPDATE CASCADE` behavior by default, and enabling `foreign_key_checks` via a DM task session variable is not recommended. If your workload relies on cascades, **do not assume** that cascade effects will be replicated. | ||
| Starting from v8.5.6, DM has **experimental** support for replicating tables with foreign key constraints. This includes two improvements: |
Collaborator
There was a problem hiding this comment.
Suggested change
| Starting from v8.5.6, DM has **experimental** support for replicating tables with foreign key constraints. This includes two improvements: | |
| Starting from v8.5.6, DM provides **experimental** support for replicating tables that use foreign key constraints. This support includes the following improvements: |
Oreoxmt
reviewed
Mar 30, 2026
Comment on lines
+34
to
+35
| - **Safe mode**: DM sets `foreign_key_checks=0` per batch during safe mode execution and skips the redundant `DELETE` for `UPDATE` statements that do not change primary key or unique key values. This prevents `REPLACE INTO` (internally `DELETE` + `INSERT`) from triggering unintended `ON DELETE CASCADE` side effects on child rows. For details, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental). | ||
| - **Multi-worker causality**: When `worker-count > 1`, DM discovers foreign key relations from the downstream schema at task start and injects causality keys so that parent row DML operations complete before dependent child row operations, preserving binlog order across workers. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **Safe mode**: DM sets `foreign_key_checks=0` per batch during safe mode execution and skips the redundant `DELETE` for `UPDATE` statements that do not change primary key or unique key values. This prevents `REPLACE INTO` (internally `DELETE` + `INSERT`) from triggering unintended `ON DELETE CASCADE` side effects on child rows. For details, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling-experimental). | |
| - **Multi-worker causality**: When `worker-count > 1`, DM discovers foreign key relations from the downstream schema at task start and injects causality keys so that parent row DML operations complete before dependent child row operations, preserving binlog order across workers. | |
| - **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 details, see [DM Safe Mode](/dm/dm-safe-mode.md#foreign-key-handling). | |
| - **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. |
Oreoxmt
reviewed
Mar 30, 2026
| > - Your source and downstream foreign key metadata must match. If you detect a mismatch, use `binlog-schema update --from-target` to resync. | ||
| > - `ON UPDATE CASCADE` is not replicated correctly in safe mode when the `UPDATE` changes a primary key or unique key value. DM rewrites such UPDATEs as `DELETE` + `REPLACE`, which would trigger `ON DELETE` actions instead of `ON UPDATE` actions. The guardrail rejects the PK/UK change and pauses the task. Non-key `UPDATE` statements on tables with `ON UPDATE CASCADE` replicate without issues. | ||
|
|
||
| In versions earlier than v8.5.6, DM creates foreign key constraints on the target but does not enforce them because it sets the session variable [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks). Cascading operations are not replicated, so do not assume that cascade effects will be applied in the downstream. |
Collaborator
There was a problem hiding this comment.
Suggested change
| In versions earlier than v8.5.6, DM creates foreign key constraints on the target but does not enforce them because it sets the session variable [`foreign_key_checks=OFF`](/system-variables.md#foreign_key_checks). Cascading operations are not replicated, so do not assume that cascade effects will be applied in 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, cascading operations are not replicated to the downstream. |
Oreoxmt
reviewed
Mar 30, 2026
Comment on lines
+37
to
+46
| > **Warning:** | ||
| > | ||
| > This feature is experimental. The following constraints apply: | ||
| > | ||
| > - `UPDATE` statements that change primary key or unique key values in safe mode are rejected. The task pauses with the error: `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate these UPDATEs, use `safe-mode: false`. | ||
| > - DDL operations that create, alter, or drop foreign key constraints during replication are rejected when `foreign_key_checks=1`. | ||
| > - Table routing combined with `worker-count > 1` is not supported. When using table routing with foreign key tables, you must set `worker-count` to `1`. | ||
| > - Your block-allow-list must include all ancestor tables in the foreign key chain. If you filter out ancestor tables, the task pauses with an error during incremental sync. | ||
| > - Your source and downstream foreign key metadata must match. If you detect a mismatch, use `binlog-schema update --from-target` to resync. | ||
| > - `ON UPDATE CASCADE` is not replicated correctly in safe mode when the `UPDATE` changes a primary key or unique key value. DM rewrites such UPDATEs as `DELETE` + `REPLACE`, which would trigger `ON DELETE` actions instead of `ON UPDATE` actions. The guardrail rejects the PK/UK change and pauses the task. Non-key `UPDATE` statements on tables with `ON UPDATE CASCADE` replicate without issues. |
Collaborator
There was a problem hiding this comment.
Suggested change
| > **Warning:** | |
| > | |
| > This feature is experimental. The following constraints apply: | |
| > | |
| > - `UPDATE` statements that change primary key or unique key values in safe mode are rejected. The task pauses with the error: `safe-mode update with foreign_key_checks=1 and PK/UK changes is not supported`. To replicate these UPDATEs, use `safe-mode: false`. | |
| > - DDL operations that create, alter, or drop foreign key constraints during replication are rejected when `foreign_key_checks=1`. | |
| > - Table routing combined with `worker-count > 1` is not supported. When using table routing with foreign key tables, you must set `worker-count` to `1`. | |
| > - Your block-allow-list must include all ancestor tables in the foreign key chain. If you filter out ancestor tables, the task pauses with an error during incremental sync. | |
| > - Your source and downstream foreign key metadata must match. If you detect a mismatch, use `binlog-schema update --from-target` to resync. | |
| > - `ON UPDATE CASCADE` is not replicated correctly in safe mode when the `UPDATE` changes a primary key or unique key value. DM rewrites such UPDATEs as `DELETE` + `REPLACE`, which would trigger `ON DELETE` actions instead of `ON UPDATE` actions. The guardrail rejects the PK/UK change and pauses the task. Non-key `UPDATE` statements on tables with `ON UPDATE CASCADE` replicate without issues. | |
| 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. |
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.
Summary
v8.5.5-12-gd6d53adbe) with 13 test scenarios, all passingChanges
dm/dm-safe-mode.mddm/dm-compatibility-catalog.mddm/dm-precheck.mdforeign-key.mdRelated
Test plan
release-8.5HEAD buildrelease-8.5branch after merge