Skip to content

docs: clarify large MySQL migration examples (#22059) - #22060

Merged
ti-chi-bot[bot] merged 1 commit into
pingcap:release-8.5from
ti-chi-bot:cherry-pick-22059-to-release-8.5
Nov 20, 2026
Merged

ti-chi-bot[bot] merged 1 commit into
pingcap:release-8.5from
ti-chi-bot:cherry-pick-22059-to-release-8.5

Conversation

@ti-chi-bot

@ti-chi-bot ti-chi-bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

This is an automated cherry-pick of #22059

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

  • 文档
    • 补充 Lightning 检查点错误处理说明:启用相关选项后,失败的目标表会被删除,检查点会重置;重试前需重建手动调整过的表结构。
    • 更新临时磁盘空间要求,说明排序键值对所需空间应大于待导入数据量。
    • 调整 DM 配置示例,默认关闭 GTID,并说明启用条件及配置步骤。
    • 补充按表设置同步白名单的示例,并将默认同步起点改为 binlog 文件名和位置。

@ti-chi-bot ti-chi-bot added lgtm ONCALL Relates to documentation oncall. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. type/bugfix This PR fixes a bug. type/cherry-pick-for-release-8.5 This PR is cherry-picked to release-8.5 from a source PR. labels Nov 13, 2026
@coderabbitai

coderabbitai Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

Walkthrough

两份 MySQL 到 TiDB 迁移指南更新了 Lightning 导入空间与 checkpoint 错误处理说明,并调整 DM 的 GTID 默认设置、表过滤规则和同步起点示例。

Changes: MySQL 到 TiDB 迁移文档

Layer / File(s) Summary
Lightning 导入说明
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
将 enable-gtid 示例默认值改为 false,并说明启用 GTID 的条件。
DM 任务过滤与同步起点
migrate-large-mysql-to-tidb.md, migrate-large-mysql-shards-to-tidb.md
示例增加表级过滤规则,并使用 binlog 文件名和位置作为同步起点。补充启用 GTID 模式时的配置步骤。

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

Change: Other

Merge Risk: Low · up to 3e597

The default non-GTID walkthrough is consistent. Users who switch to GTID mode are not told how to update an already-registered data source or which GTID value to use. Fix these doc gaps before or shortly after merge.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed 标题“docs: clarify large MySQL migration examples (#22059)”准确描述了主要变更:两份大型 MySQL 迁移指南的示例得到澄清。标题未覆盖 checkpoint 错误处理和 GTID 说明等全部细节,但这属于可接受范围。标题简洁,与变更集相符。
Description check Passed 描述基本完整。已包含变更内容列表、适用版本选择(master 与 v8.5)、相关 PR 与参考链接,并标记了 AI 代理参与情况。变更内容与摘要和目标一致。不足之处:“What is changed”部分保留了模板注释占位符,文档中的 CLA 复选框未在模板中体现(模板包含该项但描述中已省略),且“Related code change PR links”字段为空。这些属于非关键项,不影响通过。
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.
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

@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: 4

Review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 9294558 and 3e59786.

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.

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 可能从错误的事务集合开始同步,导致重复或遗漏数据。请要求用户分别填写 ${data-path}/my_db1/metadata 和 ${data-path}/my_db2/metadata 中对应快照的 GTID 集合。(raw.githubusercontent.com)

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.

Major · Functional Correctness · Quick win

在注册数据源前启用 GTID

执行到此处时,前面的步骤已将数据源以 enable-gtid: false 注册到 DM。只修改本地配置文件不会更新已注册的数据源,GTID 任务可能无法按预期启动。请说明要在创建各数据源之前设置该值,或提供更新已注册数据源的步骤。(raw.githubusercontent.com)

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.

Minor · Data Integrity & Integration · Quick win

补充 GTID 集合的来源

切换到 GTID 模式时,需要把 binlog-gtid 改为第 1 步导出的 metadata 文件中记录的 GTID 集合。示例值仅用于说明格式。沿用示例值可能使增量同步从错误的事务集合开始,导致数据重复或遗漏。

若 metadata 中的 GTID 字段为空,则不要启用 GTID 模式,改用 binlog-name 和 binlog-pos。

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

Major · Functional Correctness · Quick win

在注册数据源前启用 GTID

此步骤之前已使用 operate-source create 注册了 enable-gtid: false 的数据源。此时只修改本地 source1.yaml 不会更新已注册的配置,GTID 任务可能无法按预期启动。请说明要在创建数据源之前设置该值,或提供更新已注册数据源的步骤。(raw.githubusercontent.com)

Tools

LanguageTool

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

(BU)

@lilin90 lilin90 left a comment

Copy link
Copy Markdown
Member

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 20, 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 20, 2026
@ti-chi-bot
ti-chi-bot Bot merged commit 105d739 into pingcap:release-8.5 Nov 20, 2026
11 checks passed
@ti-chi-bot
ti-chi-bot Bot deleted the cherry-pick-22059-to-release-8.5 branch November 20, 2026 02:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

approved lgtm ONCALL Relates to documentation oncall. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. type/bugfix This PR fixes a bug. type/cherry-pick-for-release-8.5 This PR is cherry-picked to release-8.5 from a source PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants