CockroachDB Cloud backups
CockroachDB Cloud clusters can run two types of backups:- Automated managed backups
- Manual self-managed backups
Managed backups
are automated backups of CockroachDB Cloud clusters that are stored by Cockroach Labs in cloud storage. By default, Cockroach Labs takes and retains managed backups in all Cloud clusters. In Standard and Advanced clusters, you can adjust the default managed backup settings to meet your organization’s disaster recovery requirements. For details on the available settings for each cluster tier, refer to . You can view and configure managed backups through the Backup and Restore menu in the Cloud Console and with the .When a cluster is deleted, Cockroach Labs will retain the managed backups for for the , after which the backups will be deleted.If a customer’s agreement with Cockroach Labs has terminated, all managed backups will be retained for a maximum of 30 days and then deleted. If a backup’s retention time was set to less than 30 days, Cockroach Labs will retain the managed backups for the configured retention time, after which the backups will be deleted.To restore a backup from a deleted cluster, you must contact the .
Self-managed backups
You can take manual backups and store them in your using the statement. Self-managed backups are supported in all CockroachDB Cloud products. For a list of backup features that are available, refer to the following section Get started with self-managed backups.Get started with self-managed backups
The following sections outline some of the features and resources for taking backups to your own storage bucket. For more practical examples, refer to the page and the Video demo. You can run the following types of self-managed backups:- : An un-replicated copy of your cluster, database, or table’s data. A full backup is the base for any further backups.
- : 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).
- : A schedule for periodic backups.
- : 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.
- : A restore from an arbitrary point in time within the revision history of a backup.
- : An encrypted backup using a KMS or passphrase.
- : A backup where each node writes files to the backup destination that matches the node locality configured at node startup.
- : A backup with the
EXECUTION LOCALITYoption restricts the nodes that can execute a backup job with a defined locality filter.
Scheduled backups
CockroachDB supports . 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 means that you can run scheduled backups at a cadence independent from the of the data. For detail on scheduled backup features CockroachDB supports:- , , , or the schedule.
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 |
|---|---|
| Create full and incremental backups. | |
Show a list of all running jobs or show the details of a specific job by its job ID. | |
Pause a backup or restore job with its job ID. | |
Resume a backup or restore job with its job ID. | |
Cancel a backup or restore job with its job ID. | |
| Show a backup’s details at the storage location. | |
| Restore full and incremental backups. | |
| Add a new to an encrypted backup. | |
| Create a schedule for periodic backups. | |
| Alter an existing backup schedule. | |
| View information on backup schedules. | |
| Pause backup schedules. | |
| Resume paused backup schedules. | |
| Drop backup schedules. |
Backup storage
We recommend taking backups to 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:- to form the URL that you pass to
BACKUPandRESTOREstatements. - 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 is available to offer assistance where possible. If you encounter issues when using unsupported S3-compatible storage, drivers, or frameworks, contact the maintainer directly.- Prevent backups from being overwritten or deleted with .
- Set a specific storage class for your backups with .
- from cloud storage.
Cockroach Labs recommends enabling Egress Perimeter Controls on CockroachDB Advanced 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 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. Refer to the 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. Depending on your CockroachDB Cloud deployment, you can track these metrics with:| CockroachDB Standard | CockroachDB Advanced | CockroachDB Basic | |
|---|---|---|---|
| ✔ | ✔ | ✔ | |
| ✔ | ✔ | ||
| ✔ | ✔ |
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:- : 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.
- : 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 bucket that is closest to the node locality configured at .
CockroachDB Basic and Standard clusters operate with a different architecture compared to CockroachDB self-hosted and CockroachDB Advanced clusters. These architectural differences have implications for how locality-aware backups can run. Basic and Standard clusters will scale resources depending on whether they are actively in use, which means that it is less likely to have a SQL pod available in every locality. As a result, your cluster may not have a SQL pod in the locality where the data resides, which can lead to the cluster uploading that data to a storage bucket in a locality where you do have active SQL pods. You should consider this as you plan a backup strategy that must comply with requirements.
Video demo
For practical examples of running backup and restore jobs, watch the following video:See also
- Considerations for using and .
- for details on how CockroachDB stores backups.
- across major versions of CockroachDB.