br Command-line Manual

This document describes the definition, components, and common options of br commands, and how to perform snapshot backup and restore, and log backup and point-in-time recovery (PITR) using br commands.

br command-line description

A br command consists of sub-commands, options, and parameters. A sub-command is the characters without - or --. An option is the characters that start with - or --. A parameter is the characters that immediately follow behind and are passed to the sub-command or the option.

The following is a complete br command:

br backup full --pd "${PD_IP}:2379" \
--storage "s3://backup-data/snapshot-202209081330/"

Explanations for the preceding command are as follows:

• backup: the sub-command of br.
• full: the sub-command of br backup.
• -s (or --storage): the option that specifies the path where the backup files are stored. "s3://backup-data/snapshot-202209081330/" is the parameter of -s.
• --pd: the option that specifies the PD service address. "${PD_IP}:2379" is the parameter of --pd.

Commands and sub-commands

A br command consists of multiple layers of sub-commands. Currently, br command-line tool has the following sub-commands:

• br backup: used to back up the data of the TiDB cluster.
• br log: used to start and manage log backup tasks.
• br restore: used to restore backup data of the TiDB cluster.

br backup and br restore include the following sub-commands:

• full: used to back up or restore all the cluster data.
• db: used to back up or restore a specified database of the cluster.
• table: used to back up or restore a single table in the specified database of the cluster.

Common options

• --pd: specifies the PD service address. For example, "${PD_IP}:2379".
• -s (or --storage): specifies the path where the backup files are stored. Amazon S3, Google Cloud Storage (GCS), Azure Blob Storage, and NFS are supported to store backup data. For more details, refer to URL format of backup storages.
• --ca: specifies the path to the trusted CA certificate in the PEM format.
• --cert: specifies the path to the SSL certificate in the PEM format.
• --key: specifies the path to the SSL certificate key in the PEM format.
• --status-addr: specifies the listening address through which br provides statistics to Prometheus.
• --concurrency: the number of concurrent tasks during the backup or restore.
• --compression：determines the compression algorithm used for generating backup files. It supports lz4, snappy, and zstd, with the default being zstd (usually no need to modify). For guidance on choosing different compression algorithms, refer to this document.
• --compression-level：sets the compression level corresponding to the chosen compression algorithm for backup. The default compression level for zstd is 3. In most cases there is no need to set this option.

Commands of full backup

To back up cluster data, run the br backup command. You can add the full or table sub-command to specify the scope of your backup operation: the whole cluster (full) or a single table (table).

• Back up TiDB cluster snapshots
• Back up a database
• Back up a table
• Back up multiple tables with table filter
• Encrypt snapshots

Commands of log backup

To start log backup and manage log backup tasks, run the br log command.

• Start a log backup task
• Query the backup status
• Pause and resume a log backup task
• Stop and restart a log backup task
• Clean up the backup data
• View the backup metadata

Commands of restoring backup data

To restore cluster data, run the br restore command. You can add the full, db, or table sub-command to specify the scope of your restore: the whole cluster (full), a single database (db), or a single table (table).

• Point-in-time recovery
• Restore cluster snapshots
• Restore a database
• Restore a table
• Restore multiple tables with table filter
• Restore encrypted snapshots