From 6dee38c00326695b1e17e870d8e05167fcf9e459 Mon Sep 17 00:00:00 2001 From: Jianjun Liao Date: Mon, 19 May 2025 10:43:52 +0800 Subject: [PATCH 1/7] draft Signed-off-by: Jianjun Liao --- br/br-checkpoint-restore.md | 6 +++++- br/br-snapshot-manual.md | 4 ++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/br/br-checkpoint-restore.md b/br/br-checkpoint-restore.md index 16af1ef4bf12..050f829acc31 100644 --- a/br/br-checkpoint-restore.md +++ b/br/br-checkpoint-restore.md @@ -91,6 +91,10 @@ br 工具暂停 GC 的原理是通过执行 `SET config tikv gc.ratio-threshold 在第一次执行恢复并且进入日志恢复阶段前，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,4 @@ 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 被重复分配。如果删除 `mysql.tidb_pitr_id_map` 中的数据，可能会导致 PITR 恢复数据不一致。 diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index 8f4a5c9e0332..7435b543c4d9 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -132,6 +132,10 @@ tiup br restore full \ --storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log ``` +> **注意：** +> +> 从 v9.0.0 起，当关闭 br 命令行工具参数 `--load-stats` 时，br 将不会在表 `mysql.stats_meta` 中更新恢复的表的相关信息。如果你想要在恢复完成后手动分析表，那么可以关闭这个参数。 + 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。 ## 备份数据加密 From f93d5a6c05595aa5dfc36feddb93f67671cb8fb8 Mon Sep 17 00:00:00 2001 From: Jianjun Liao Date: Mon, 19 May 2025 10:57:42 +0800 Subject: [PATCH 2/7] fix typos Signed-off-by: Jianjun Liao --- br/br-checkpoint-restore.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-checkpoint-restore.md b/br/br-checkpoint-restore.md index 050f829acc31..c52c4b229d6f 100644 --- a/br/br-checkpoint-restore.md +++ b/br/br-checkpoint-restore.md @@ -155,4 +155,4 @@ 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 映射关系，并将其持久化到存放断点数据的外部存储中（文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`），以避免库表 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 恢复数据不一致。 From dd8aa2b4cf3f4382a10938336c3645aa2e998b43 Mon Sep 17 00:00:00 2001 From: Jianjun Liao Date: Fri, 23 May 2025 12:06:16 +0800 Subject: [PATCH 3/7] commit some suggestions Signed-off-by: Jianjun Liao --- br/br-checkpoint-restore.md | 6 +++--- br/br-snapshot-guide.md | 1 + br/br-snapshot-manual.md | 19 +++++++++++++++++++ 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/br/br-checkpoint-restore.md b/br/br-checkpoint-restore.md index c52c4b229d6f..90e8e6ee5bc3 100644 --- a/br/br-checkpoint-restore.md +++ b/br/br-checkpoint-restore.md @@ -89,11 +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}`。 +> 为了兼容旧版本集群，从 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}`。 ## 实现细节：将断点数据存储在外部存储 @@ -155,4 +155,4 @@ 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 映射关系，并将其持久化到存放断点数据的外部存储中（文件名为 `pitr_id_maps/pitr_id_map.cluster_id:{downstream-cluster-ID}.restored_ts:{restored-ts}`），以避免库表 ID 被重复分配。如果删除 `pitr_id_maps` 目录中的文件，可能会导致 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 恢复数据不一致。** diff --git a/br/br-snapshot-guide.md b/br/br-snapshot-guide.md index adb174da0176..0a34e99d5ef8 100644 --- a/br/br-snapshot-guide.md +++ b/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 开始，增加恢复参数 `--load-sys-table-physical` 支持物理恢复系统表。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。 **可恢复的部分系统表**： diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index 7435b543c4d9..89705a53e3f2 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -138,6 +138,13 @@ tiup br restore full \ 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。 +从 9.0.0 起，BR 引入参数 `--load-stats-physical`。当 br 命令行工具恢复在全新集群并且上下游表和分区的 ID 都能被复用时，通过设置 `--load-stats-physical` 会将统计信息相关表恢复到临时系统库 `__TiDB_BR_Temporary_mysql` 中，再通过 `RENAME TABLE` DDL 将恢复的统计信息表和 `mysql` 库下的表进行原子交换。示例如下： + +```shell +tiup br restore full \ +--storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log --load-stats --load-stats-physical +``` + ## 备份数据加密 br 命令行工具支持在备份端，或备份到 Amazon S3 的时候在[存储服务端进行备份数据加密](/br/backup-and-restore-storages.md#amazon-s3-存储服务端加密备份数据)，你可以根据自己情况选择其中一种使用。 @@ -190,6 +197,18 @@ Download&Ingest SST <----------------------------------------------------------- Restore Pipeline <-------------------------/...............................................> 17.12% ``` +自 TiDB v9.0.0 起，你可以通过指定参数 `--load-sys-table-physical` 在全新的集群上进行物理恢复系统表： + +```shell +tiup br restore full \ + --pd "${PD_IP}:2379" \ + --with-sys-table \ + --load-sys-table-physical \ + --storage "s3://${backup_collection_addr}/snapshot-${date}?access-key=${access-key}&secret-access-key=${secret-access-key}" \ + --ratelimit 128 \ + --log-file restorefull.log +``` + ## 恢复备份数据中指定库表的数据 br 命令行工具支持只恢复备份数据中指定库/表的局部数据。该功能在恢复过程中过滤掉不需要的数据，可以用于往 TiDB 集群上恢复指定库/表的数据。 From f6d74014f3766b46c67509b0cc1d5d914378732c Mon Sep 17 00:00:00 2001 From: Jianjun Liao <36503113+Leavrth@users.noreply.github.com> Date: Fri, 23 May 2025 12:15:46 +0800 Subject: [PATCH 4/7] Update br/br-snapshot-manual.md Co-authored-by: BornChanger <97348524+BornChanger@users.noreply.github.com> --- br/br-snapshot-manual.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index 89705a53e3f2..611234cb4eb7 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -134,7 +134,7 @@ tiup br restore full \ > **注意：** > -> 从 v9.0.0 起，当关闭 br 命令行工具参数 `--load-stats` 时，br 将不会在表 `mysql.stats_meta` 中更新恢复的表的相关信息。如果你想要在恢复完成后手动分析表，那么可以关闭这个参数。 +> 从 v9.0.0 起，当设置参数 `--load-stats` 为 false 时，br 将不会在表 `mysql.stats_meta` 中更新恢复的表的相关信息。你可以在恢复完成后手动执行 analyze table，更新相关统计信息。 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。 From d72d9714d4d3cf98af3b30f5b2b74a0ae5d90a0c Mon Sep 17 00:00:00 2001 From: Jianjun Liao Date: Wed, 28 May 2025 13:51:26 +0800 Subject: [PATCH 5/7] update the parameter Signed-off-by: Jianjun Liao --- br/br-snapshot-guide.md | 2 +- br/br-snapshot-manual.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/br/br-snapshot-guide.md b/br/br-snapshot-guide.md index 0a34e99d5ef8..2258ce3e4463 100644 --- a/br/br-snapshot-guide.md +++ b/br/br-snapshot-guide.md @@ -153,7 +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 开始，增加恢复参数 `--load-sys-table-physical` 支持物理恢复系统表。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。 +- `br` v9.0.0 开始，增加恢复参数 `--fast-load-sys-tables` 支持物理恢复系统表。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。 **可恢复的部分系统表**： diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index 89705a53e3f2..ba8bbce3883a 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -138,11 +138,11 @@ tiup br restore full \ 备份恢复功能在备份时，将统计信息通过 JSON 格式存储在 `backupmeta` 文件中。在恢复时，将 JSON 格式的统计信息导入到集群中。详情请参考 [LOAD STATS](/sql-statements/sql-statement-load-stats.md)。 -从 9.0.0 起，BR 引入参数 `--load-stats-physical`。当 br 命令行工具恢复在全新集群并且上下游表和分区的 ID 都能被复用时，通过设置 `--load-stats-physical` 会将统计信息相关表恢复到临时系统库 `__TiDB_BR_Temporary_mysql` 中，再通过 `RENAME TABLE` DDL 将恢复的统计信息表和 `mysql` 库下的表进行原子交换。示例如下： +从 9.0.0 起，BR 引入参数 `--fast-load-sys-tables`，默认开启。当 br 命令行工具恢复在全新集群并且上下游表和分区的 ID 都能被复用时（否则，将自动回退为逻辑导入统计信息数据），通过设置 `--fast-load-sys-tables` 会将统计信息相关表恢复到临时系统库 `__TiDB_BR_Temporary_mysql` 中，再通过 `RENAME TABLE` DDL 将恢复的统计信息表和 `mysql` 库下的表进行原子交换。示例如下： ```shell tiup br restore full \ ---storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log --load-stats --load-stats-physical +--storage local:///br_data/ --pd "${PD_IP}:2379" --log-file restore.log --load-stats --fast-load-sys-tables ``` ## 备份数据加密 @@ -197,13 +197,13 @@ Download&Ingest SST <----------------------------------------------------------- Restore Pipeline <-------------------------/...............................................> 17.12% ``` -自 TiDB v9.0.0 起，你可以通过指定参数 `--load-sys-table-physical` 在全新的集群上进行物理恢复系统表： +自 TiDB v9.0.0 起，你可以通过指定参数 `--fast-load-sys-tables` 在全新的集群上进行物理恢复系统表： ```shell tiup br restore full \ --pd "${PD_IP}:2379" \ --with-sys-table \ - --load-sys-table-physical \ + --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 From 44dd7c0559fa836774083b5a5183d6885a28f6ef Mon Sep 17 00:00:00 2001 From: Jianjun Liao Date: Wed, 28 May 2025 14:15:59 +0800 Subject: [PATCH 6/7] add notice Signed-off-by: Jianjun Liao --- br/br-snapshot-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/br/br-snapshot-guide.md b/br/br-snapshot-guide.md index 2258ce3e4463..50c03dc68797 100644 --- a/br/br-snapshot-guide.md +++ b/br/br-snapshot-guide.md @@ -153,7 +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` 库下的系统表进行原子交换。 +- `br` v9.0.0 开始，增加恢复参数 `--fast-load-sys-tables` 支持物理恢复系统表。通过 `RENAME TABLE` DDL 将 `__TiDB_BR_Temporary_mysql` 下的系统表和 `mysql` 库下的系统表进行原子交换。与通过 `REPLACE INTO` SQL 写入的逻辑恢复系统表方式不同，物理恢复系统表将会完全覆盖系统表中原有的数据。 **可恢复的部分系统表**： From adf4a3dfc76fa7ee383bdf8a491cabf166c85207 Mon Sep 17 00:00:00 2001 From: Jianjun Liao Date: Wed, 28 May 2025 14:56:16 +0800 Subject: [PATCH 7/7] add notice Signed-off-by: Jianjun Liao --- br/br-snapshot-manual.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/br/br-snapshot-manual.md b/br/br-snapshot-manual.md index 197fc0d89d41..0c9877cd6f77 100644 --- a/br/br-snapshot-manual.md +++ b/br/br-snapshot-manual.md @@ -209,6 +209,10 @@ tiup br restore full \ --log-file restorefull.log ``` +> **注意：** +> +> 与通过 `REPLACE INTO` SQL 写入的逻辑恢复系统表方式不同，物理恢复系统表将会完全覆盖系统表中原有的数据。 + ## 恢复备份数据中指定库表的数据 br 命令行工具支持只恢复备份数据中指定库/表的局部数据。该功能在恢复过程中过滤掉不需要的数据，可以用于往 TiDB 集群上恢复指定库/表的数据。