Backup and Restore Overview

CockroachDB is built to be fault-tolerant with automatic recovery, but sometimes disasters happen. Backup and restore is an important part of a robust disaster recovery plan. CockroachDB self-hosted clusters provide a range of backup and restore features.

• Backup and restore support
• Scheduled backups
• Backup jobs with locality requirements
• Backup and restore SQL statements
• Backup storage
• Backup and restore observability
• Video demo
• See also

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 a technical explanation of how a backup works, refer to the Backup Architecture page.

​

Backup and restore 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:

​

Scheduled backups

CockroachDB supports creating schedules for periodic backups. Scheduled backups ensure that the data to be backed up is protected from garbage collection until it has been successfully backed up. This active management of protected timestamps means that you can run scheduled backups at a cadence independent from the GC TTL of the data. For detail on scheduled backup features CockroachDB supports:

• Set up monitoring for the backup schedule
• View, pause, resume, or drop the schedule

​

Backup jobs with locality requirements

CockroachDB supports two backup features that use a node’s locality to determine how a backup job runs or where the backup data is stored:

• Locality-restricted backup execution: Specify a set of locality filters for a backup job in order to restrict the nodes that can participate in the backup process to that locality. This ensures that the backup job is executed by nodes that meet certain requirements, such as being located in a specific region or having access to a certain storage bucket.
• Locality-aware backup: Partition and store backup data in a way that is optimized for locality. When you run a locality-aware backup, nodes write backup data to the cloud storage bucket that is closest to the node locality configured at node startup.

​

Backup and restore SQL statements

The following table outlines SQL statements you can use to create, configure, pause, and show backup and restore jobs:

​

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 BACKUP and RESTORE statements.
• Authentication to set up authentication to a cloud storage bucket and include those credentials in the URL.

Cockroach Labs does not officially support S3-compatible storage solutions other than AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Some common compatibility issues may be fixed by adding the AWS_SKIP_CHECKSUM option to the S3 URLs. The Cockroach Labs Support team is available to offer assistance where possible. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer directly. Cockroach Labs does not officially support S3-compatible storage solutions other than AWS S3, Google Cloud Storage (GCS), and Azure Blob Storage. Some common compatibility issues may be fixed by adding the AWS_SKIP_CHECKSUM option to the S3 URLs.. The Cockroach Labs Support team is available to offer assistance where possible. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer. 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).
• Expire past backups from cloud storage

​

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.

​

Video demo

For practical examples of running backup and restore jobs, watch the following video:

​

See also

• Considerations for using backup and restore.
• Exclude a table’s data from backups
• Backup collections for details on how CockroachDB stores backups.
• Restoring backups across major versions of CockroachDB.