br: pitr filter feature release doc (#21109) #22199
Conversation
Signed-off-by: ti-chi-bot <ti-community-prow-bot@tidb.io>
ti-chi-bot
added
do-not-merge/hold
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
Summary of ChangesHello @ti-chi-bot, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request updates the TiDB documentation for Point-in-Time Recovery (PITR) to reflect new features and operational enhancements introduced in TiDB v9.0.0. The changes provide comprehensive guidance on filtering data during PITR, executing concurrent restore tasks, and managing compatibility with ongoing log backups. Additionally, it introduces a new command for gracefully aborting failed restore processes, improving the overall robustness and user experience of backup and restore operations. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation for new PITR features available in TiDB v9.0.0, such as filtering, concurrent restores, and aborting operations. My review includes a critical fix for unresolved merge conflict markers that were left in the document. I have also provided several suggestions to improve clarity and conciseness, aligning with the repository's style guide for technical documentation.
| <<<<<<< HEAD | ||
| ======= | ||
| ### Restore data using filters | ||
| Starting from TiDB v9.0.0, you can use filters during PITR to restore specific databases or tables, enabling more fine-grained control over the data to be restored. | ||
| The filter patterns follow the same [table filtering syntax](/table-filter.md) as other BR operations: | ||
| - `'*.*'`: matches all databases and tables. | ||
| - `'db1.*'`: matches all tables in the database `db1`. | ||
| - `'db1.table1'`: matches the specific table `table1` in the database `db1`. | ||
| - `'db*.tbl*'`: matches databases starting with `db` and tables starting with `tbl`. | ||
| - `'!mysql.*'`: excludes all tables in the `mysql` database. | ||
| Usage examples: | ||
| ```shell | ||
| # restore specific databases | ||
| tiup br restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --start-ts "2025-06-02 00:00:00+0800" \ | ||
| --restored-ts "2025-06-03 18:00:00+0800" \ | ||
| --filter 'db1.*' --filter 'db2.*' | ||
| # restore specific tables | ||
| tiup br restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --start-ts "2025-06-02 00:00:00+0800" \ | ||
| --restored-ts "2025-06-03 18:00:00+0800" \ | ||
| --filter 'db1.users' --filter 'db1.orders' | ||
| # restore using pattern matching | ||
| tiup br restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --start-ts "2025-06-02 00:00:00+0800" \ | ||
| --restored-ts "2025-06-03 18:00:00+0800" \ | ||
| --filter 'db*.tbl*' | ||
| ``` | ||
| > **Note:** | ||
| > | ||
| > - Before restoring data using filters, ensure that the target cluster does not contain any databases or tables that match the filter. Otherwise, the restore will fail with an error. | ||
| > - The filter options apply during the restore phase for both snapshot and log backups. | ||
| > - You can specify multiple `--filter` options to include or exclude different patterns. | ||
| > - PITR filtering does not support system tables yet. If you need to restore specific system tables, use the `br restore full` command with filters instead. Note that this command restores only the snapshot backup data (not log backup data). | ||
| ### Concurrent restore operations | ||
| Starting from TiDB v9.0.0, you can run multiple PITR restore tasks concurrently. This feature allows you to restore different datasets in parallel, improving efficiency for large-scale restore scenarios. | ||
| Usage example for concurrent restores: | ||
| ```shell | ||
| # terminal 1 - restore database db1 | ||
| tiup br restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --start-ts "2025-06-02 00:00:00+0800" \ | ||
| --restored-ts "2025-06-03 18:00:00+0800" \ | ||
| --filter 'db1.*' | ||
| # terminal 2 - restore database db2 (can run simultaneously) | ||
| tiup br restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --start-ts "2025-06-02 00:00:00+0800" \ | ||
| --restored-ts "2025-06-03 18:00:00+0800" \ | ||
| --filter 'db2.*' | ||
| ``` | ||
| > **Note:** | ||
| > | ||
| > Each concurrent restore operation must target a different database or a non-overlapping set of tables. Attempting to restore overlapping datasets concurrently will result in an error. | ||
| ### Compatibility between ongoing log backup and snapshot restore | ||
| Starting from v9.0.0, when a log backup task is running, if all of the following conditions are met, you can still perform snapshot restore (`br restore [full|database|table]`) and allow the restored data to be properly recorded by the ongoing log backup (hereinafter referred to as "log backup"): | ||
| - The node performing backup and restore operations has the following necessary permissions: | ||
| - Read access to the external storage containing the backup source, for snapshot restore | ||
| - Write access to the target external storage used by the log backup | ||
| - The target external storage for the log backup is Amazon S3 (`s3://`), Google Cloud Storage (`gcs://`), or Azure Blob Storage (`azblob://`). | ||
| - The data to be restored uses the same type of external storage as the target storage for the log backup. | ||
| - Neither the data to be restored nor the log backup has enabled local encryption. For details, see [log backup encryption](#encrypt-the-log-backup-data) and [snapshot backup encryption](/br/br-snapshot-manual.md#encrypt-the-backup-data). | ||
| If any of the above conditions are not met, you can restore the data by following these steps: | ||
| 1. [Stop the log backup task](#stop-a-log-backup-task). | ||
| 2. Perform the data restore. | ||
| 3. After the restore is complete, perform a new snapshot backup. | ||
| 4. [Restart the log backup task](#restart-a-log-backup-task). | ||
| > **Note:** | ||
| > | ||
| > When restoring a log backup that contains records of snapshot (full) restore data, you must use BR v9.0.0 or later. Otherwise, restoring the recorded full restore data might fail. | ||
| ### Compatibility between ongoing log backup and PITR operations | ||
| Starting from TiDB v9.0.0, you can perform PITR operations while a log backup task is running by default. The system automatically handles compatibility between these operations. | ||
| #### Important limitation for PITR with ongoing log backup | ||
| When you perform the PITR operations while a log backup is running, the restored data will also be recorded in the ongoing log backup. However, due to the nature of log restore operations, data inconsistencies might occur within the restore window. The system writes metadata to external storage to mark both the time range and data range where consistency cannot be guaranteed. | ||
| If such inconsistency occurs during the time range `[t1, t2)`, you cannot directly restore data from this period. Instead, choose one of the following alternatives: | ||
| - Restore data up to `t1` (to retrieve data before the inconsistent period). | ||
| - Perform a new snapshot backup after `t2`, and use it as the base for future PITR operations. | ||
| ### Abort restore operations | ||
| If a restore operation fails, you can use the `tiup br abort` command to clean up registry entries and checkpoint data. This command automatically locates and removes relevant metadata based on the original restore parameters, including entries in the `mysql.tidb_restore_registry` table and checkpoint data (regardless of whether it is stored in a local database or external storage). | ||
| > **Note:** | ||
| > | ||
| > The `abort` command only cleans up metadata. You need to manually delete any actual restored data from the cluster. | ||
| The examples of aborting restore operations using the same parameters as the original restore command are as follows: | ||
| ```shell | ||
| # Abort a PITR operation | ||
| tiup br abort restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' | ||
| # Abort a PITR operation with filters | ||
| tiup br abort restore point --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --filter 'db1.*' | ||
| # Abort a full restore | ||
| tiup br abort restore full --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' | ||
| # Abort a database restore | ||
| tiup br abort restore db --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --db database_name | ||
| # Abort a table restore | ||
| tiup br abort restore table --pd="${PD_IP}:2379" \ | ||
| --storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \ | ||
| --db database_name --table table_name | ||
| ``` | ||
| >>>>>>> 5182861b86 (br: pitr filter feature release doc (#21109)) |
There was a problem hiding this comment.
This block contains unresolved merge conflict markers (<<<<<<< HEAD, =======, >>>>>>>). These markers must be removed to ensure the document renders correctly.
### Restore data using filters
Starting from TiDB v9.0.0, you can use filters during PITR to restore specific databases or tables, enabling more fine-grained control over the data to be restored.
The filter patterns follow the same [table filtering syntax](/table-filter.md) as other BR operations:
- `'*.*'`: matches all databases and tables.
- `'db1.*'`: matches all tables in the database `db1`.
- `'db1.table1'`: matches the specific table `table1` in the database `db1`.
- `'db*.tbl*'`: matches databases starting with `db` and tables starting with `tbl`.
- `'!mysql.*'`: excludes all tables in the `mysql` database.
Usage examples:
```shell
# restore specific databases
tiup br restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--start-ts "2025-06-02 00:00:00+0800" \
--restored-ts "2025-06-03 18:00:00+0800" \
--filter 'db1.*' --filter 'db2.*'
# restore specific tables
tiup br restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--start-ts "2025-06-02 00:00:00+0800" \
--restored-ts "2025-06-03 18:00:00+0800" \
--filter 'db1.users' --filter 'db1.orders'
# restore using pattern matching
tiup br restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--start-ts "2025-06-02 00:00:00+0800" \
--restored-ts "2025-06-03 18:00:00+0800" \
--filter 'db*.tbl*'Note:
- Before restoring data using filters, ensure that the target cluster does not contain any databases or tables that match the filter. Otherwise, the restore will fail with an error.
- The filter options apply during the restore phase for both snapshot and log backups.
- You can specify multiple
--filteroptions to include or exclude different patterns.- PITR filtering does not support system tables yet. If you need to restore specific system tables, use the
br restore fullcommand with filters instead. Note that this command restores only the snapshot backup data (not log backup data).
Concurrent restore operations
Starting from TiDB v9.0.0, you can run multiple PITR restore tasks concurrently. This feature allows you to restore different datasets in parallel, improving efficiency for large-scale restore scenarios.
Usage example for concurrent restores:
# terminal 1 - restore database db1
tiup br restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--start-ts "2025-06-02 00:00:00+0800" \
--restored-ts "2025-06-03 18:00:00+0800" \
--filter 'db1.*'
# terminal 2 - restore database db2 (can run simultaneously)
tiup br restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--start-ts "2025-06-02 00:00:00+0800" \
--restored-ts "2025-06-03 18:00:00+0800" \
--filter 'db2.*'Note:
Each concurrent restore operation must target a different database or a non-overlapping set of tables. Attempting to restore overlapping datasets concurrently will result in an error.
Compatibility between ongoing log backup and snapshot restore
Starting from v9.0.0, when a log backup task is running, if all of the following conditions are met, you can still perform snapshot restore (br restore [full|database|table]) and allow the restored data to be properly recorded by the ongoing log backup (hereinafter referred to as "log backup"):
- The node performing backup and restore operations has the following necessary permissions:
- Read access to the external storage containing the backup source, for snapshot restore
- Write access to the target external storage used by the log backup
- The target external storage for the log backup is Amazon S3 (
s3://), Google Cloud Storage (gcs://), or Azure Blob Storage (azblob://). - The data to be restored uses the same type of external storage as the target storage for the log backup.
- Neither the data to be restored nor the log backup has enabled local encryption. For details, see log backup encryption and snapshot backup encryption.
If any of the above conditions are not met, you can restore the data by following these steps:
- Stop the log backup task.
- Perform the data restore.
- After the restore is complete, perform a new snapshot backup.
- Restart the log backup task.
Note:
When restoring a log backup that contains records of snapshot (full) restore data, you must use BR v9.0.0 or later. Otherwise, restoring the recorded full restore data might fail.
Compatibility between ongoing log backup and PITR operations
Starting from TiDB v9.0.0, you can perform PITR operations while a log backup task is running by default. The system automatically handles compatibility between these operations.
Important limitation for PITR with ongoing log backup
When you perform the PITR operations while a log backup is running, the restored data will also be recorded in the ongoing log backup. However, due to the nature of log restore operations, data inconsistencies might occur within the restore window. The system writes metadata to external storage to mark both the time range and data range where consistency cannot be guaranteed.
If such inconsistency occurs during the time range [t1, t2), you cannot directly restore data from this period. Instead, choose one of the following alternatives:
- Restore data up to
t1(to retrieve data before the inconsistent period). - Perform a new snapshot backup after
t2, and use it as the base for future PITR operations.
Abort restore operations
If a restore operation fails, you can use the tiup br abort command to clean up registry entries and checkpoint data. This command automatically locates and removes relevant metadata based on the original restore parameters, including entries in the mysql.tidb_restore_registry table and checkpoint data (regardless of whether it is stored in a local database or external storage).
Note:
The
abortcommand only cleans up metadata. You need to manually delete any actual restored data from the cluster.
The examples of aborting restore operations using the same parameters as the original restore command are as follows:
# Abort a PITR operation
tiup br abort restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}'
# Abort a PITR operation with filters
tiup br abort restore point --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--full-backup-storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--filter 'db1.*'
# Abort a full restore
tiup br abort restore full --pd="${PD_IP}:2379" \
--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}'
# Abort a database restore
tiup br abort restore db --pd="${PD_IP}:2379" \
--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--db database_name
# Abort a table restore
tiup br abort restore table --pd="${PD_IP}:2379" \
--storage='s3://backup-101/snapshot-20250602000000?access-key=${ACCESS-KEY}&secret-access-key=${SECRET-ACCESS-KEY}' \
--db database_name --table table_name| ### Compatibility between ongoing log backup and snapshot restore | ||
| Starting from v9.0.0, when a log backup task is running, if all of the following conditions are met, you can still perform snapshot restore (`br restore [full|database|table]`) and allow the restored data to be properly recorded by the ongoing log backup (hereinafter referred to as "log backup"): |
There was a problem hiding this comment.
This sentence is a bit long and complex. For better readability, consider rephrasing it to be more direct, in line with the style guide's emphasis on clarity and simplicity.
| Starting from v9.0.0, when a log backup task is running, if all of the following conditions are met, you can still perform snapshot restore (`br restore [full|database|table]`) and allow the restored data to be properly recorded by the ongoing log backup (hereinafter referred to as "log backup"): | |
| Starting from v9.0.0, you can perform a snapshot restore (`br restore [full|database|table]`) while a log backup task is running. For the restored data to be correctly recorded by the ongoing log backup, all of the following conditions must be met: |
References
- The style guide recommends writing for clarity and simplicity, and avoiding unnecessary words. (link)
| Starting from v9.0.0, when a log backup task is running, if all of the following conditions are met, you can still perform snapshot restore (`br restore [full|database|table]`) and allow the restored data to be properly recorded by the ongoing log backup (hereinafter referred to as "log backup"): | ||
| - The node performing backup and restore operations has the following necessary permissions: |
There was a problem hiding this comment.
This line has a trailing whitespace. Please remove it for consistency and clean formatting.
| - The node performing backup and restore operations has the following necessary permissions: | |
| - The node performing backup and restore operations has the following necessary permissions: |
| > | ||
| > The `abort` command only cleans up metadata. You need to manually delete any actual restored data from the cluster. | ||
| The examples of aborting restore operations using the same parameters as the original restore command are as follows: |
There was a problem hiding this comment.
This sentence is a bit wordy. Consider a more concise phrasing to improve readability, as suggested by the style guide.
| The examples of aborting restore operations using the same parameters as the original restore command are as follows: | |
| The following examples show how to abort restore operations using the same parameters as the original restore command: |
References
- The style guide recommends avoiding unnecessary words. (link)
|
@ti-chi-bot: The following test failed, say
Full PR test history. Your PR dashboard. DetailsInstructions 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. I understand the commands that are listed here. |
3 participants
This is an automated cherry-pick of #21109
First-time contributors' checklist
What is changed, added or deleted? (Required)
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.
What is the related PR or file link(s)?
br: pitr filter feature release doc docs-cn#20450
Do your changes match any of the following descriptions?