v8.5.6: dm experimentally supports foreign key#22616
Merged
ti-chi-bot[bot] merged 6 commits intopingcap:masterfrom Apr 13, 2026
Merged
v8.5.6: dm experimentally supports foreign key#22616ti-chi-bot[bot] merged 6 commits intopingcap:masterfrom
ti-chi-bot[bot] merged 6 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.
| | 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
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)
| - 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)
|
|
||
| * `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)
| > | ||
| > 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)
|
|
||
| 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
| > | ||
| > `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.
| <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)
|
|
||
| > **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)
| > | ||
| > 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 |
|
@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
approved these changes
Apr 1, 2026
Oreoxmt
approved these changes
Apr 1, 2026
Oreoxmt
approved these changes
Apr 1, 2026
|
@Oreoxmt: Your lgtm message is repeated, so it is ignored. 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: Your lgtm message is repeated, so it is ignored. 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
added
translation/done
14 tasks
Collaborator
|
/cc @qiancai |
qiancai
reviewed
Apr 10, 2026
qiancai
approved these changes
Apr 10, 2026
ti-chi-bot
bot
added
lgtm
and removed
needs-1-more-lgtm
Co-authored-by: Grace Cai <qqzczy@126.com>
Collaborator
|
/retest |
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 |
Collaborator
|
/unhold |
ti-chi-bot
bot
removed
the
do-not-merge/hold
ti-chi-bot
pushed a commit
to ti-chi-bot/docs
that referenced
this pull request
Apr 13, 2026
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.
14 tasks
Member
|
In response to a cherrypick label: new pull request created to branch |
14 tasks
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
5 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.
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?