TiDB 日志备份与 PITR 命令行手册
本文介绍 TiDB 日志备份和 PITR (Point-in-time recovery) 命令行。
如果你想了解如何进行日志备份与 PITR,可以参考以下教程:
日志备份命令行介绍
你可以执行 tiup br log
命令来开启和管理日志备份任务:
tiup br log --help
backup stream log from TiDB/TiKV cluster
Usage:
br log [command]
Available Commands:
metadata get the metadata of log dir
pause pause a log backup task
resume resume a log backup task
start start a log backup task
status get status for the log backup task
stop stop a log backup task
truncate truncate the log data until sometime
各个子命令的作用如下:
tiup br log start
:启动一个日志备份任务tiup br log status
:查询日志备份任务状态tiup br log pause
:暂停日志备份任务tiup br log resume
:重启暂停的备份任务tiup br log stop
:停止备份任务,并删除任务元信息tiup br log truncate
:从备份存储中清理日志备份数据tiup br log metadata
:查询备份存储中备份数据的元信息
启动日志备份
执行 tiup br log start
命令,你可以在备份集群启动一个日志备份任务。该任务在 TiDB 集群持续地运行,及时地将 KV 变更日志保存到备份存储中。
执行 tiup br log start --help
命令可获取该子命令使用介绍:
tiup br log start --help
start a log backup task
Usage:
br log start [flags]
Flags:
-h, --help help for start
--start-ts string usually equals last full backupTS, used for backup log. Default value is current ts. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'.
--task-name string The task name for the backup log task.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
以上命令行示例只展示了常用的参数,这些参数作用如下:
--start-ts
:指定开始备份日志的起始时间点。如果未指定,备份程序选取当前时间作为start-ts
。task-name
:指定日志备份任务名。该名称也用于查询备份状态、暂停、重启和恢复备份任务等操作。ca
、cert
、key
:指定使用 mTLS 加密方式与 TiKV 和 PD 进行通讯。--pd
:指定备份集群的 PD 访问地址。br 命令行工具需要访问 PD,发起日志备份任务。--storage
:指定备份存储地址。日志备份支持以 Amazon S3、Google Cloud Storage (GCS)、Azure Blob Storage 为备份存储,以上命令以 S3 为示例。关于 URI 格式的详细信息,请参考外部存储服务的 URI 格式。
使用示例:
tiup br log start --task-name=pitr --pd="${PD_IP}:2379" \
--storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}"'
查询日志备份任务
执行 tiup br log status
命令,你可以查询日志备份任务状态。
执行 tiup br log status --help
命令可获取该子命令使用介绍:
tiup br log status --help
get status for the log backup task
Usage:
br log status [flags]
Flags:
-h, --help help for status
--json Print JSON as the output.
--task-name string The task name for backup stream log. If default, get status of all of tasks (default "*")
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
以上示例中,--task-name
为常用参数,它用来指定日志备份任务名。默认值为 *
,即显示全部任务。
使用示例:
tiup br log status --task-name=pitr --pd="${PD_IP}:2379"
命令输出如下:
● Total 1 Tasks.
> #1 <
name: pitr
status: ● NORMAL
start: 2022-07-14 20:08:03.268 +0800
end: 2090-11-18 22:07:45.624 +0800
storage: s3://backup-101/logbackup
speed(est.): 0.82 ops/s
checkpoint[global]: 2022-07-25 22:52:15.518 +0800; gap=2m52s
命令输出中的字段含义如下:
status
:任务状态,包括NORMAL
(正常)、ERROR
(异常)和PAUSE
(暂停)三种状态。start
:日志备份任务开始的时间,该值为备份任务启动时候指定的start-ts
。storage
:备份存储。speed
:日志备份任务的总 QPS(每秒备份的日志个数)。checkpoint [global]
:集群中早于该checkpoint
的数据都已经保存到备份存储,它也是备份数据可恢复的最近时间点。error [store]
:存储节点上的日志备份组件运行遇到的异常。
暂停和恢复日志备份任务
执行 tiup br log pause
命令,你可以暂停正在运行的日志备份任务。
执行 tiup br log pause --help
可获取该子命令使用介绍:
tiup br log pause --help
pause a log backup task
Usage:
br log pause [flags]
Flags:
--gc-ttl int the TTL (in seconds) that PD holds for BR's GC safepoint (default 86400)
-h, --help help for status
--task-name string The task name for backup stream log.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
使用示例:
tiup br log pause --task-name=pitr --pd="${PD_IP}:2379"
执行 tiup br log resume
命令,你可以恢复被暂停的日志备份任务。
执行 tiup br log resume --help
命令可获取该子命令使用介绍:
tiup br log resume --help
resume a log backup task
Usage:
br log resume [flags]
Flags:
-h, --help help for status
--task-name string The task name for backup stream log.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
暂停日志备份任务超过了 24 小时后,执行 tiup br log resume
会报错,提示备份数据丢失。处理方法请参考恢复日志备份任务失败。
使用示例:
tiup br log resume --task-name=pitr --pd="${PD_IP}:2379"
停止和重启日志备份任务
通过执行 tiup br log stop
命令,你可以停止正在进行的日志备份任务。停止的任务,可以通过 --storage
路径重新启动。
停止日志备份任务
执行 tiup br log stop
命令,可以停止日志备份任务,该命令会清理备份集群中的任务元信息。
执行 tiup br log stop --help
命令可获取该子命令使用介绍:
tiup br log stop --help
stop a log backup task
Usage:
br log stop [flags]
Flags:
-h, --help help for status
--task-name string The task name for the backup log task.
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
使用示例:
tiup br log stop --task-name=pitr --pd="${PD_IP}:2379"
重新启动备份任务
当使用 tiup br log stop
命令停止日志备份任务后,可在另一个 --storage
路径下重新创建一个新的日志备份任务,也可以在原来的 --storage
路径下执行 tiup br log start
命令重新启动日志备份任务。如果是在原来的 --storage
路径重启任务,需要注意:
- 重启备份任务的
--storage
参数需要与停止任务之前的参数相同。 - 此时不需要填入
--start-ts
参数,程序将自动从上次的备份进度点开始备份数据。 - 如果停止任务后的时间过长,多版本的数据已经被 GC,则在重启备份任务时会报错
BR:Backup:ErrBackupGCSafepointExceeded
,此时只能配置另外的日志路径来重新创建日志备份任务。
清理日志备份数据
执行 tiup br log truncate
命令,你可以从备份存储中删除过期或不再需要的备份日志数据。
执行 tiup br log truncate --help
命令可获取该子命令使用介绍:
tiup br log truncate --help
truncate the incremental log until sometime.
Usage:
br log truncate [flags]
Flags:
--dry-run Run the command but don't really delete the files.
-h, --help help for truncate
--until string Remove all backup data until this TS.(support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'.)
-y, --yes Skip all prompts and always execute the command.
Global Flags:
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
该命令只需要访问备份存储,不需要访问备份集群。此外,常用的参数如下:
--dry-run
:运行命令,但是不删除文件。--until
:早于该参数指定时间点的日志备份数据会被删除。建议使用快照备份的时间点作为该参数值。--storage
:指定备份存储地址。日志备份支持以 Amazon S3、Google Cloud Storage (GCS)、Azure Blob Storage 为备份存储。关于 URI 格式的详细信息,请参考外部存储服务的 URI 格式。
使用示例:
tiup br log truncate --until='2022-07-26 21:20:00+0800' \
--storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}'
该子命令运行后输出以下信息:
Reading Metadata... DONE; take = 277.911599ms
We are going to remove 9 files, until 2022-07-26 21:20:00.0000.
Sure? (y/N) y
Clearing data files... DONE; take = 43.504161ms, kv-count = 53, kv-size = 4573(4.573kB)
Removing metadata... DONE; take = 24.038962ms
查看备份数据元信息
执行 tiup br log metadata
命令,你可以查看备份存储中保存的日志备份的元信息,例如最早和最近的可恢复时间点。
执行 tiup br log metadata --help
命令可获取该子命令使用介绍:
tiup br log metadata --help
get the metadata of log backup storage
Usage:
br log metadata [flags]
Flags:
-h, --help help for metadata
Global Flags:
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
该命令只需要访问备份存储,不需要访问备份集群。
以上示例中,--storage
为常用参数,它用来指定备份存储地址。日志备份支持以 Amazon S3、Google Cloud Storage (GCS)、Azure Blob Storage 为备份存储。关于 URI 格式的详细信息,请参考外部存储服务的 URI 格式。
使用示例:
tiup br log metadata --storage='s3://backup-101/logbackup?access-key=${access-key}&secret-access-key=${secret-access-key}'
该子命令运行后输出以下信息:
[2022/07/25 23:02:57.236 +08:00] [INFO] [collector.go:69] ["log metadata"] [log-min-ts=434582449885806593] [log-min-date="2022-07-14 20:08:03.268 +0800"] [log-max-ts=434834300106964993] [log-max-date="2022-07-25 23:00:15.618 +0800"]
恢复到指定时间点 PITR
执行 tiup br restore point
命令,你可以在新集群上进行 PITR,或者只恢复日志备份数据。
执行 tiup br restore point --help
命令可获取该命令使用介绍:
tiup br restore point --help
restore data from log until specify commit timestamp
Usage:
br restore point [flags]
Flags:
--full-backup-storage string specify the backup full storage. fill it if want restore full backup before restore log.
-h, --help help for point
--restored-ts string the point of restore, used for log restore. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'
--start-ts string the start timestamp which log restore from. support TSO or datetime, e.g. '400036290571534337' or '2018-05-11 01:42:23+0800'
Global Flags:
--ca string CA certificate path for TLS connection
--cert string Certificate path for TLS connection
--key string Private key path for TLS connection
-u, --pd strings PD address (default [127.0.0.1:2379])
-s, --storage string specify the url where backup storage, eg, "s3://bucket/path/prefix"
以上示例只展示了常用的参数,这些参数作用如下:
--full-backup-storage
:指定快照(全量)备份的存储地址。如果你要使用 PITR,需要指定该参数,并选择恢复时间点之前最近的快照备份;如果只恢复日志备份数据,则不需要指定该参数。需要注意的是,第一次初始化恢复集群时,必须指定快照备份,快照备份支持以 Amazon S3、Google Cloud Storage (GCS)、Azure Blob Storage 为备份存储。关于 URI 格式的详细信息,请参考外部存储服务的 URI 格式。--restored-ts
:指定恢复到的时间点。如果没有指定该参数,则恢复到日志备份数据最后的可恢复时间点(备份数据的 checkpoint)。--start-ts
:指定日志备份恢复的起始时间点。如果你只恢复日志备份数据,不恢复快照备份,需要指定这个参数。ca
、cert
、key
:指定使用 mTLS 加密方式与 TiKV 和 PD 进行通讯。--pd
:指定恢复集群的 PD 访问地址。--storage
:指定备份存储地址。日志备份支持以 Amazon S3、Google Cloud Storage (GCS)、Azure Blob Storage 为备份存储。关于 URI 格式的详细信息,请参考外部存储服务的 URI 格式。
使用示例:
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-202205120000?access-key=${access-key}&secret-access-key=${secret-access-key}'
Full Restore <--------------------------------------------------------------------------------------------------------------------------------------------------------> 100.00%
*** ***["Full Restore success summary"] ****** [total-take=3.112928252s] [restore-data-size(after-compressed)=5.056kB] [Size=5056] [BackupTS=434693927394607136] [total-kv=4] [total-kv-size=290B] [average-speed=93.16B/s]
Restore Meta Files <--------------------------------------------------------------------------------------------------------------------------------------------------> 100.00%
Restore KV Files <----------------------------------------------------------------------------------------------------------------------------------------------------> 100.00%
"restore log success summary"] [total-take=192.955533ms] [restore-from=434693681289625602] [restore-to=434693753549881345] [total-kv-count=33] [total-size=21551]