br: pitr filter feature release doc

br/br-pitr-manual.md

@@ -496,6 +496,84 @@ tiup br restore point --pd="${PD_IP}:2379"
 --master-key "local:///path/to/master.key"
 ```
 
+### Restore with filters
+
+Starting from TiDB v9.0.0, you can use filters during PITR to selectively restore specific databases or tables. This allows for more granular control over what data gets restored during point-in-time recovery operations.
+
+
+The filter patterns follow the same syntax as [table filters](/table-filter.md) used in other BR operations:
+
+- `'*.*'` - matches all databases and tables
+- `'db1.*'` - matches all tables in database `db1`
+- `'db1.table1'` - matches specific table `table1` in 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 with 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:**
+>
+> - When using filters, ensure that the filtered data maintains referential integrity.
+> - Filter options apply to both snapshot and log backup restoration phases.
+> - Multiple `--filter` options can be specified to include or exclude different patterns.
+> - PITR filtering does not support restoring system tables. System tables are restored according to the full backup data and cannot be selectively filtered during PITR operations. If you need to restore specific system tables, use `br restore full` with filters instead, which will restore only the snapshot backup data (not log backup data).
+> - The target databases and tables specified in the filter must not exist in the cluster, or the restore will fail with an error.
+
+### Concurrent restore operations
+
+Starting from TiDB v9.0.0, you can run multiple PITR operations concurrently. This feature allows you to restore different datasets simultaneously, improving restore efficiency for large-scale operations.
+
+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 different databases or non-overlapping table sets. 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"):
@@ -507,13 +585,25 @@ Starting from v9.0.0, when a log backup task is running, if all of the following
 - 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, or if you need to perform a point-in-time recovery, while a log backup task is running, BR refuses to proceed with the data recovery. In this case, you can complete the recovery by following these steps:
-
+If any of the above conditions are not met, you can complete the recovery 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.
+> 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 performing PITR operations while log backup is running, the restored data will be recorded in the log backup. However, during the restore time window, the data may not be consistent due to the nature of log restore operations. 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 restore data from that time period. Instead, you must:
+
+- Restore data up to `t1` (before the inconsistent period), or
+- Take a new snapshot backup after `t2` and use that for future PITR operations