Backup and restore

pkg/backup/ implements BACKUP and RESTORE for clusters, databases, and tables. Backups produce SSTables and metadata in cloud storage; restores re-ingest those SSTables into a target cluster.

Anatomy of a backup

graph LR
  BackupSQL["BACKUP …"] --> Plan["backup planner"]
  Plan --> Job["BACKUP job (resumer)"]
  Job --> Spans["resolve spans + introduced spans"]
  Spans --> Workers["DistSQL backup processors"]
  Workers --> SST["build SSTs"]
  SST --> Cloud["pkg/cloud (S3, GCS, Azure, …)"]
  Job --> Manifest["BACKUP-MANIFEST"]
  Manifest --> Cloud

A full backup contains:

• A BACKUP-MANIFEST describing the timestamps, included objects, and file layout.
• A directory of data SSTs organized by span and [start, end) time range.
• A BACKUP-CHECKPOINT (incremental progress).
• Per-tenant subdirectories for multi-tenant clusters.

Incremental backups capture only [prev_end, new_end) MVCC ranges and reuse parent files. Locality-aware backups split files across storage prefixes by node locality.

Restore

Restore reverses the pipeline. Steps:

1. Read the manifest set (full + chained incrementals).
2. Rewrite descriptor IDs, type IDs, and zone configs to match the destination cluster.
3. Use AddSSTable requests through pkg/kv/bulk/ to ingest each SST into the right key range.
4. Run schema-change cleanups, recompute stats, and re-validate.

The SST ingestion path is the same one used by IMPORT and physical replication.

Sub-areas

Path	Purpose
pkg/backup/backuppb/	Proto types: manifest, spans, encryption info
pkg/backup/backupresolver/	Resolve user input to descriptor sets
pkg/backup/backupinfo/	Metadata IO
pkg/backup/backupencryption/	Backup-level encryption (separate from EAR)
pkg/backup/backupdest/	Destination URI resolution
pkg/backup/backuputils/	Shared helpers
pkg/backup/backupsink/	SST writer to cloud
pkg/backup/backupbase/	Base types
pkg/cloud/	The cloud-storage adapters used by both backup and changefeed

Cluster restore

A RESTORE FROM ... AS OF SYSTEM TIME ... of a full cluster brings back not just user data but system metadata (jobs, comments, role memberships, etc.). The restore job orchestrates this in stages, gating each on cluster version compatibility (pkg/clusterversion/).

Schedules

Backups can be scheduled with CREATE SCHEDULE FOR BACKUP ..., which plumbs through pkg/jobs/job_scheduler.go.

Protected timestamps

A backup must guarantee that the data it depends on is not GC'd while it's running. pkg/protectedts/ and pkg/jobs/jobsprotectedts/ install a record on the relevant ranges that prevents GC up to the backup's read timestamp.

Related pages

• Jobs — backup runs as a job.
• KV client — pkg/kv/bulk/ does the SST construction during restore.
• Storage — SST format on disk.
• features/cross-cluster-replication — the streaming cousin of full backup/restore.