Use Managed-Service Backups

On this page Carat arrow pointing down

This page describes how to use managed-service backups in CockroachDB Serverless and CockroachDB Dedicated clusters.

Managed-service backups are automated backups of CockroachDB Cloud clusters that are stored in Cockroach Labs' cloud storage.

Note:

In addition to managed-service backups, you can configure manual backups to your own storage bucket with customer-owned backups. Refer to the Take and Restore Customer-Owned Backups page.

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

To access your managed-service backups, select a cluster from the Clusters page, then click Backup and Restore in the Data section of the left-side navigation.

Select one of the following filters for your deployment:

Click on Backup and Restore in the Data section of the left-side navigation to access the Backup Recovery page.

Once a cluster is deleted, Cockroach Labs retains the full backups for 30 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.

Every backup will be stored entirely in a single region, which is chosen at random from the list of cluster regions at the time of cluster creation. This region will be used indefinitely to store backups.

Note:

You cannot restore a backup of a multi-region database into a single-region database.

Click on Backup and Restore in the Data section of the left-side navigation to access the Backup and Restore page.

Consider the following as you use managed-service backups:

  • By default, full backups are retained for 30 days, while incremental backups are retained for 7 days. However, if you delete the backup schedule manually or enable CMEK on the cluster, this will affect the availability of managed backups. Refer to the CockroachDB Cloud FAQs for more detail.
  • 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.
  • Every backup will be stored entirely in a single region, which is chosen at random from the list of cluster regions at the time of cluster creation. This region will be used indefinitely to store backups.
Note:

You cannot restore a backup of a multi-region database into a single-region database.

Backups tab

The Backups tab displays a list of your full and incremental cluster backups. Use the calendar drop-down to view all backups taken on a certain date.

For each backup, the following details display:

  • Data From: The date and time the backup was taken.
  • Type: Whether the backup is a full or incremental backup.
  • Expires In: The remaining number of days Cockroach Labs will retain the backup.
  • Databases: The number of databases included in the backup.

To restore a particular cluster backup, click Restore in the corresponding row.

Backup Recovery page

The Backup Recovery page displays a list of your full cluster backups. Use the calendar drop-down to view all backups taken on a certain date.

For each backup, the following details display:

  • Data From: The date and time the backup was taken.
  • Status: Whether the backup is In Progress or Complete.
  • Expires In: The remaining number of days Cockroach Labs will retain the backup.

Databases

To view the databases included in the backup, click the number in the Databases column on the cluster view of the Backups tab.

For each database in the backup, the following details display:

  • The Name of the database.
  • The number of Tables in the database.

    To view the tables in the database, click the number in the Tables column.

To restore a database, click Restore in the corresponding row.

Note:

If a database does not contain tables, it will not display in the Databases view.

Tables

To view the tables in a database, click the number in the Tables column on the Databases page.

For each table in the database, the Name of the table displays.

To restore a table, click Restore in the corresponding row.

Incomplete Backups

To view any failed or pending backups, click the Incomplete Backups tab on your cluster's Backup and Restore page.

For each incomplete backup, the following details display:

  • Started: The date and time the backup job began.
  • Duration: The amount of time the backup job ran for.
  • Status: The error code and message for failed backup jobs.
  • Description: The SQL command corresponding to the failed or pending backup job.

Ways to restore data

Users with the Org Administrator, Cluster Operator or Cluster Administrator roles can perform the following from the Console:

Additional ways to restore data:

Restore a cluster

Note:

This feature is in preview. This feature is subject to change. To share feedback and/or issues, contact Support.

Warning:

The restore completely erases all data in the destination cluster. All cluster data is replaced with the data from the backup. The destination cluster will be unavailable while the job is in progress.

This operation is disruptive and is to be performed with caution. Use the Principle of Least Privilege (PoLP) as a golden rule when to designing your system of privilege grants.

To restore a cluster:

  1. Find the cluster backup on the Backups tab.
  2. Click Restore for the cluster you want to restore.

    The Restore cluster module displays with backup details.

  3. Select the cluster to restore to. You can restore to: a) the same cluster or b) a different cluster. By default, the option shows the current cluster. The dropdown displays options to restore to a different cluster.

    Note:

    Only active clusters are displayed. You can perform a cross-cluster restore across clusters that belong to the same organization. Incompatible versions cannot be selected and restoring CockroachDB Dedicated to CockroachDB Serverless or vice versa does not work.

  4. Click Continue.

  5. Enter the name of the destination cluster.

  6. Once you have reviewed the restore details, click Restore.

    The Restore Jobs tab will show you the status of your restore and update when the restore job has been created successfully.

Restore a database

To restore a database:

  1. Find the cluster backup containing the database you want to restore, and click the number in the corresponding Databases column.
  2. In the Databases view, click Restore for the database you want to restore.

    The Restore database module displays with backup details.

  3. In the Restore to field, enter the name of the destination database.

    Note:

    Resolve any naming conflicts by using DROP or RENAME on the existing database. If you enter a unique name in the Restore to field, a new database will be created.

  4. Select any of the Dependency options to skip. You can:

    • Skip missing foreign keys, which will remove missing foreign key constraints (i.e., when the referenced table is not in the backup or is not being restored) before restoring.
    • Skip missing sequences, which will ignore sequence dependencies (i.e., the DEFAULT expression that uses the sequence).
    • Skip missing views, which will skip restoring views that cannot be restored because their dependencies are not being restored at the same time.
  5. Click Continue.

  6. Once you have reviewed the restore details, click Restore.

    When the restore job has been created successfully, you will be taken to the Restore Jobs tab, which will show you the status of your restore.

When the restore is complete, be sure to set any database-specific zone configurations and, if applicable, grant privileges.

Restore a table

To restore a table:

  1. Find the cluster backup containing the table you want to restore, and click the number in the corresponding Databases column.
  2. In the Databases view, find the database containing the table you want to restore, and click the number in the corresponding Tables column.

    The Tables view displays.

  3. Click Restore for the table you want to restore.

    The Restore table module displays with backup details.

  4. In the Restore to field, enter the name of the destination database.

    Note:

    If you enter the name of an existing database, the table will be restored into that existing database. To use the name of an existing database, first resolve any naming conflicts by using DROP or RENAME on the existing database. If you enter a unique name in the Restore to field, a new database will be created.

  5. Select any of the Dependency options to skip. You can:

    • Skip missing foreign keys, which will remove missing foreign key constraints (i.e., when the referenced table is not in the backup or is not being restored) before restoring.
    • Skip missing sequences, which will ignore sequence dependencies (i.e., the DEFAULT expression that uses the sequence).
    • Skip missing views, which will skip restoring views that cannot be restored because their dependencies are not being restored at the same time.
  6. Click Continue.

  7. Once you have reviewed the restore details, click Restore.

When the restore job has been created successfully, you will be taken to the Restore Jobs tab, which will show you the status of your restore.

Back up a self-hosted CockroachDB cluster and restore into a CockroachDB Cloud cluster

To back up a self-hosted CockroachDB cluster into a CockroachDB Cloud cluster:

  1. While connected to your self-hosted CockroachDB cluster, back up your databases and/or tables to an external location:

    icon/buttons/copy
    BACKUP DATABASE example_database INTO 'gs://{bucket name}/{path/to/backup}?AUTH=specified&CREDENTIALS={encoded key}';
    
    Warning:

    If you are backing up the data to AWS or GCP, use the specified option for the AUTH parameter, as CockroachDB Cloud will need the specified credentials upon RESTORE. For more information on authentication parameters to cloud storage providers, see Cloud Storage Authentication.

  2. Connect to your CockroachDB Cloud cluster:

    icon/buttons/copy
    cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
    

    icon/buttons/copy
    cockroach sql --url 'postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert='$HOME'/Library/CockroachCloud/certs/<cluster-name>-ca.crt'
    
    icon/buttons/copy
    cockroach sql --url "postgresql://<user>@<cluster-name>-<short-id>.<region>.cockroachlabs.cloud:26257/<database>?sslmode=verify-full&sslrootcert=$env:appdata\CockroachCloud\certs\$<cluster-name>-ca.crt"
    

    Where:

    • <user> is the SQL user. By default, this is your CockroachDB Cloud account username.
    • <cluster-name>-<short-id> is the short name of your cluster plus the short ID. For example, funny-skunk-3ab.
    • <cluster-id> is a unique string used to identify your cluster when downloading the CA certificate. For example, 12a3bcde-4fa5-6789-1234-56bc7890d123.
    • <region> is the region in which your cluster is running. If you have a multi-region cluster, you can choose any of the regions in which your cluster is running. For example, aws-us-east-1.
    • <database> is the name for your database. For example, defaultdb.

    You can find these settings in the Connection parameters tab of the Connection info dialog.

  3. Restore to your CockroachDB Cloud cluster.

    Use SHOW BACKUPS with your external location to find the backup's subdirectory:

    icon/buttons/copy
    SHOW BACKUPS IN 'gs://{bucket name}/{path/to/backup}?AUTH=specified&CREDENTIALS={encoded key}';
    
            path
    ------------------------
    2021/03/23-213101.37
    2021/03/24-172553.85
    2021/03/24-210532.53
    (3 rows)
    

    Use the subdirectory to specify the backup to restore:

    icon/buttons/copy
    RESTORE DATABASE example_database FROM '2021/03/23-213101.37' IN 'gs://{bucket name}/{path/to/backup}?AUTH=specified&CREDENTIALS={encoded key}';
    

Known limitations

  • For restoring a cluster:
    • Restoring a backup taken on cluster running a newer version of CockroachDB into a cluster that is on an earlier version does not work. See Restoring Backups Across Versions.
    • Restoring CockroachDB Dedicated to CockroachDB Serverless or vice versa does not work.
    • Restoring to a different cluster is disabled for CMEK clusters.
    • Restores on AWS that take longer than 36 hours may run into authentication errors due to expired credentials.
    • You can perform a cross-cluster restore across clusters that belong to the same organization. Cross-organization restores are not supported.

See tracking issue.

Troubleshooting

Resolve a database naming conflict

The databases you want to restore cannot have the same name as an existing database in the target cluster. Before you restore a database, verify that the database name is not already in use. To do this, connect to the target cluster with the CockroachDB SQL client and run the following:

icon/buttons/copy
> SHOW DATABASES;

If the database's name is already in use, either drop the existing database:

icon/buttons/copy
> DROP DATABASE example_database;

Or change the existing database's name:

icon/buttons/copy
> ALTER DATABASE example_database RENAME TO archived_example_database;

Resolve a table naming conflict

The table you want to restore cannot have the same name as an existing table in the target database. Before you restore a table, verify that the table name is not already in use. To do this, connect to the target cluster with the CockroachDB SQL client and run the following:

icon/buttons/copy
> SHOW TABLES FROM database_name;

If the table's name is already in use, either drop the existing table:

icon/buttons/copy
> DROP TABLE target_database.example_table;

Or change the existing table's name:

icon/buttons/copy
> ALTER TABLE target_database.example_table RENAME TO target_database.archived_example_table;

Restore a cluster

Find the cluster backup you want to restore, and click Restore.

Note:

CockroachDB Serverless does not support cross-cluster restores through the CockroachDB Cloud Console. If you need to restore data into a new or different cluster, use customer-owned backups or contact support.

Performing a restore will cause your cluster to be unavailable for the duration of the restore. All current data is deleted, and the cluster will be restored to the state it was in at the time of the backup. There are no automatic incremental backups, and no automatic database or table level backups.

You can manage your own backups, including incremental, database, and table level backups. To perform manual backups, you must configure either a userfile location or a cloud storage location.


Yes No
On this page

Yes No