BR (Backup & Restore)

BR is the CLI tool and library used to back up and restore TiDB clusters and to ship CDC log streams. It is co-located in this monorepo because it shares the table codec, region routing, and schema model with the SQL server.

Source

• CLI: br/cmd/br/ (entry: br/cmd/br/main.go).
• Library: br/pkg/.
• Build: make build_br → bin/br.
• Top-level docs: br/README.md.
• Compatibility tests: br/compatibility/.

Directory layout

br/
├── cmd/br/                 # CLI: cobra commands (backup, restore, stream, debug, …)
├── pkg/
│   ├── task/               # Top-level command logic
│   ├── backup/             # Backup pipeline (region scan, gRPC to TiKV)
│   ├── restore/            # Restore pipeline
│   ├── stream/             # Log backup (CDC) and PITR stream
│   ├── streamhelper/       # Helpers for log streams
│   ├── checkpoint/         # Resumable checkpoints
│   ├── checksum/           # Cross-cluster checksum verification
│   ├── conn/               # Cluster connection (TiKV/PD/TiDB)
│   ├── encryption/         # Encrypted backup
│   ├── kms/                # KMS integration for encryption
│   ├── pdutil/             # PD wrapper (scheduler suspension during backup)
│   ├── glue/               # Pluggable "glue" between BR and a TiDB stack
│   ├── gluetidb/           # Glue impl backed by an in-process TiDB
│   ├── gluetikv/           # Glue impl talking only to TiKV
│   ├── metautil/           # Metadata read/write
│   ├── rtree/              # Range tree for tracking imported regions
│   ├── registry/           # Restore registry (in-progress restores)
│   ├── summary/            # Per-task summary printer
│   ├── version/            # Version compatibility checks
│   ├── trace/              # Tracing helpers
│   ├── utils/, utiltest/   # Misc
│   └── ...
├── tests/                  # Integration tests (sh-driven)
└── docker-compose.yaml     # Local cluster for end-to-end testing

Key abstractions

Type	File	Purpose
task.BackupConfig, task.RestoreConfig	br/pkg/task/	Top-level command configurations.
backup.Client	br/pkg/backup/client.go	Coordinates a backup run across TiKV peers.
restore.Client	br/pkg/restore/client.go	Drives a restore.
stream.Client	br/pkg/stream/	Log backup / PITR.
glue.Glue	br/pkg/glue/	Pluggable interface for opening a TiDB session, fetching schema, executing DDL.
gluetidb.Glue, gluetikv.Glue	br/pkg/gluetidb/, br/pkg/gluetikv/	Glue implementations. Tidb glue runs an in-process TiDB; tikv glue avoids it.
metautil.MetaWriter/MetaReader	br/pkg/metautil/	Read/write the backup metadata file.

How a backup runs

graph TD
  cli[br backup full ...] --> task[task.RunBackup]
  task --> conn[Connect to PD/TiKV]
  task --> glue[Open TiDB glue]
  glue --> schema[Read infoschema, stats]
  task --> sched[Suspend PD schedulers]
  task --> stream[Stream backups from TiKV peers]
  stream --> rtree[rtree of done ranges]
  rtree --> meta[metautil writer]
  meta --> store[External storage<br/>S3 / GCS / Azure / local]
  task --> resume[PD scheduler resume]

1. Plan: BR resolves the database/table set to back up. It uses the glue to read TiDB's infoschema for table layouts.
2. Suspend schedulers: pdutil temporarily pauses certain PD schedulers so regions don't move during the backup.
3. Stream from TiKV: backup.Client opens gRPC backup streams to each TiKV peer covering the relevant key ranges. Each peer writes its SST files into the configured external storage (S3/GCS/Azure/local).
4. Track progress: a rtree.RangeTree keeps the union of completed ranges; checkpointing in pkg/checkpoint/ allows resuming after a crash.
5. Write metadata: metautil.MetaWriter produces backupmeta, listing every SST file, its checksum, the schema, and stats.
6. Resume schedulers and exit.

How a restore runs

1. Read metadata: metautil.MetaReader parses backupmeta.
2. Pre-check: version package verifies cluster compatibility.
3. Restore schema: glue creates databases/tables. For some operations BR runs the DDL through the in-process TiDB (gluetidb.Glue), letting the DDL framework drive online changes.
4. Ingest SST files: restore.Client issues IngestSST calls to each TiKV peer; pkg/lightning/backend/local/ is reused for the SST building pipeline (Lightning shares this code).
5. Re-build statistics: stats from the backup are restored into mysql.stats_*.
6. Verify: optional checksum step confirms restored data matches the source.

Log backup and PITR

br/pkg/stream/ and br/pkg/streamhelper/ implement log backup. TiKV ships continuous Raft log streams to external storage; BR can replay those onto a base full backup to reach any point-in-time within the retention window. br stream start, br stream stop, and br restore point are the user-visible entry points.

Encryption

br/pkg/encryption/ plus br/pkg/kms/ implement encrypted backup with keys from AWS KMS, GCP KMS, Azure Key Vault, or a static master key. The encryption is at-rest on the external storage; data in transit is the TiKV gRPC stream which can also be TLS-secured.

Integration with this repo

• BR uses pkg/parser/ to parse stored SQL (e.g., when restoring views).
• BR uses pkg/tablecodec/ to compute correct key ranges per table.
• BR shares pkg/lightning/backend/local/ and pkg/ingestor/ for SST production and ingestion paths.
• The SQL-level entry points BACKUP, RESTORE, SHOW BACKUPS, SHOW RESTORES in pkg/executor/brie.go invoke BR as a library inside the TiDB server process.

Tests

• br/tests/ contains shell-driven integration tests that spin up TiUP playgrounds and exercise backup/restore against real clusters.
• Compatibility tests under br/compatibility/ run BR built from this branch against older TiDB clusters.
• Unit tests live next to each pkg/.

Building and running locally

make build_br
./bin/br backup full \
  --pd 127.0.0.1:2379 \
  --storage local:///tmp/backup \
  --log-file /tmp/br_backup.log

Full quick-start instructions and TiUP-based examples are in br/README.md.