Question

Backup & Restore（以下简称 BR）是 TiDB 分布式备份恢复的命令行工具，用于对 TiDB 集群进行数据备份和恢复。相比 dumpling 和 mydumper/loader，BR 更适合大数据量的场景。本文档介绍了 BR 的使用限制、工作原理、命令行描述、备份恢复用例以及最佳实践。

使用限制

• BR 只支持 TiDB v3.1 及以上版本。

• BR 支持在不同拓扑的集群上执行恢复，但恢复期间对在线业务影响很大，建议低峰期或者限速 (rate-limit) 执行恢复。

• BR 备份最好串行执行，否则不同备份任务之间会相互影响。

• BR 恢复到 TiCDC / Drainer 的上游集群时，恢复数据无法由 TiCDC / Drainer 同步到下游。

• BR 只支持在 new_collations_enabled_on_first_bootstrap 开关值相同的集群之间进行操作。这是因为 BR 仅备份 KV 数据。如果备份集群和恢复集群采用不同的排序规则，数据校验会不通过。所以恢复集群时，你需要确保 select VARIABLE_VALUE from mysql.tidb where VARIABLE_NAME='new_collation_enabled'; 语句的开关值查询结果与备份时的查询结果相一致，才可以进行恢复。

  • 对于 v3.1 集群，TiDB 尚未支持 new collation，因此可以认为 new collation 未打开

  • 对于 v4.0 集群，请通过 SELECT VARIABLE_VALUE FROM mysql.tidb WHERE VARIABLE_NAME='new_collation_enabled'; 查看 new collation 是否打开。

    例如，数据备份在 v3.1 集群。如果恢复到 v4.0 集群中，查询恢复集群的 new_collation_enabled 的值为 true，则说明创建恢复集群时打开了 new collation 支持的开关。此时恢复数据，可能会出错。

推荐部署配置

• 推荐 BR 部署在 PD 节点上。
• 推荐使用一块高性能 SSD 网盘，挂载到 BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。

注意：

如果没有挂载网盘或者使用其他共享存储，那么 BR 备份的数据会生成在各个 TiKV 节点上。由于 BR 只备份 leader 副本，所以各个节点预留的空间需要根据 leader size 来预估。 同时由于 v4.0 默认使用 leader count 进行平衡，所以会出现 leader size 差别大的问题，导致各个节点备份数据不均衡。

工作原理

BR 是分布式备份恢复的工具，它将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。更多信息请参阅备份恢复设计方案

备份文件类型

备份路径下会生成以下两种类型文件：

• SST 文件：存储 TiKV 备份下来的数据信息
• backupmeta 文件：存储本次备份的元信息，包括备份文件数、备份文件的 Key 区间、备份文件大小和备份文件 Hash (sha256) 值

SST 文件命名格式

SST 文件以 storeID_regionID_regionEpoch_keyHash_cf 的格式命名。格式名的解释如下：

• storeID：TiKV 节点编号
• regionID：Region 编号
• regionEpoch：Region 版本号
• keyHash：Range startKey 的 Hash (sha256) 值，确保唯一性
• cf：RocksDB 的 ColumnFamily（默认为 default 或 write）

使用方式

目前支持两种方式来运行备份恢复，分别是 SQL 和命令行工具。

通过 SQL

在 v4.0.2 及以上版本的 TiDB 中，已经可以支持通过 SQL 语句进行备份恢复，详见 Backup 语法 以及 Restore 语法

通过命令行工具

同时也支持命令行工具的方式。首先需要下载一个 BR 工具的 Binary，详见下载链接。

下面以命令行工具为例，介绍备份恢复的执行方式。

BR 命令行描述

一条 br 命令是由子命令、选项和参数组成的。子命令即不带 - 或者 -- 的字符。选项即以 - 或者 -- 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。

以下是一条完整的 br 命令行：

br backup full --pd "${PDIP}:2379" -s "local:///tmp/backup"

命令行各部分的解释如下：

• backup：br 的子命令
• full：backup 的子命令
• -s 或 --storage：备份保存的路径
• "local:///tmp/backup"：-s 的参数，保存的路径为各个 TiKV 节点本地磁盘的 /tmp/backup
• --pd：PD 服务地址
• "${PDIP}:2379"：--pd 的参数

注意：

在使用 local storage 的时候，备份数据会分散在各个节点的本地文件系统中。

不建议在生产环境中备份到本地磁盘，因为在日后恢复的时候，必须手动聚集这些数据才能完成恢复工作（见命令和子命令

BR 由多层命令组成。目前，BR 包含 backup、restore 和 version 三个子命令:

• br backup 用于备份 TiDB 集群
• br restore 用于恢复 TiDB 集群

以上三个子命令可能还包含这些子命令：

• full：可用于备份或恢复全部数据。
• db：可用于备份或恢复集群中的指定数据库。
• table：可用于备份或恢复集群指定数据库中的单张表。

常用选项

• --pd：用于连接的选项，表示 PD 服务地址，例如 "${PDIP}:2379"。
• -h/--help：获取所有命令和子命令的使用帮助。例如 br backup --help。
• -V (或 --version): 检查 BR 版本。
• --ca：指定 PEM 格式的受信任 CA 的证书文件路径。
• --cert：指定 PEM 格式的 SSL 证书文件路径。
• --key：指定 PEM 格式的 SSL 证书密钥文件路径。
• --status-addr：BR 向 Prometheus 提供统计数据的监听地址。

备份集群数据

使用 br backup 命令来备份集群数据。可选择添加 full 或 table 子命令来指定备份的范围：全部集群数据或单张表的数据。

如果 BR 的版本低于 v4.0.3，而且备份时间可能超过设定的 tikv_gc_life_time（默认 10m0s，即表示 10 分钟），需要手动将该参数调大。

例如，将 tikv_gc_life_time 调整为 720h：

mysql -h${TiDBIP} -P4000 -u${TIDB_USER} ${password_str} -Nse \
    "update mysql.tidb set variable_value='720h' where variable_name='tikv_gc_life_time'";

自 v4.0.3 起 BR 已经支持自适应 GC，无需手动调整 tikv_gc_life_time.

备份全部集群数据

要备份全部集群数据，可使用 br backup full 命令。该命令的使用帮助可以通过 br backup full -h 或 br backup full --help 来获取。

用例：将所有集群数据备份到各个 TiKV 节点的 /tmp/backup 路径，同时也会将备份的元信息文件 backupmeta 写到该路径下。

注意：

• 经测试，在全速备份的情况下，如果备份盘和服务盘不同，在线备份会让只读线上服务的 QPS 下降 15%~25% 左右。如果希望降低影响，请参考 --ratelimit 进行限速。

• 假如备份盘和服务盘相同，备份将会和服务争夺 I/O 资源，这可能会让只读线上服务的 QPS 骤降一半以上。请尽量禁止将在线服务的数据备份到 TiKV 的数据盘。

br backup full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 120 \
    --log-file backupfull.log

以上命令中，--ratelimit 选项限制了每个 TiKV 执行备份任务的速度上限（单位 MiB/s）。--log-file 选项指定把 BR 的 log 写到 backupfull.log 文件中。

备份期间有进度条在终端中显示。当进度条前进到 100% 时，说明备份已完成。在完成备份后，BR 为了确保数据安全性，还会校验备份数据。进度条效果如下：

br backup full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 120 \
    --log-file backupfull.log
Full Backup <---------/................................................> 17.12%.

备份单个数据库的数据

要备份集群中指定单个数据库的数据，可使用 br backup db 命令。同样可通过 br backup db -h 或 br backup db --help 来获取子命令 db 的使用帮助。

用例：将数据库 test 备份到各个 TiKV 节点的 /tmp/backup 路径，同时也会将备份的元信息文件 backupmeta 写到该路径下。

br backup db \
    --pd "${PDIP}:2379" \
    --db test \
    --storage "local:///tmp/backup" \
    --ratelimit 120 \
    --log-file backuptable.log

db 子命令的选项为 --db，用来指定数据库名。其他选项的含义与备份单张表的数据

要备份集群中指定单张表的数据，可使用 br backup table 命令。同样可通过 br backup table -h 或 br backup table --help 来获取子命令 table 的使用帮助。

用例：将表 test.usertable 备份到各个 TiKV 节点的 /tmp/backup 路径，同时也会将备份的元信息文件 backupmeta 写到该路径下。

br backup table \
    --pd "${PDIP}:2379" \
    --db test \
    --table usertable \
    --storage "local:///tmp/backup" \
    --ratelimit 120 \
    --log-file backuptable.log

table 子命令有 --db 和 --table 两个选项，分别用来指定数据库名和表名。其他选项的含义与使用表库过滤功能备份多张表的数据

如果你需要以更复杂的过滤条件来备份多个表，执行 br backup full 命令，并使用 --filter 或 -f 来指定表库过滤规则。

用例：以下命令将所有 db*.tbl* 形式的表格数据备份到每个 TiKV 节点上的 /tmp/backup 路径，并将 backupmeta 文件写入该路径。

br backup full \
    --pd "${PDIP}:2379" \
    --filter 'db*.tbl*' \
    --storage "local:///tmp/backup" \
    --ratelimit 120 \
    --log-file backupfull.log

备份数据到 Amazon S3 后端存储

如果备份的存储并不是在本地，而是在 Amazon 的 S3 后端存储，那么需要在 storage 子命令中指定 S3 的存储路径，并且赋予 BR 节点和 TiKV 节点访问 Amazon S3 的权限。

这里可以参照 AWS 官方文档在指定的 Region 区域中创建一个 S3 桶 Bucket，如果有需要，还可以参照 AWS 官方文档 在 Bucket 中创建一个文件夹 Folder。

将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 BR 节点，并且通过 BR 将权限传给 TiKV 节点。

export AWS_ACCESS_KEY_ID=${AccessKey}
export AWS_SECRET_ACCESS_KEY=${SecretKey}

在进行 BR 备份时，显示指定参数 --s3.region 和 --send-credentials-to-tikv, --s3.region 表示 S3 存储所在的区域，--send-credentials-to-tikv 表示将 S3 的访问权限传递给 TiKV 节点。

br backup full \
    --pd "${PDIP}:2379" \
    --storage "s3://${Bucket}/${Folder}" \
    --s3.region "${region}" \
    --send-credentials-to-tikv true \
    --log-file backuptable.log

增量备份

如果想要备份增量，只需要在备份的时候指定上一次的备份时间戳 --lastbackupts 即可。

注意增量备份有以下限制：

• 增量备份需要与前一次全量备份在不同的路径下
• GC safepoint 必须在 lastbackupts 之前

br backup full\
    --pd ${PDIP}:2379 \
    -s local:///home/tidb/backupdata/incr \
    --lastbackupts ${LAST_BACKUP_TS}

以上命令会备份 (LAST_BACKUP_TS, current PD timestamp] 之间的增量数据。

你可以使用 validate 指令获取上一次备份的时间戳，示例如下：

LAST_BACKUP_TS=`br validate decode --field="end-version" -s local:///home/tidb/backupdata`

示例备份的增量数据记录 (LAST_BACKUP_TS, current PD timestamp] 之间的数据变更，以及这段时间内的 DDL。在恢复的时候，BR 会先把所有 DDL 恢复，而后才会恢复数据。

Raw KV 备份（实验性功能）

警告：

Raw KV 备份功能还在实验中，没有经过完备的测试。暂时请避免在生产环境中使用该功能。

在某些使用场景下，TiKV 可能会独立于 TiDB 运行。考虑到这点，BR 也提供跳过 TiDB 层，直接备份 TiKV 中数据的功能：

br backup raw --pd $PD_ADDR \
    -s "local://$BACKUP_DIR" \
    --start 31 \
    --end 3130303030303030 \
    --format hex \
    --cf default

以上命令会备份 default CF 上 [0x31, 0x3130303030303030) 之间的所有键到 $BACKUP_DIR 去。

这里，--start 和 --end 的参数会先依照 --format 指定的方式解码，再被送到 TiKV 上去，目前支持以下解码方式：

• "raw"：不进行任何操作，将输入的字符串直接编码为二进制格式的键。
• "hex"：将输入的字符串视作十六进制数字。这是默认的编码方式。
• "escape"：对输入的字符串进行转义之后，再编码为二进制格式。

恢复集群数据

使用 br restore 命令来恢复备份数据。可选择添加 full、db 或 table 子命令来指定恢复操作的范围：全部集群数据、某个数据库或某张数据表。

注意：

如果使用本地存储，在恢复前必须将所有备份的 SST 文件复制到各个 TiKV 节点上 --storage 指定的目录下。

即使每个 TiKV 节点最后只需要读取部分 SST 文件，这些节点也需要有所有 SST 文件的完全访问权限。原因如下：

• 数据被复制到了多个 Peer 中。在读取 SST 文件时，这些文件必须要存在于所有 Peer 中。这与数据的备份不同，在备份时，只需从单个节点读取。
• 在数据恢复的时候，每个 Peer 分布的位置是随机的，事先并不知道哪个节点将读取哪个文件。

使用共享存储可以避免这些情况。例如，在本地路径上安装 NFS，或使用 S3。利用这些网络存储，各个节点都可以自动读取每个 SST 文件，此时上述注意事项不再适用。

恢复全部备份数据

要将全部备份数据恢复到集群中来，可使用 br restore full 命令。该命令的使用帮助可以通过 br restore full -h 或 br restore full --help 来获取。

用例：将 /tmp/backup 路径中的全部备份数据恢复到集群中。

br restore full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --ratelimit 128 \
    --log-file restorefull.log

以上命令中，--ratelimit 选项限制了每个 TiKV 执行恢复任务的速度上限（单位 MiB/s）。--log-file 选项指定把 BR 的 log 写到 restorefull.log 文件中。

恢复期间还有进度条会在终端中显示，当进度条前进到 100% 时，说明恢复已完成。在完成恢复后，BR 为了确保数据安全性，还会校验恢复数据。进度条效果如下：

br restore full \
    --pd "${PDIP}:2379" \
    --storage "local:///tmp/backup" \
    --log-file restorefull.log
Full Restore <---------/...............................................> 17.12%.

恢复单个数据库的数据

要将备份数据中的某个数据库恢复到集群中，可以使用 br restore db 命令。该命令的使用帮助可以通过 br restore db -h 或 br restore db --help 来获取。

用例：将 /tmp/backup 路径中备份数据中的某个数据库恢复到集群中。

br restore db \
    --pd "${PDIP}:2379" \
    --db "test" \
    --storage "local:///tmp/backup" \
    --log-file restorefull.log

以上命令中 --db 选项指定了需要恢复的数据库名字。其余选项的含义与恢复单张表的数据

要将备份数据中的某张数据表恢复到集群中，可以使用 br restore table 命令。该命令的使用帮助可通过 br restore table -h 或 br restore table --help 来获取。

用例：将 /tmp/backup 路径下的备份数据中的某个数据表恢复到集群中。

br restore table \
    --pd "${PDIP}:2379" \
    --db "test" \
    --table "usertable" \
    --storage "local:///tmp/backup" \
    --log-file restorefull.log

使用表库功能过滤恢复数据

如果你需要用复杂的过滤条件来恢复多个表，执行 br restore full 命令，并用 --filter 或 -f 指定使用表库过滤。

用例：以下命令将备份在 /tmp/backup 路径的表的子集恢复到集群中。

br restore full \
    --pd "${PDIP}:2379" \
    --filter 'db*.tbl*' \
    --storage "local:///tmp/backup" \
    --log-file restorefull.log

从 Amazon S3 后端存储恢复数据

如果需要恢复的数据并不是存储在本地，而是在 Amazon 的 S3 后端，那么需要在 storage 子命令中指定 S3 的存储路径，并且赋予 BR 节点和 TiKV 节点访问 Amazon S3 的权限。

将有权限访问该 S3 后端存储的账号的 SecretKey 和 AccessKey 作为环境变量传入 BR 节点，并且通过 BR 将权限传给 TiKV 节点。

export AWS_ACCESS_KEY_ID=${AccessKey}
export AWS_SECRET_ACCESS_KEY=${SecretKey}

在进行 BR 恢复时，显示指定参数 --s3.region 和 --send-credentials-to-tikv, --s3.region 表示 S3 存储所在的区域，--send-credentials-to-tikv 表示将 S3 的访问权限传递给 TiKV 节点。--storage参数中的 Bucket 和 Folder 分别代表需要恢复的数据所在的 S3 存储桶和文件夹。

br restore full \
    --pd "${PDIP}:2379" \
    --storage "s3://${Bucket}/${Folder}" \
    --s3.region "${region}" \
    --send-credentials-to-tikv=true \
    --log-file restorefull.log

以上命令中 --table 选项指定了需要恢复的表名。其余选项的含义与增量恢复

增量恢复的方法和使用 BR 进行全量恢复的方法并无差别。需要注意，恢复增量数据的时候，需要保证备份时指定的 last backup ts 之前备份的数据已经全部恢复到目标集群。

Raw KV 恢复（实验性功能）

警告：

Raw KV 恢复功能还在实验中，没有经过完备的测试。暂时请避免在生产环境中使用该功能。

和 在线恢复（实验性功能）

警告：

在线恢复功能还在实验中，没有经过完备的测试，同时还依赖 PD 的不稳定特性 Placement Rules。暂时请避免在生产环境中使用该功能。

在恢复的时候，写入过多的数据会影响在线集群的性能。为了尽量避免影响线上业务，BR 支持通过 Placement rules 隔离资源。让下载、导入 SST 的工作仅仅在指定的几个节点（下称“恢复节点”）上进行，具体操作如下：

1. 配置 PD，启动 Placement rules：

   echo "config set enable-placement-rules true" | pd-ctl

2. 编辑恢复节点 TiKV 的配置文件，在 server 一项中指定：

   [server]
   labels = { exclusive = "restore" }

3. 启动恢复节点的 TiKV，使用 BR 恢复备份的文件，和非在线恢复相比，这里只需要加上 --online 标志即可：

   br restore full \
       -s "local://$BACKUP_DIR" \
       --pd $PD_ADDR \
       --online

最佳实践

• 推荐在 -s 指定的备份路径上挂载一个共享存储，例如 NFS。这样能方便收集和管理备份文件。
• 在使用共享存储时，推荐使用高吞吐的存储硬件，因为存储的吞吐会限制备份或恢复的速度。
• 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。

更多最佳实践内容，参见 BR 备份与恢复场景示例。

备份和恢复示例

本示例展示如何对已有的集群数据进行备份和恢复操作。可以根据机器性能、配置、数据规模来预估一下备份和恢复的性能。

数据规模和机器配置

假设对 TiKV 集群中的 10 张表进行备份和恢复。每张表有 500 万行数据，数据总量为 35 GB。

MySQL [sbtest]> show tables;
+------------------+
| Tables_in_sbtest |
+------------------+
| sbtest1          |
| sbtest10         |
| sbtest2          |
| sbtest3          |
| sbtest4          |
| sbtest5          |
| sbtest6          |
| sbtest7          |
| sbtest8          |
| sbtest9          |
+------------------+

MySQL [sbtest]> select count(*) from sbtest1;
+----------+
| count(*) |
+----------+
|  5000000 |
+----------+
1 row in set (1.04 sec)

表结构如下：

CREATE TABLE `sbtest1` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `k` int(11) NOT NULL DEFAULT '0',
  `c` char(120) NOT NULL DEFAULT '',
  `pad` char(60) NOT NULL DEFAULT '',
  PRIMARY KEY (`id`),
  KEY `k_1` (`k`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin AUTO_INCREMENT=5138499

示例假设有 4 个 TiKV 节点，每个节点配置如下：

CPU	内存	磁盘	副本数
16 核	32 GB	SSD	3

备份示例

• 备份前需确认已将 GC 时间调长，确保备份期间不会因为数据丢失导致中断
• 备份前需确认 TiDB 集群没有执行 DDL 操作

执行以下命令对集群中的全部数据进行备份：

bin/br backup full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file backup.log

[INFO] [collector.go:165] ["Full backup summary: total backup ranges: 2, total success: 2, total failed: 0, total take(s): 0.00, total kv: 4, total size(Byte): 133, avg speed(Byte/s): 27293.78"] ["backup total regions"=2] ["backup checksum"=1.640969ms] ["backup fast checksum"=227.885µs]

恢复示例

恢复操作前，需确认待恢复的 TiKV 集群是全新的集群。

执行以下命令对全部数据进行恢复：

bin/br restore full -s local:///tmp/backup --pd "${PDIP}:2379" --log-file restore.log

[INFO] [collector.go:165] ["Full Restore summary: total restore tables: 1, total success: 1, total failed: 0, total take(s): 0.26, total kv: 20000, total size(MB): 10.98, avg speed(MB/s): 41.95"] ["restore files"=3] ["restore ranges"=2] ["split region"=0.562369381s] ["restore checksum"=36.072769ms]