From 7d7cc80080fe984cb8733aa2eb5f7205b2ec8591 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Tue, 3 Jun 2025 15:41:06 -0400 Subject: [PATCH 1/6] br: pitr filter feature release doc Signed-off-by: Wenqi Mou --- br/br-pitr-manual.md | 98 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 93 insertions(+), 5 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 8932bef2b14c..f470284731e8 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -496,9 +496,85 @@ tiup br restore point --pd="${PD_IP}:2379" --master-key "local:///path/to/master.key" ``` +### 使用过滤器恢复 + +从 TiDB v9.0.0 开始，你可以在 PITR 过程中使用过滤器来选择性地恢复特定的数据库或表。这使得在时间点恢复操作中能够更精细地控制要恢复的数据。 + +过滤器模式遵循与其他 BR 操作中使用的[表库过滤](/table-filter.md)相同的语法： + +- `'*.*'` - 匹配所有数据库和表 +- `'db1.*'` - 匹配数据库 `db1` 中的所有表 +- `'db1.table1'` - 匹配数据库 `db1` 中的特定表 `table1` +- `'db*.tbl*'` - 匹配以 `db` 开头的数据库和以 `tbl` 开头的表 +- `'!mysql.*'` - 排除 `mysql` 数据库中的所有表 + +使用示例： + +```shell +# 恢复特定数据库 +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.*' + +# 恢复特定表 +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' + +# 使用模式匹配恢复 +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*' +``` + +> **注意：** +> +> - 使用过滤器时，请确保过滤的数据保持引用完整性。 +> - 过滤器选项适用于快照备份和日志备份恢复阶段。 +> - 可以指定多个 `--filter` 选项来包含或排除不同的模式。 +> - PITR 过滤暂不支持系统表。如果需要恢复特定的系统表，请使用 `br restore full` 命令并配合过滤器，该命令仅恢复快照备份数据（而非日志备份数据）。 +> - 过滤器中指定的目标数据库和表在集群中必须不存在，否则恢复将失败并报错。 + +### 并发恢复操作 + +从 TiDB v9.0.0 开始，你可以同时运行多个 PITR 操作。此功能允许你同时恢复不同的数据集，提高大规模操作的恢复效率。 + +并发恢复的使用示例： + +```shell +# 终端 1 - 恢复数据库 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.*' + +# 终端 2 - 恢复数据库 db2（可同时运行） +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.*' +``` + +> **注意：** +> +> - 每个并发恢复操作必须针对不同的数据库或非重叠的表集合。尝试并发恢复重叠数据集将导致错误。 + ### 进行中的日志备份与快照恢复的兼容性 -从 v9.0.0 开始，当存在日志备份任务时，如果**同时满足**以下条件，则可以正常进行快照恢复 (`br restore [full|database|table]`)，并且恢复的数据可以被进行中的日志备份（下称“日志备份”）正常记录： +从 v9.0.0 开始，当存在日志备份任务时，如果**同时满足**以下条件，则可以正常进行快照恢复 (`br restore [full|database|table]`)，并且恢复的数据可以被进行中的日志备份（下称"日志备份"）正常记录： - 执行备份恢复操作的节点需要同时具备以下权限： - 对备份来源外部存储的读取权限，用于执行快照恢复 @@ -507,13 +583,25 @@ tiup br restore point --pd="${PD_IP}:2379" - 待恢复的数据与日志备份的目标存储拥有相同的外部存储类型。 - 待恢复的数据和日志备份均未开启本地加密，参考[日志备份加密](#加密日志备份数据)和[快照备份加密](/br/br-snapshot-manual.md#备份数据加密)。 -如果不能同时满足上述条件或者要恢复到时间点，当存在日志备份任务时，BR 会拒绝恢复数据。此时，可以通过以下步骤完成数据恢复： - -1. [停止备份任务](#停止日志备份任务)。 +如果不能同时满足上述条件，你可以通过以下步骤完成数据恢复： +1. [停止日志备份任务](#停止日志备份任务)。 2. 进行数据恢复。 3. 恢复完成后，重新进行快照备份。 4. [重新启动备份任务](#重新启动备份任务)。 > **注意：** > -> 当恢复记录了快照（全量）恢复数据的日志备份时，需要使用 v9.0.0 及之后版本的 BR，否则可能导致记录下来的全量恢复数据无法被恢复。 \ No newline at end of file +> 当恢复记录了快照（全量）恢复数据的日志备份时，需要使用 v9.0.0 及之后版本的 BR，否则可能导致记录下来的全量恢复数据无法被恢复。 + +### 进行中的日志备份与 PITR 操作的兼容性 + +从 TiDB v9.0.0 开始，默认情况下你可以在日志备份任务运行时执行 PITR 操作。系统自动处理这些操作之间的兼容性。 + +#### 进行中的日志备份与 PITR 的重要限制 + +当在运行日志备份的同时执行 PITR 操作时，恢复的数据将被记录在日志备份中。但是，在恢复时间窗口期间，由于日志恢复操作的性质，数据可能不一致。系统会将元数据写入外部存储，以标记无法保证一致性的时间范围和数据范围。 + +如果在时间范围 `[t1, t2)` 期间发生此类不一致，你无法恢复该时间段的数据。你必须： + +- 恢复到 `t1` 时间点（不一致时期之前的数据），或 +- 在 `t2` 之后进行新的快照备份，并使用该备份进行未来的 PITR 操作 From 762ba0feb1d6e5598a4605d3953e077a0f4ea2e5 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Thu, 26 Jun 2025 20:25:21 -0400 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Lilian Lee --- br/br-pitr-manual.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index f470284731e8..1342a0e4630a 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -498,15 +498,15 @@ tiup br restore point --pd="${PD_IP}:2379" ### 使用过滤器恢复 -从 TiDB v9.0.0 开始，你可以在 PITR 过程中使用过滤器来选择性地恢复特定的数据库或表。这使得在时间点恢复操作中能够更精细地控制要恢复的数据。 +从 TiDB v9.0.0 开始，在按时间点恢复 (PITR) 过程中，你可以使用过滤器来选择性地恢复特定的数据库或表，从而更精细地控制要恢复的数据。 -过滤器模式遵循与其他 BR 操作中使用的[表库过滤](/table-filter.md)相同的语法： +过滤器采用与其他 BR 操作相同的[表库过滤语法](/table-filter.md)： -- `'*.*'` - 匹配所有数据库和表 -- `'db1.*'` - 匹配数据库 `db1` 中的所有表 -- `'db1.table1'` - 匹配数据库 `db1` 中的特定表 `table1` -- `'db*.tbl*'` - 匹配以 `db` 开头的数据库和以 `tbl` 开头的表 -- `'!mysql.*'` - 排除 `mysql` 数据库中的所有表 +- `'*.*'`：匹配所有数据库和表。 +- `'db1.*'`：匹配数据库 `db1` 中的所有表。 +- `'db1.table1'`：匹配数据库 `db1` 中的特定表 `table1`。 +- `'db*.tbl*'`：匹配以 `db` 开头的数据库和以 `tbl` 开头的表。 +- `'!mysql.*'`：排除 `mysql` 数据库中的所有表。 使用示例： @@ -538,15 +538,14 @@ tiup br restore point --pd="${PD_IP}:2379" \ > **注意：** > -> - 使用过滤器时，请确保过滤的数据保持引用完整性。 -> - 过滤器选项适用于快照备份和日志备份恢复阶段。 +> - 使用过滤器恢复前，请确保目标集群中不存在与过滤器匹配的数据库或表，否则恢复将失败并报错。 +> - 过滤器选项适用于快照备份和日志备份的恢复阶段。 > - 可以指定多个 `--filter` 选项来包含或排除不同的模式。 -> - PITR 过滤暂不支持系统表。如果需要恢复特定的系统表，请使用 `br restore full` 命令并配合过滤器，该命令仅恢复快照备份数据（而非日志备份数据）。 -> - 过滤器中指定的目标数据库和表在集群中必须不存在，否则恢复将失败并报错。 +> - PITR 过滤暂不支持系统表。如果需要恢复特定的系统表，请使用 `br restore full` 命令并配合过滤器，注意该命令仅恢复快照备份数据（而非日志备份数据）。 ### 并发恢复操作 -从 TiDB v9.0.0 开始，你可以同时运行多个 PITR 操作。此功能允许你同时恢复不同的数据集，提高大规模操作的恢复效率。 +从 TiDB v9.0.0 开始，你可以同时执行多个 PITR 恢复任务。该功能允许你并行恢复不同的数据集，从而提升大规模恢复场景下的效率。 并发恢复的使用示例： @@ -570,11 +569,11 @@ tiup br restore point --pd="${PD_IP}:2379" \ > **注意：** > -> - 每个并发恢复操作必须针对不同的数据库或非重叠的表集合。尝试并发恢复重叠数据集将导致错误。 +> 每个并发恢复操作必须作用于不同的数据库或不重叠的表集合。尝试并发恢复重叠数据集将导致错误。 ### 进行中的日志备份与快照恢复的兼容性 -从 v9.0.0 开始，当存在日志备份任务时，如果**同时满足**以下条件，则可以正常进行快照恢复 (`br restore [full|database|table]`)，并且恢复的数据可以被进行中的日志备份（下称"日志备份"）正常记录： +从 v9.0.0 开始，当存在日志备份任务时，如果**同时满足**以下条件，则可以正常进行快照恢复 (`br restore [full|database|table]`)，并且恢复的数据可以被进行中的日志备份（下称“日志备份”）正常记录： - 执行备份恢复操作的节点需要同时具备以下权限： - 对备份来源外部存储的读取权限，用于执行快照恢复 @@ -584,6 +583,7 @@ tiup br restore point --pd="${PD_IP}:2379" \ - 待恢复的数据和日志备份均未开启本地加密，参考[日志备份加密](#加密日志备份数据)和[快照备份加密](/br/br-snapshot-manual.md#备份数据加密)。 如果不能同时满足上述条件，你可以通过以下步骤完成数据恢复： + 1. [停止日志备份任务](#停止日志备份任务)。 2. 进行数据恢复。 3. 恢复完成后，重新进行快照备份。 @@ -595,13 +595,13 @@ tiup br restore point --pd="${PD_IP}:2379" \ ### 进行中的日志备份与 PITR 操作的兼容性 -从 TiDB v9.0.0 开始，默认情况下你可以在日志备份任务运行时执行 PITR 操作。系统自动处理这些操作之间的兼容性。 +从 TiDB v9.0.0 开始，默认情况下，你可以在日志备份任务运行期间执行 PITR 操作。系统会自动处理这些操作之间的兼容性。 #### 进行中的日志备份与 PITR 的重要限制 -当在运行日志备份的同时执行 PITR 操作时，恢复的数据将被记录在日志备份中。但是，在恢复时间窗口期间，由于日志恢复操作的性质，数据可能不一致。系统会将元数据写入外部存储，以标记无法保证一致性的时间范围和数据范围。 +当在运行日志备份的同时执行 PITR 操作时，恢复的数据也会被记录到日志备份中。但是，在恢复操作的时间窗口内，由于日志恢复操作的特性，可能存在数据不一致的风险。系统会将元数据写入外部存储，以标记无法保证一致性的时间范围和数据范围。 -如果在时间范围 `[t1, t2)` 期间发生此类不一致，你无法恢复该时间段的数据。你必须： +如果在时间范围 `[t1, t2)` 期间发生此类不一致，你无法直接恢复该时间段的数据，需选择以下替代方案： -- 恢复到 `t1` 时间点（不一致时期之前的数据），或 -- 在 `t2` 之后进行新的快照备份，并使用该备份进行未来的 PITR 操作 +- 恢复到 `t1` 时间点（获取不一致时期之前的数据） +- 或在 `t2` 时间点后执行新的快照备份，并基于此备份进行后续 PITR 操作 From 6a83151642e67f0f6557716f6a43facfc004fd66 Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Mon, 30 Jun 2025 17:45:01 -0400 Subject: [PATCH 3/6] add abort command Signed-off-by: Wenqi Mou --- br/br-pitr-manual.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 1342a0e4630a..0534a2335ad2 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -605,3 +605,38 @@ tiup br restore point --pd="${PD_IP}:2379" \ - 恢复到 `t1` 时间点（获取不一致时期之前的数据） - 或在 `t2` 时间点后执行新的快照备份，并基于此备份进行后续 PITR 操作 + +## 中止恢复操作 + +当恢复操作失败时，你可以使用 `tiup br abort` 命令来清理注册表条目和检查点数据。该命令会根据提供的原始恢复参数自动找到并删除相关的元数据，包括 `mysql.tidb_restore_registry` 表中的条目以及检查点数据（无论存储在本地数据库还是外部存储中）。注意，`abort` 命令仅清理元数据，任何实际恢复的数据需要手动从集群中删除。 + +### 使用示例 + +使用与原始恢复命令相同的参数： + +```shell +# 中止 PITR 操作 +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}' + +# 中止带过滤器的 PITR 操作 +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.*' + +# 中止全量恢复 +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}' + +# 中止数据库恢复 +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 + +# 中止表恢复 +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 +``` From 30520895783e84bb9fe77af46bc4ea34e7cc06fc Mon Sep 17 00:00:00 2001 From: Wenqi Mou Date: Fri, 11 Jul 2025 09:38:20 -0400 Subject: [PATCH 4/6] Update br/br-pitr-manual.md Co-authored-by: xixirangrang --- br/br-pitr-manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 0534a2335ad2..36009ff393f4 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -498,7 +498,7 @@ tiup br restore point --pd="${PD_IP}:2379" ### 使用过滤器恢复 -从 TiDB v9.0.0 开始，在按时间点恢复 (PITR) 过程中，你可以使用过滤器来选择性地恢复特定的数据库或表，从而更精细地控制要恢复的数据。 +从 TiDB v9.0.0 开始，在按时间点恢复 (PITR) 过程中，你可以使用过滤器恢复特定的数据库或表，从而更精细地控制要恢复的数据。 过滤器采用与其他 BR 操作相同的[表库过滤语法](/table-filter.md)： From 21c234835c86593d27a9ca3d04bebc4b486f6add Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Mon, 14 Jul 2025 11:48:16 +0800 Subject: [PATCH 5/6] Use note format --- br/br-pitr-manual.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 36009ff393f4..0154144c1ddf 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -608,7 +608,11 @@ tiup br restore point --pd="${PD_IP}:2379" \ ## 中止恢复操作 -当恢复操作失败时，你可以使用 `tiup br abort` 命令来清理注册表条目和检查点数据。该命令会根据提供的原始恢复参数自动找到并删除相关的元数据，包括 `mysql.tidb_restore_registry` 表中的条目以及检查点数据（无论存储在本地数据库还是外部存储中）。注意，`abort` 命令仅清理元数据，任何实际恢复的数据需要手动从集群中删除。 +当恢复操作失败时，你可以使用 `tiup br abort` 命令来清理注册表条目和检查点数据。该命令会根据提供的原始恢复参数自动找到并删除相关的元数据，包括 `mysql.tidb_restore_registry` 表中的条目以及检查点数据（无论存储在本地数据库还是外部存储中）。 + +> **注意：** +> +> `abort` 命令仅清理元数据，任何实际恢复的数据需要手动从集群中删除。 ### 使用示例 From f5ca940f446a8b2f5ba2fa7fcf7f248ca8495d26 Mon Sep 17 00:00:00 2001 From: Lilian Lee Date: Fri, 15 Aug 2025 14:22:23 +0800 Subject: [PATCH 6/6] Update heading level --- br/br-pitr-manual.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/br/br-pitr-manual.md b/br/br-pitr-manual.md index 0154144c1ddf..756174b771a6 100644 --- a/br/br-pitr-manual.md +++ b/br/br-pitr-manual.md @@ -606,7 +606,7 @@ tiup br restore point --pd="${PD_IP}:2379" \ - 恢复到 `t1` 时间点（获取不一致时期之前的数据） - 或在 `t2` 时间点后执行新的快照备份，并基于此备份进行后续 PITR 操作 -## 中止恢复操作 +### 中止恢复操作 当恢复操作失败时，你可以使用 `tiup br abort` 命令来清理注册表条目和检查点数据。该命令会根据提供的原始恢复参数自动找到并删除相关的元数据，包括 `mysql.tidb_restore_registry` 表中的条目以及检查点数据（无论存储在本地数据库还是外部存储中）。 @@ -614,9 +614,7 @@ tiup br restore point --pd="${PD_IP}:2379" \ > > `abort` 命令仅清理元数据，任何实际恢复的数据需要手动从集群中删除。 -### 使用示例 - -使用与原始恢复命令相同的参数： +使用与原始恢复命令相同的参数来中止恢复操作的示例如下： ```shell # 中止 PITR 操作