restore: update the definition of the parameter --load-stats and the usage of pitr id map

br/br-checkpoint-restore.md

@@ -89,7 +89,11 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold
 
 在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 `__TiDB_BR_Temporary_Log_Restore_Checkpoint` 数据库，然后使用其他备份重试。
 
-在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。
+注意在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。**如果随意删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。**
+
+> **注意：**
+>
+> 为了兼容旧版本集群，从 v9.0.0 开始，当恢复集群不存在系统表 `mysql.tidb_pitr_id_map` 时，`pitr_id_map` 数据会写到日志备份目录下，文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`。
 
 ## 实现细节：将断点数据存储在外部存储
 
@@ -151,4 +155,8 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold
 
 在第一次执行恢复并且进入日志恢复阶段时，br 工具会在恢复集群中创建路径 `restore-{downstream-cluster-ID}/log`，用于记录断点数据，以及这次恢复的上游集群 ID 和恢复的时间范围 `start-ts` 与 `restored-ts`。如果在此阶段恢复失败，重新执行恢复命令时，你需要指定与断点记录相同的 `start-ts` 和 `restored-ts` 参数，否则 br 工具会报错，并提示上游集群 ID 或恢复的时间范围与断点记录不同。如果恢复集群已被清理，你可以手动删除 存储在外部存储的断点数据或更换指定的断点数据存储路径，然后使用其他备份重试。
 
-在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到系统表 `mysql.tidb_pitr_id_map` 中，以避免库表 ID 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。
+注意在第一次执行恢复并且进入日志恢复阶段前，br 工具会构造出在 `restored-ts` 时间点的上下游集群库表 ID 映射关系，并将其持久化到存放断点数据的外部存储中（文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`），以避免库表 ID 被重复分配。**如果随意删除 `pitr_id_maps` 目录中的文件，可能会导致 PITR 恢复数据不一致。**
+
+> **注意：**
+>
+> 为了兼容旧版本集群，从 v9.0.0 开始，当恢复集群不存在系统表 `mysql.tidb_pitr_id_map` 且未指定参数 `--checkpoint-storage` 时，`pitr_id_map` 数据会写到日志备份目录下，文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`。

br/br-snapshot-guide.md

@@ -153,6 +153,7 @@ tiup br restore full \
 - `br` v5.1.0 开始，快照备份时默认自动备份 **mysql schema 下的系统表数据**，但恢复数据时默认不恢复系统表数据。
 - `br` v6.2.0 开始，增加恢复参数 `--with-sys-table` 支持恢复数据的同时恢复**部分系统表相关数据**。
 - `br` v7.6.0 开始，恢复参数 `--with-sys-table` 默认开启，即默认支持恢复数据的同时恢复**部分系统表相关数据**。
+- `br` v9.0.0 开始，增加恢复参数 `--fast-load-sys-tables` 支持物理恢复系统表。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。与通过 `REPLACE INTO` SQL 写入的逻辑恢复系统表方式不同，物理恢复系统表将会完全覆盖系统表中原有的数据。
 
 **可恢复的部分系统表**：
 

br/br-snapshot-manual.md

@@ -132,8 +132,19 @@ tiup br restore full \
 --storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log
 ```
 
+> **注意：**
+>
+> 从 v9.0.0 开始，当参数 `--load-stats` 设置为 `false` 时，br 不再向 `mysql.stats_meta` 表写入恢复表的统计信息。你可以在恢复完成后手动执行 [`ANALYZE TABLE`](/sql-statements/sql-statement-analyze-table.md)，以更新相关统计信息。
+
 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。
 
+从 v9.0.0 开始，BR 引入参数 `--fast-load-sys-tables`，该参数默认开启。在使用 br 命令行工具将数据恢复到一个全新集群，且上下游的表和分区 ID 能够复用的前提下（否则会自动回退为逻辑导入统计信息），开启 `--fast-load-sys-tables` 后，br 会先将统计信息相关表恢复至临时系统库 `__TiDB_BR_Temporary_mysql` 中，再通过 `RENAME TABLE` 语句将这些表与 `mysql` 库下的原有表进行原子性替换。使用示例如下：
+
+```shell
+tiup br restore full \
+--storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log --load-stats --fast-load-sys-tables
+```
+
 ## 备份数据加密
 
 br 命令行工具支持在备份端，或备份到 Amazon S3 的时候在[存储服务端进行备份数据加密](/br/backup-and-restore-storages.md#amazon-s3-存储服务端加密备份数据)，你可以根据自己情况选择其中一种使用。
@@ -186,6 +197,22 @@ Download&Ingest SST <-----------------------------------------------------------
 Restore Pipeline <-------------------------/...............................................> 17.12%
 ```
 
+从 TiDB v9.0.0 开始，你可以通过指定参数 `--fast-load-sys-tables` 在全新的集群上进行物理恢复系统表：
+
+```shell
+tiup br restore full \
+    --pd "${PD_IP}:2379" \
+    --with-sys-table \
+    --fast-load-sys-tables \
+    --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \
+    --ratelimit 128 \
+    --log-file restorefull.log
+```
+
+> **注意：**
+>
+> 与通过 `REPLACE INTO` SQL 语句执行的逻辑恢复系统表方式不同，物理恢复系统表会完全覆盖系统表中的原有数据。
+
 ## 恢复备份数据中指定库表的数据
 
 br 命令行工具支持只恢复备份数据中指定库/表的局部数据。该功能在恢复过程中过滤掉不需要的数据，可以用于往 TiDB 集群上恢复指定库/表的数据。