Backup and Restore in CockroachDB Cloud Overview

On this page Carat arrow pointing down

CockroachDB is built to be fault-tolerant through automatic recovery, but unforeseen disasters can happen. Backup and restore is an important part of a resilient disaster recovery plan. CockroachDB Cloud clusters run routine managed-service backups to Cockroach Labs' cloud storage. Additionally, you can also manually create customer-owned backups using CockroachDB's backup features.

CockroachDB Cloud backups

CockroachDB Cloud clusters can run 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. This table outlines how frequently CockroachDB Cloud clusters run automated backups and the retention period for each type of backup:

Backup type Tier Frequency Retention
Full cluster Dedicated Daily 30 days
Serverless Hourly 30 days
Incremental cluster Dedicated Hourly 7 days
Serverless None Not applicable

You can interact with managed-service backups through the Backup and Restore menu in the Cloud Console. Refer to Use Managed-Service Backups for instructions on using the Cloud console to work with managed-service backups for both CockroachDB Cloud clusters.

Note:

Once a cluster is deleted, Cockroach Labs retains the full backups for 30 days and incremental backups for 7 days. The retained backups are not available for restore using the Cloud Console. To restore a backup from a deleted cluster, you must contact the Cockroach Labs Support team. If an organization is deleted, you will lose access to all of the managed-service backups that Cockroach Labs has taken of the cluster.

Customer-owned backups

You can take manual backups and store them in your cloud storage buckets using the BACKUP statement. Customer-owned backups are supported in CockroachDB Serverless and CockroachDB Dedicated. Refer to the Backup and restore support table for a list of the types of manual backups that are available.

Backup and restore support

Backup / Restore Description CockroachDB Cloud 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.
  • Managed-service backups in CockroachDB Serverless and CockroachDB Dedicated.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
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).
  • Managed-service backups in CockroachDB Dedicated.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
Scheduled backup A schedule for periodic backups.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
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.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
Point-in-time restore A restore from an arbitrary point in time within the revision history of a backup.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
Encrypted backup and restore An encrypted backup using a KMS or passphrase.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
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.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.
Locality-restricted backup execution A backup with the EXECUTION LOCALITY option restricts the nodes that can execute a backup job with a defined locality filter.
  • Customer-owned backups in CockroachDB Serverless and CockroachDB Dedicated.

Get started with customer-owned 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 Take and Restore Customer-Owned Backups page and the Video demo.

Scheduled backups

Tip:

We recommend using scheduled backups to automate daily backups of your cluster.

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:

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 BACKUP and RESTORE statements.
  • 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:

Note:

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.

Refer to 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. Depending on your CockroachDB Cloud deployment, you can track these metrics with:

  • Prometheus: Dedicated
  • Datadog: Dedicated
  • Cloud Console Metrics page: Serverless, Dedicated

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.
Note:

CockroachDB Serverless clusters operate with a different architecture compared to CockroachDB Self-Hosted and CockroachDB Dedicated clusters. These architectural differences have implications for how locality-aware backups can run. Serverless 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 Serverless 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 data domiciling requirements.

Video demo

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

See also


Yes No
On this page

Yes No