Skip to content

docs: clarify large MySQL migration examples - #22059

Merged
ti-chi-bot[bot] merged 3 commits into
pingcap:masterfrom
lilin90:docs/fix-large-mysql-migration-guides-24673
Nov 13, 2026
Merged

ti-chi-bot[bot] merged 3 commits into
pingcap:masterfrom
lilin90:docs/fix-large-mysql-migration-guides-24673

Conversation

@lilin90

@lilin90 lilin90 commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

What is changed, added, or deleted? (Required)

This PR fixes several inconsistencies in the large MySQL migration walkthroughs:

  • align the TiDB Lightning temporary disk-space guidance in migrate-large-mysql-to-tidb.md with the physical import mode documentation
  • clarify the non-GTID example in migrate-large-mysql-to-tidb.md so it uses the recorded binlog file and position, and explain when to switch to GTID mode instead
  • limit the DM examples in both large-migration guides to the same tables that Dumpling exports
  • clarify in migrate-large-mysql-shards-to-tidb.md that --checkpoint-error-destroy drops the failed target table and resets its checkpoint
  • make the large-shards guide use a consistent non-GTID example and explain when to switch to GTID mode

Which 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.

  • master (the latest development version)
  • v9.0 (TiDB 9.0 versions)
  • v8.5 (TiDB 8.5 versions)
  • v8.1 (TiDB 8.1 versions)
  • v7.5 (TiDB 7.5 versions)
  • v7.1 (TiDB 7.1 versions)
  • v6.5 (TiDB 6.5 versions)

What is the related PR or file link(s)?

AI agent involvement

  • The changes in this PR were primarily made by an AI agent on behalf of the PR author.

Do your changes match any of the following descriptions?

  • Delete files
  • Change aliases
  • Need modification after applied to another branch
  • Might cause conflicts after applied to another branch

Summary by CodeRabbit

  • 文档
    • 更新 TiDB Lightning 导入期间的临时磁盘空间要求:可用空间需大于待导入数据总量。
    • 补充 checkpoint 错误处理警告,说明使用 --checkpoint-error-destroy 会删除失败的目标表并重置其 checkpoint。
    • 调整 DM 配置示例,默认关闭 GTID,说明启用条件及 GTID 模式下的配置方式;示例改用 binlog 文件和位置作为同步起点,并补充表名过滤规则。

@lilin90 lilin90 added needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. ONCALL Relates to documentation oncall. translation/from-docs This PR is translated from a PR in pingcap/docs. type/bugfix This PR fixes a bug. labels Nov 13, 2026
@ti-chi-bot ti-chi-bot Bot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Nov 13, 2026
@lilin90 lilin90 self-assigned this Nov 13, 2026
Synced from: pingcap/docs#24673
Target PR: pingcap#22059

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
@github-actions

Copy link
Copy Markdown

Auto-sync completed successfully

Source PR: pingcap/docs#24673
Target PR: #22059

Chinese documentation has been updated based on English documentation changes.

@ti-chi-bot ti-chi-bot Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. labels Nov 13, 2026
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • Resume reviews
  • Trigger review

No actionable comments were generated in the recent review.

Walkthrough

文档更新 TiDB Lightning 的临时排序空间和 checkpoint 错误处理说明,并调整 DM 数据源及任务配置示例中的 GTID、表过滤和增量同步起点设置。

Changes: MySQL 到 TiDB 迁移文档

Layer / File(s) Summary
Lightning 导入空间与 checkpoint 处理
migrate-large-mysql-to-tidb.md, migrate-large-mysql-shards-to-tidb.md
临时排序空间要求改为大于待导入数据总量。文档说明 checkpoint 错误处理会删除目标表并重置 checkpoint;若需保留手动调整的表结构,重试前需重新创建表。
DM 数据源 GTID 配置
migrate-large-mysql-to-tidb.md, migrate-large-mysql-shards-to-tidb.md
数据源示例默认关闭 GTID,并说明需要从指定 GTID 集合复制时如何启用;上游存在主库自动切换时,必须使用 GTID 模式。
DM 任务过滤与增量起点
migrate-large-mysql-to-tidb.md, migrate-large-mysql-shards-to-tidb.md
任务示例增加表级过滤,并使用 binlog 文件和位置作为增量起点。文档说明启用 GTID 模式时使用 binlog-gtid,并注释 binlog 文件和位置配置。

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Merge Risk: Low · up to 0dc7c

The documentation changes are mostly accurate and the default non-GTID path is sound. Users who switch to GTID mode could copy a placeholder GTID value, or not realize that an already-loaded source needs its enable-gtid setting updated. These documentation clarifications are worth making, but they should not block the merge.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed 标题“docs: clarify large MySQL migration examples”与变更集的主要内容一致。变更涉及两份大规模 MySQL 迁移文档,包括 GTID 与 binlog 位置示例、DM 表范围示例,以及 --checkpoint-error-destroy 的说明。标题概括了主要变更,未涵盖所有细节,这属于正常范围。
Description check Passed 描述基本完整。已填写“What is changed, added, or deleted?”一节,列出了五项具体修改。已勾选适用版本(master 与 v8.5),并给出相关 PR 和参考链接。已勾选 AI agent 参与选项。模板中的 First-time contributors' checklist 未勾选,但该项仅适用于首次贡献者,可以忽略。主要缺口是“What is changed”…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

描述基本完整。已填写“What is changed, added, or deleted?”一节,列出了五项具体修改。已勾选适用版本(master 与 v8.5),并给出相关 PR 和参考链接。已勾选 AI agent 参与选项。模板中的 First-time contributors' checklist 未勾选,但该项仅适用于首次贡献者,可以忽略。主要缺口是“What is changed”一节仅有 PR 内的简要说明,未解释每项修改的具体原因。

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between a2cbb26 and 0dc7c2b.

Files selected for processing: 1

  • migrate-large-mysql-shards-to-tidb.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 2 remain after this review.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 66c2817 and a2cbb26.

Files selected for processing: 2

  • migrate-large-mysql-shards-to-tidb.md
  • migrate-large-mysql-to-tidb.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Comment thread migrate-large-mysql-shards-to-tidb.md Resolved
binlog-name: "${binlog-name}" # 第 1 步中 `${data-path}/my_db1/metadata` 记录的日志位置;当该上游未启用 GTID 时,使用 `binlog-name` + `binlog-pos`。
binlog-pos: ${binlog-position}
# binlog-gtid: " 例如:09bec856-ba95-11ea-850a-58f2b4af5188:1-9"
# binlog-gtid: "09bec856-ba95-11ea-850a-58f2b4af5188:1-9" # 如果该上游使用 GTID 模式,则改用 `binlog-gtid`。

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Quick win

为每个数据源使用对应的导出 GTID

两个示例使用相同的固定 GTID。切换模式时,如果直接取消注释,DM 可能从错误位置同步,导致增量数据遗漏或重复。请要求分别使用 my_db1/metadata 和 my_db2/metadata 中记录的 GTID 集合,并将示例值改为占位符。

Also applies to: 319-319


```

如果某个上游 MySQL 实例已启用 GTID,并且该数据源需要使用 GTID 模式(例如需要进行主从切换),请将该数据源的 `enable-gtid` 设置为 `true`,注释掉 `binlog-name` 和 `binlog-pos`,并改为配置 `binlog-gtid`。

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Data Integrity & Integration · Quick win

在加载数据源前说明 GTID 设置

用户按顺序操作时,会先通过 operate-source create 以 enable-gtid: false 加载数据源。本页随后要求将 enable-gtid 设置为 true,但未说明如何更新已加载的数据源。仅修改本地 source1.yaml 不会更新集群中的数据源配置。

影响范围为需要 GTID 模式(例如主从切换)的用户。默认的非 GTID 路径不受影响。

建议在“添加数据源”小节的 operate-source create 命令前说明 GTID 要求,并在该处补充需要 GTID 时应如何设置 enable-gtid 的说明。

binlog-gtid: "09bec856-ba95-11ea-850a-58f2b4af5188:1-9"
binlog-name: "mysql-bin.000004" # 第 1 步“从 MySQL 导出所有数据”中记录的 binlog 文件。上游未启用 GTID 时,使用 `binlog-name` + `binlog-pos`。
binlog-pos: 109227
# binlog-gtid: "09bec856-ba95-11ea-850a-58f2b4af5188:1-9" # 如果上游使用 GTID 模式,则改用 `binlog-gtid`。

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Major · Data Integrity & Integration · Quick win

要求使用全量导出的 GTID 集合

切换到 GTID 模式时,示例值不是本次导出快照的 GTID 集合。直接取消注释可能从错误位置同步,导致增量数据遗漏或重复。请明确要求使用第 1 步生成的 metadata 中的 GTID 集合,并将固定值改为占位符。

# safe-mode: true # 设置为 true,会将来自数据源的 INSERT 改写为 REPLACE,将 UPDATE 改写为 DELETE 与 REPLACE,从而保证在表结构中存在主键或唯一索引的条件下迁移数据时可以重复导入 DML。在启动或恢复增量复制任务的前 1 分钟内 TiDB DM 会自动启动 safe mode。
```

上述示例使用了第 1 步中记录的 binlog 文件和位置,因为 `metadata` 文件中的 `GTID` 字段为空。如果上游 MySQL 已启用 GTID 且你需要使用 GTID 模式(例如需要进行主从切换),请将 `enable-gtid` 设置为 `true`,注释掉 `binlog-name` 和 `binlog-pos`,并改为配置 `binlog-gtid`。

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor · Functional Correctness · Quick win

在创建数据源前设置 GTID 模式

如果用户按示例加载了 enable-gtid: false,此时修改 source1.yaml 不会更新已加载的数据源。请在创建数据源前明确设置时机,或说明如何将更改应用到已创建的数据源。

Tools

LanguageTool

[uncategorized] ~244-~244: 您的意思是“"不"中”?
Context: ...自动启动 safe mode。 ``` 上述示例使用了第 1 步中记录的 binlog 文件和位置,因为 metadata 文件中的 `GT...

(BU)

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
@lilin90 lilin90 added the lgtm label Nov 13, 2026

@lilin90 lilin90 left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

/approve

@ti-chi-bot

ti-chi-bot Bot commented Nov 13, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: lilin90

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@ti-chi-bot ti-chi-bot Bot added the approved label Nov 13, 2026
@ti-chi-bot
ti-chi-bot Bot merged commit 694518f into pingcap:master Nov 13, 2026
12 checks passed
@ti-chi-bot

Copy link
Copy Markdown
Member

In response to a cherrypick label: new pull request created to branch release-8.5: #22060.

@lilin90
lilin90 deleted the docs/fix-large-mysql-migration-guides-24673 branch November 20, 2026 02:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved lgtm needs-cherry-pick-release-8.5 Should cherry pick this PR to release-8.5 branch. ONCALL Relates to documentation oncall. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. translation/from-docs This PR is translated from a PR in pingcap/docs. type/bugfix This PR fixes a bug.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants