Skip to content

Update br-checkpoint-backup.md #37

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
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Update br-checkpoint-backup.md #37

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
be56261
Update br-checkpoint-backup.md
qiancai Apr 21, 2025
7b725f1
Update br-checkpoint-backup.md
qiancai Apr 21, 2025
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
10 changes: 5 additions & 5 deletions br/br-checkpoint-backup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,13 @@ aliases: ["/tidb/dev/br-checkpoint"]

# Checkpoint Backup

Snapshot backup might be interrupted due to recoverable errors, such as disk exhaustion and node crash. Before TiDB v6.5.0, data that is backed up before the interruption would be invalidated even after the error is addressed, and you need to start the backup from scratch. For large clusters, this incurs considerable extra cost.
Snapshot backup might be interrupted due t recoverable errors, such as disk exhaustion and node crash. Before TiDB v6.5.0, data that is backed up before the interruption would be invalidated even after the error is addressed, and you need to start the backup from scratch. For large clusters, this incurs considerable extra cost.
Copy link

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion

Correct typo and improve clarity in error description.

The phrase “due t recoverable errors” should be “due to recoverable errors”, and the sentence can be rephrased to maintain neutral, third‑person tone.

Proposed diff:

- Snapshot backup might be interrupted due t recoverable errors, such as disk exhaustion and node crash. Before TiDB v6.5.0, data that is backed up before the interruption would be invalidated even after the error is addressed, and you need to start the backup from scratch. For large clusters, this incurs considerable extra cost.
+ Snapshot backups might be interrupted due to recoverable errors, such as disk exhaustion or node crashes. Before TiDB v6.5.0, all previously backed-up data would be invalidated after such interruptions, requiring a full restart of the backup process. For large clusters, this can be costly.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
Snapshot backup might be interrupted due t recoverable errors, such as disk exhaustion and node crash. Before TiDB v6.5.0, data that is backed up before the interruption would be invalidated even after the error is addressed, and you need to start the backup from scratch. For large clusters, this incurs considerable extra cost.
Snapshot backups might be interrupted due to recoverable errors, such as disk exhaustion or node crashes. Before TiDB v6.5.0, all previously backed-up data would be invalidated after such interruptions, requiring a full restart of the backup process. For large clusters, this can be costly.

Copy link

Choose a reason for hiding this comment

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

low

Typo: "due t recoverable" should be "due to recoverable"1

Style Guide References

Suggested change
Snapshot backup might be interrupted due t recoverable errors, such as disk exhaustion and node crash. Before TiDB v6.5.0, data that is backed up before the interruption would be invalidated even after the error is addressed, and you need to start the backup from scratch. For large clusters, this incurs considerable extra cost.
Snapshot backup might be interrupted due to recoverable errors, such as disk exhaustion and node crash. Before TiDB v6.5.0, data that is backed up before the interruption would be invalidated even after the error is addressed, and you need to start the backup from scratch. For large clusters, this incurs considerable extra cost.

Footnotes

  1. Correct English grammar, spelling, and punctuation mistakes if any. (link) ↩


In TiDB v6.5.0, Backup & Restore (BR) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.
In TiDB v6.5.0, Backup & Restore (B) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.
Copy link

Choose a reason for hiding this comment

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

⚠️ Potential issue

Fix the tool name abbreviation.

The documentation refers to “Backup & Restore (B)” but the correct abbreviation is “BR” (the tool’s name).

Proposed diff:

- In TiDB v6.5.0, Backup & Restore (B) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.
+ In TiDB v6.5.0, Backup & Restore (BR) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
In TiDB v6.5.0, Backup & Restore (B) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.
In TiDB v6.5.0, Backup & Restore (BR) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.

Copy link

Choose a reason for hiding this comment

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

low

Abbreviation: It might be better to spell out "Backup & Restore" here as "Backup and Restore" for clarity, or use the full abbreviation "(Backup & Restore (BR))"1

Style Guide References

Suggested change
In TiDB v6.5.0, Backup & Restore (B) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.
In TiDB v6.5.0, Backup & Restore (BR) introduces the checkpoint backup feature to allow continuing an interrupted backup. This feature can retain most data of the interrupted backup.

Footnotes

  1. Clarity, simplicity, completeness, and readability (link) ↩


## Application scenarios

If your TiDB cluster is large and cannot afford to back up again after a failure, you can use the checkpoint backup feature. The br command-line tool (hereinafter referred to as `br`) periodically records the shards that have been backed up. In this way, the next backup retry can use the backup progress close to the abnormal exit.
If your TiDB cluster is large and cannot affords to backup again after a failure, users can use the checkpoint backup feature. The br command-line tool (hereinafter referred to as `br`) periodically records the shards that have been backed up. In this way, the next backup retry can use the backup progress close to the abnormal exit.
Copy link

Choose a reason for hiding this comment

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

🛠️ Refactor suggestion

Use correct verb forms and neutral tone.

The phrase “cannot affords to backup” is grammatically incorrect and still addresses the reader indirectly.

Proposed diff:

- If your TiDB cluster is large and cannot affords to backup again after a failure, users can use the checkpoint backup feature. The br command-line tool (hereinafter referred to as `br`) periodically records the shards that have been backed up. In this way, the next backup retry can use the backup progress close to the abnormal exit.
+ If a TiDB cluster is large and restarting the backup from scratch is not feasible after a failure, users can use the checkpoint backup feature. The `br` command‑line tool periodically records completed shards, allowing the next retry to resume from the last recorded progress.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
If your TiDB cluster is large and cannot affords to backup again after a failure, users can use the checkpoint backup feature. The br command-line tool (hereinafter referred to as `br`) periodically records the shards that have been backed up. In this way, the next backup retry can use the backup progress close to the abnormal exit.
If a TiDB cluster is large and restarting the backup from scratch is not feasible after a failure, users can use the checkpoint backup feature. The `br` command‑line tool periodically records completed shards, allowing the next retry to resume from the last recorded progress.
🧰 Tools
🪛 LanguageTool

[grammar] ~15-~15: The modal verb ‘cannot’ requires the verb’s base form.
Context: ...f your TiDB cluster is large and cannot affords to backup again after a failure, users ...

(MD_BASEFORM)

Copy link

Choose a reason for hiding this comment

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

low

Grammar: "cannot affords" should be "cannot afford"1. Also, rephrasing to avoid direct address: "users can use" instead of "you can use"2

Style Guide References

Suggested change
If your TiDB cluster is large and cannot affords to backup again after a failure, users can use the checkpoint backup feature. The br command-line tool (hereinafter referred to as `br`) periodically records the shards that have been backed up. In this way, the next backup retry can use the backup progress close to the abnormal exit.
If your TiDB cluster is large and cannot afford to backup again after a failure, users can use the checkpoint backup feature. The br command-line tool (hereinafter referred to as `br`) periodically records the shards that have been backed up. In this way, the next backup retry can use the backup progress close to the abnormal exit.

Footnotes

  1. Correct English grammar, spelling, and punctuation mistakes if any. (link) ↩

  2. Write in second person ("you") when addressing users. (link) ↩


## Implementation details

Expand All @@ -30,7 +30,7 @@ Checkpoint backup relies on the GC mechanism and cannot recover all data that ha

During the backup, `br` periodically updates the `gc-safepoint` of the backup snapshot in PD to avoid data being garbage collected. When `br` exits, the `gc-safepoint` cannot be updated in time. As a result, before the next backup retry, the data might have been garbage collected.

To avoid this situation, `br` keeps the `gc-safepoint` for about one hour by default when `gcttl` is not specified. You can set the `gcttl` parameter to extend the retention period if needed .
To avoid this situation, `br` keeps the `gc-safepoint` for about one hour by default when `gcttl` is not specified. Users can set the `gcttl` parameter to extend the retention period if needed .

The following example sets `gcttl` to 15 hours (54000 seconds) to extend the retention period of `gc-safepoint`:

Expand All @@ -42,7 +42,7 @@ tiup br backup full \

> **Note:**
>
> The `gc-safepoint` created before backup is deleted after the snapshot backup is completed. You do not need to delete it manually.
> The `gc-safepoint` created before backup is deleted after the snapshot backup is completed. Users do not need to delete it manually.

### Some data needs to be backed up again

Expand Down
Loading