Skip to content

docs: clarify the snapshot time for sync-diff-inspector - #21996

Open
dzhmj0204-creator wants to merge 3 commits into
pingcap:masterfrom
dzhmj0204-creator:fix/snapshot-time-in-replication-doc
Open

dzhmj0204-creator wants to merge 3 commits into
pingcap:masterfrom
dzhmj0204-creator:fix/snapshot-time-in-replication-doc

Conversation

@dzhmj0204-creator

@dzhmj0204-creator dzhmj0204-creator commented Oct 22, 2026 •

Copy link
Copy Markdown

First-time contributors' checklist

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

In replicate-between-primary-and-secondary-clusters.md, the doc states that the BackupTS returned by RESTORE is "the time when the downstream cluster finishes restoring data". This is inaccurate: that value is the backup snapshot time on which the restore is based.

Using it as the snapshot of the downstream data source can make sync-diff-inspector report that the table does not exist. This PR clarifies the paragraph and the comment of the downstream snapshot config, and points out that the downstream snapshot should be a time point after the restore completes.

Close #21575

Which TiDB version(s) do your changes apply to? (Required)

  • master (the latest development version)

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.

Summary by CodeRabbit

  • 文档
    • 明确说明 RESTORE 返回的 BackupTS 表示恢复所依据的备份快照时间点,不代表恢复完成时间。
    • 说明下游 snapshot 应设置为恢复完成后的时间点;配置示例改为空值,并补充在 RESTORE 完成后通过 SELECT TIDB_CURRENT_TSO(); 获取当前 TSO 的方法。

The BackupTS returned by RESTORE is the backup snapshot time that the
restore is based on, not the time when the restore completes. Using it as
the downstream snapshot can make sync-diff-inspector report that the table
does not exist. Clarify what the downstream snapshot should be.

Ref pingcap#21575

Signed-off-by: dzhmj0204-creator <306411393+dzhmj0204-creator@users.noreply.github.com>
@ti-chi-bot ti-chi-bot Bot added contribution This PR is from a community contributor. first-time-contributor Indicates that the PR was contributed by an external member and is a first-time contributor. labels Oct 22, 2026
@ti-chi-bot

ti-chi-bot Bot commented Oct 22, 2026

Copy link
Copy Markdown

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign tangenta for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found 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 needs-ok-to-test Indicates a PR created by contributors and need ORG member send '/ok-to-test' to start testing. label Oct 22, 2026
@ti-chi-bot

ti-chi-bot Bot commented Oct 22, 2026

Copy link
Copy Markdown

Hi @dzhmj0204-creator. Thanks for your PR.

I'm waiting for a pingcap member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

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.

@ti-chi-bot

ti-chi-bot Bot commented Oct 22, 2026

Copy link
Copy Markdown

Welcome @dzhmj0204-creator!

It looks like this is your first PR to pingcap/docs-cn 🎉.

I'm the bot to help you request reviewers, add labels and more, See available commands.

We want to make sure your contribution gets all the attention it needs!



Thank you, and welcome to pingcap/docs-cn. 😃

@ti-chi-bot ti-chi-bot Bot added the missing-translation-status This PR does not have translation status info. label Oct 22, 2026
@pingcap-cla-assistant

pingcap-cla-assistant Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@ti-chi-bot ti-chi-bot Bot added the size/XS Denotes a PR that changes 0-9 lines, ignoring generated files. label Oct 22, 2026
@coderabbitai

coderabbitai Bot commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

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

ℹ️ Recent review info
⚙️ Run configuration
📥 Commits

Reviewing files that changed from the base of the PR and between d32752f and a9fd92d.

📒 Files selected for processing: 1
  • replicate-between-primary-and-secondary-clusters.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.

📝 Walkthrough

文档更新了数据校验时间说明:RESTORE 返回的 BackupTS 表示备份快照时间,下游 snapshot 应使用恢复完成后的时间点。示例改为空值,并提示使用 SELECT TIDB_CURRENT_TSO(); 获取当前 TSO。

Changes: 数据校验时间说明

Layer / File(s) Summary
说明备份快照与校验时间
replicate-between-primary-and-secondary-clusters.md
说明 RESTORE 输出的 BackupTS 表示恢复所依据的备份快照时间。下游 snapshot 示例改为空值,并提示在 RESTORE 完成后填写恢复完成时间点,通过 SELECT TIDB_CURRENT_TSO(); 获取当前 TSO。

Priority: ➖ Normal

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other · Severity of issue fixed: Medium

Merge Risk: 🔵 Low · up to a9fd9

The snapshot instructions are now clear, but users following the TiUP installation path may still be unable to run the documented validation command.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Linked Issues check Warning 针对直接关联的 #21575,正文已说明 RESTORE 返回的 BackupTS 是恢复所依据的备份快照时间点,不是恢复完成时间。配置注释已要求将下游 snapshot 设为恢复完成后的时间点,并使用 SELECT TIDB_CURRENT_TSO(); 获取当前 TSO。文档中的校验命令仍为 sync_diff_inspector -C ./config.yaml,未按 #… 将 replicate-between-primary-and-secondary-clusters.md 中的数据校验命令改为 tiup sync-diff-inspector -C ./config.yaml。
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed 标题“docs: clarify the snapshot time for sync-diff-inspector”与变更内容相关。变更澄清了 RESTORE 返回的 BackupTS 是备份快照时间点,而非恢复完成时间,并说明下游 snapshot 应设为恢复完成之后的时间点。标题准确描述了主要变更,表述简洁。
Description check Passed 描述已按模板填写主要部分:变更内容说明(指出原文档错误、说明 BackupTS 的含义、修正 snapshot 配置注释)、关联 issue(Close #21575)、适用版本(master)、相关链接以及 AI agent 参与声明。首次贡献者检查项已勾选。描述基本完整。未填写的可选项包括关联代码 PR、是否为翻译文档等,但不影响判断。
Out of Scope Changes check Passed 相对合并基准,变更仅涉及 replicate-between-primary-and-secondary-clusters.md 的数据校验说明和下游 snapshot 配置注释。这些变更直接服务于 #21575。未发现无关变更。
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (1 skipped: 1 unsupported.)

Full details: Linked Issues check

Explanation

针对直接关联的 #21575,正文已说明 RESTORE 返回的 BackupTS 是恢复所依据的备份快照时间点,不是恢复完成时间。配置注释已要求将下游 snapshot 设为恢复完成后的时间点,并使用 SELECT TIDB_CURRENT_TSO(); 获取当前 TSO。文档中的校验命令仍为 sync_diff_inspector -C ./config.yaml,未按 #21575 改为 tiup sync-diff-inspector -C ./config.yaml。

Resolution

将 replicate-between-primary-and-secondary-clusters.md 中的数据校验命令改为 tiup sync-diff-inspector -C ./config.yaml。

✨ 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

Comment @coderabbitai help to get the list of available commands.

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


ℹ️ Review info
⚙️ Run configuration
📥 Commits

Reviewing files that changed from the base of the PR and between 9f0e45f and 1833885.

📒 Files selected for processing: 1
  • replicate-between-primary-and-secondary-clusters.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.

Replace the concrete BackupTS value returned by RESTORE with an empty value
so that readers do not copy a backup snapshot time into the downstream
snapshot setting, which can cause sync-diff-inspector to report that the
table does not exist. Address the review comment on pingcap#21996.

Signed-off-by: dzhmj0204-creator <306411393+dzhmj0204-creator@users.noreply.github.com>

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


ℹ️ Review info
⚙️ Run configuration
📥 Commits

Reviewing files that changed from the base of the PR and between 1833885 and d32752f.

📒 Files selected for processing: 1
  • replicate-between-primary-and-secondary-clusters.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.

The NOW()-based expression only has second precision, so the TSO derived from
it can be earlier than the restore completion time when the restore finishes
within the same second. Use TIDB_CURRENT_TSO(), which returns a real TSO and
is already documented in functions-and-operators/tidb-functions.md.

Signed-off-by: dzhmj0204-creator <306411393+dzhmj0204-creator@users.noreply.github.com>
@dzhmj0204-creator

Copy link
Copy Markdown
Author

One more follow-up on the second suggestion in this thread: you are right that
NOW() only has second precision, so the TSO derived from it can be earlier
than the restore completion time when the restore finishes within the same
second.

I have replaced the expression with SELECT TIDB_CURRENT_TSO();, which returns
a real TSO and is already documented in
functions-and-operators/tidb-functions.md. Pushed in a9fd92d.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

contribution This PR is from a community contributor. first-time-contributor Indicates that the PR was contributed by an external member and is a first-time contributor. missing-translation-status This PR does not have translation status info. needs-ok-to-test Indicates a PR created by contributors and need ORG member send '/ok-to-test' to start testing. size/XS Denotes a PR that changes 0-9 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

关于校验数据部分的问题

1 participant