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:

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

Explanations for the preceding command are as follows:

  • backup: the sub-command of tiup br.
  • full: the sub-command of tiup 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 tiup br command consists of multiple layers of sub-commands. Currently, br command-line tool has the following sub-commands:

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

tiup br backup and tiup 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 URI Formats of External Storage Services.
  • --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 tiup 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).

Commands of log backup

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

Commands of restoring backup data

To restore cluster data, run the tiup 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).