Skip to content

docs: add checkpoint restore warning #23201

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
qiancai wants to merge 3 commits into
base: master
Choose a base branch
from
+12 −0
Open

docs: add checkpoint restore warning #23201

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f25fa49
Create empty translation PR
qiancai Jul 4, 2026
90ff498
Auto-sync: Update English docs from Chinese PR
github-actions[bot] Jul 4, 2026
a834b9a
Update br/br-checkpoint-restore.md
qiancai Jul 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions br/br-checkpoint-restore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,18 @@ When `br` retries a restore, some data that has been restored might need to be r

After a restore failure, avoid writing, deleting, or creating tables in the cluster. This is because the backup data might contain DDL operations for renaming tables. If you modify the cluster data, the checkpoint restore cannot decide whether the deleted or existing table are resulted from external operations, which affects the accuracy of the next restore retry.

> **Warning:**
>
> Starting from v8.5.5, if you delete a table being restored during the restore and then retry the restore from the checkpoint, you might encounter the following issues (see [#68709](https://github.com/pingcap/tidb/issues/68709) for details):
>
> - The restore is terminated due to a checksum verification failure.
> - The restored data is lost some time after the restore is completed.
>
> If you are sure that you want to abandon the current restore result, first perform one of the following operations based on the restore type, and then `DROP` the restored table:
>
> - For `restore point`, execute [`br abort`](/br/br-pitr-manual.md#abort-restore-operations).
> - For `restore full`, manually delete the checkpoint database in the downstream cluster. The name format of the checkpoint database is `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint_<restoreID>`, where `<restoreID>` can be found in `mysql.tidb_restore_registry`.
Comment on lines +64 to +74

@gemini-code-assist gemini-code-assist Bot Jul 4, 2026

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.

low

To improve clarity, reduce repetition, and adhere to the active voice and second-person guidelines in the style guide, we can refine this warning block:

  • Avoid repeating "restored" and "restore" in "delete a table being restored during the restore".
  • Change passive voice ("is terminated", "is completed", "can be found") to active voice ("terminates", "completes", "you can find").
  • Use second person ("you") to address the user directly.
Suggested change
> **Warning:**
>
> Starting from v8.5.5, if you delete a table being restored during the restore and then retry the restore from the checkpoint, you might encounter the following issues (see [#68709](https://github.com/pingcap/tidb/issues/68709) for details):
>
> - The restore is terminated due to a checksum verification failure.
> - The restored data is lost some time after the restore is completed.
>
> If you are sure that you want to abandon the current restore result, first perform one of the following operations based on the restore type, and then `DROP` the restored table:
>
> - For `restore point`, execute [`br abort`](/br/br-pitr-manual.md#abort-restore-operations).
> - For `restore full`, manually delete the checkpoint database in the downstream cluster. The name format of the checkpoint database is `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint_<restoreID>`, where `<restoreID>` can be found in `mysql.tidb_restore_registry`.
> **Warning:**
>
> Starting from v8.5.5, if you delete a table during the restore process and then retry the restore from the checkpoint, you might encounter the following issues (see [#68709](https://github.com/pingcap/tidb/issues/68709) for details):
>
> - The restore terminates due to a checksum verification failure.
> - You might lose the restored data some time after the restore completes.
>
> If you are sure that you want to abandon the current restore result, first perform one of the following operations based on the restore type, and then `DROP` the restored table:
>
> - For `restore point`, execute [`br abort`](/br/br-pitr-manual.md#abort-restore-operations).
> - For `restore full`, manually delete the checkpoint database in the downstream cluster. The name format of the checkpoint database is `__TiDB_BR_Temporary_Snapshot_Restore_Checkpoint_<restoreID>`, where you can find `<restoreID>` in the `mysql.tidb_restore_registry` table.
References
  1. Write in second person ('you') when addressing users. (link)
  2. Prefer present tense unless describing historical behavior. (link)
  3. Avoid unnecessary words and repetition. (link)
  4. Avoid passive voice overuse. (link)


### Cross-major-version checkpoint recovery is not recommended

Cross-major-version checkpoint recovery is not recommended. For clusters where `br` recovery fails using the Long-Term Support (LTS) versions prior to v8.5.0, recovery cannot be continued with v8.5.0 or later LTS versions, and vice versa.
Expand Down
Loading