This page provides an overview of the backup and restore features available in CockroachDB:
- Types of backup available in CockroachDB
- Backup and restore product support
- SQL statements for working with backups and restores
- Storage for backups
You can create full or incremental backups of a cluster, database, or table. Taking regular backups of your data is an operational best practice.
For an explanation of how a backup works, see Backup Architecture.
CockroachDB backup types
CockroachDB supports two types of backups:
- Managed-service backups: Cockroach Labs takes automated backups of CockroachDB Serverless and CockroachDB Dedicated clusters that are stored in Cockroach Labs' cloud storage. See Use Managed-Service Backups to learn more about the type and frequency of backups supported for both CockroachDB Cloud clusters.
- Customer-owned backups: You can take manual backups and store them in your cloud storage buckets using the
BACKUPstatement. Customer-owned backups are supported in CockroachDB Serverless, CockroachDB Dedicated, and CockroachDB Self-Hosted.
Backup and restore product support
This table outlines the level of product support for backup and restore features in CockroachDB. See each of the pages linked in the table for usage examples:
| Backup / Restore | Description | Product Support |
|---|---|---|
| Full backup | An un-replicated copy of your cluster, database, or table's data. A full backup is the base for any further backups. |
|
| Incremental backup | A copy of the changes in your data since the specified base backup (either a full backup or a full backup plus an incremental backup). |
|
| Scheduled backup | A schedule for periodic backups. |
|
| Backups with revision history | A backup with revision history allows you to back up every change made within the garbage collection period leading up to and including the given timestamp. |
|
| Point-in-time restore | A restore from an arbitrary point in time within the revision history of a backup. |
|
| Encrypted backup and restore | An encrypted backup using a KMS or passphrase. |
|
| Locality-aware backup and restore | A backup where each node writes files to the backup destination that matches the node locality configured at node startup. |
|
You can create schedules for periodic backups in CockroachDB. We recommend using scheduled backups to automate daily backups of your cluster.
Backup and restore SQL statements
The following table outlines SQL statements you can use to create, configure, pause, and show backup and restore jobs:
| SQL Statement | Description |
|---|---|
BACKUP |
Create full and incremental backups. |
SHOW JOBS |
Show a list of all running jobs or show the details of a specific job by its job ID. |
PAUSE JOB |
Pause a backup or restore job with its job ID. |
RESUME JOB |
Resume a backup or restore job with its job ID. |
CANCEL JOB |
Cancel a backup or restore job with its job ID. |
SHOW BACKUP |
Show a backup's details at the backup collection's storage location. |
RESTORE |
Restore full and incremental backups. |
ALTER BACKUP |
Add a new KMS encryption key to an encrypted backup. |
CREATE SCHEDULE FOR BACKUP |
Create a schedule for periodic backups. |
ALTER BACKUP SCHEDULE |
Alter an existing backup schedule. |
SHOW SCHEDULES |
View information on backup schedules. |
PAUSE SCHEDULES |
Pause backup schedules. |
RESUME SCHEDULES |
Resume paused backup schedules. |
DROP SCHEDULES |
Drop backup schedules. |
Backup storage
We recommend taking backups to cloud storage and enabling object locking to protect the validity of your backups. CockroachDB supports Amazon S3, Azure Storage, and Google Cloud Storage for backups. Read the following usage information:
- Example file URLs to form the URL that you pass to
BACKUPandRESTOREstatements. - Authentication to set up authentication to a cloud storage bucket and include those credentials in the URL.
For detail on additional cloud storage features CockroachDB supports:
- Prevent backups from being overwritten or deleted with immutable storage buckets.
- Set a specific storage class for your backups with Storage Class (AWS S3 only).
Cockroach Labs recommends enabling Egress Perimeter Controls on CockroachDB Dedicated clusters to mitigate the risk of data exfiltration when accessing external resources, such as cloud storage for change data capture or backup and restore operations. See Egress Perimeter Controls for detail and setup instructions.
Backup and restore observability
You can verify that your stored backups are restorable with backup validation. While a successful restore completely validates a backup, the validation tools offer a faster alternative and return an error message if a backup is not valid. There are three "levels" of verifying backups that give increasing validation coverage depending on the amount of runtime you want to invest in validating backups.
See the Backup Validation page for detail and examples.
You can track backup jobs using metrics that cover scheduled backups, status of running jobs, and details on completed or failed jobs. You can alert on these metrics via the Prometheus endpoint or the Datadog integration.
See the Backup and Restore Monitoring page for product availability and a list of the available metrics.
See also
- Considerations for using backup and restore
- Backup collections for details on how CockroachDB stores backups
Was this helpful?
