Backup and Restore Data

      Couchbase recommends a robust scheduled backup and retention time policy as part of an overall disaster recovery plan for production data.

      Couchbase Capella supports scheduled and on-demand backups of bucket data.

      Weekly Backup Schedule

      All buckets can have a Set Weekly Schedule for backing up. You can choose an incremental backup interval from several available hourly options. Alternatively, you can choose not to back up your buckets.

      Daily Backup Schedule

      From January 2023, the Set Daily Schedule bucket backup setting has been deprecated for new Capella users and databases. Therefore, Set Daily Schedule is not available for new clusters. We recommend you use Set Weekly Schedule. However, Set Daily Schedule is still supported indefinitely if you are a current user already using Set Daily Schedule on pre-existing databases.

      Per-Bucket Backups

      Capella supports scheduled and on-demand bucket backups on a per-bucket basis. You can schedule backups for each bucket during bucket creation and modify the schedule at any time as needed. You can also create on-demand backups as needed.

      Couchbase Capella uses its own backup utility. When a backup or restore job begins, Capella starts a separate compute instance that is dedicated to running the backup utility. As the backup utility runs in a separate instance and connects to the database over the cloud network, there is minimal impact on database performance. When a job finishes, the instance running the backup utility is decommissioned.

      What is not included in a backup:

      Type Description

      Point-in-time Snapshot of Database

      Capella does not support point-in-time snapshots of database data. While the data in a backup is per-item consistent, data items are written to the backup at slightly different times. The state of one item does not infer the state of another item.

      Database Settings

      For example, nodes, replication, networking, or database access.

      Bucket Backup Types

      Couchbase Capella supports Full backups and Incremental backups. Every Scheduled backup includes both backup types.

      Backup types are described as follows:

      Type Description

      Full Backup

      Full backups provide the best restore performance but take the most time to complete, require the most storage, and can be demanding on database resources. A Full backup includes all bucket data from the time the backup was created and can amount to about 40% of the size of the original dataset. Full backups are taken automatically at the start of every Scheduled backup series. You can also create Full backups on demand.

      Incremental Backup

      Capella creates an Incremental backup during every Scheduled backup series. Incremental backups depend on Full backups to be restored. Incremental backups include the data that has changed since the last Scheduled backup. They take less time and storage space to create than a Full backup.

      Scheduled Backup

      Every Scheduled backup series starts with a Full backup. Every subsequent backup during the set retention time period uses an Incremental backup. Scheduled backups reflect all the bucket data present when Capella automatically created the last Incremental backup in the series. By using both Full and Incremental backups, the Scheduled backups provide the best compromise between performance and required storage.

      Cost Optimized Retention Policy

      You can select a cost-optimized retention policy to manage backups, and provide a trade-off between total cost of ownership (TCO) and the recovery point objective (RPO). RPO is the maximum acceptable amount of data loss after an unplanned data-loss incident, expressed as time. The frequency of backups with incremental intervals that are retained across a timeframe impacts RPO.

      A cost-optimized retention policy enables you to save money at the expense of RPO. For example, where the retention of backups might be more costly than running the cluster itself. For the cost-optimized retention policy, the retention time is applied only to the monthly restore point, keeping all other backups for four weeks. This policy enables restoring from any backup within the last four weeks. Beyond this time, Capella retains only the monthly restore point.

      Weekly full backup scheduled cycles expire as follows:

      • Each weekly cycle expires after four weeks.

      • The last backup cycle of each monthly period expires at your Retention Time setting. Therefore, only the last backup cycle of each monthly period is retained for the retention time you select in the Set Weekly Schedule.

        For example, suppose you start backups at mid-calendar month, on March 15. The last backup cycle of the monthly period is in the week of April 15th, and not in the last week of March.
        For Set Weekly Schedule, a cycle is the weekly full backup and the incremental backups following it for that week. When the week ends, a new cycle starts.

      You are able to restore:

      • From any backup within the last four weeks, which has been backed up incrementally every so many hours, as per your preference.

      • The final backup cycle from the monthly period, from your chosen retention time.

      RPO intervals and retention time periods are as follows:

      RPO Interval Retention Time Period


      4 Weeks


      4 Weeks


      4 Weeks


      User-chosen retention time period [30 days to 5 years]

      Only the monthly restore point (RPO) is retained for the user-chosen time retention period. Others are retained for 30 days.

      Bucket Backup Retention

      Capella retains a bucket’s scheduled backups based on the Retention Time setting in the bucket’s Backup Schedule. Retention time is from 30 days to five years. After the retention time lapses, Capella schedules the backup for deletion.

      The Retention Time setting applies to all future backups for a bucket. Changes to this setting don’t affect previous backups.

      Capella retains on-demand backups for 30 days.

      Downloading Backups

      You can download on-demand backups or completed cycles of scheduled backups for storage or use outside Couchbase Capella. The request to create a download file is done in Capella. When the download file is ready, you are notified by email to copy the download URL from the Downloadable Backups in Capella.

      You can’t download a backup that’s over 5 TB.

      You can use the download URL to download the zip archive file using a browser or a utility like wget.

      Downloadable backups are supported for AWS, GCP, and Microsoft Azure cloud providers.

      A backup cycle is a Couchbase Capella concept. A cycle is a full backup, and any incremental backups that come after it in a scheduled backup. All backups in a cycle are stored in the same archive repository.

      Requesting a Download

      You can request to create a download file for an on-demand backup, or a completed series (a cycle) of scheduled weekly or daily backups. On-demand backups are available to download as soon as the backup is complete. Scheduled backups are available to download when the backup cycle is complete. For example, if you set a weekly schedule backup, the backup is available to download after one week.

      After you request a download, you are notified by email when the downloadable backup file is ready for download. You can then log into your Capella account and copy the download URL from the Downloadable Backups.

      You have up to 12 hours, from the time when the downloadable file is ready, to retrieve the download URL. When copied, you must start the download using the URL within 1 hour.

      For more information, see Download a Backup in the Capella UI.

      Using the Download

      You can store the backup download file as appropriate for your backup storage policies, or you can unzip the zip archive file and use the Couchbase Server cbbackupmgr utility. You can use this utility to view, examine, or restore the contents of the backup repository.

      For more information about the cbbackupmgr utility, see cbbackupmgr in Command Line Tools.

      As noted in the documentation, if you are running cbbackupmgr commands against Couchbase Capella databases with the database access credentials, there are a few cbbackupmgr disable options that must be used. These restrictions do not apply if you are running cbbackupmgr commands against your self-managed databases, using the downloaded backup archive.

      Downloadable Backup Costs

      As part of your Capella backup storage costs, you are charged for the storage that a downloadable backup file uses. Capella stores a downloadable backup file for approximately 24 hours before automatically deleting it.

      Using the download URL incurs data transfer charges.

      About the Zip Archive File

      A zip archive file is in the following format: {database name}-{bucket-name}-{type of backup}-{date of backup or date range of backup}.zip

      Where: {type of backup} is scheduled or on-demand.


      Backup Type Format





      When you unzip the downloaded file, its cbbackupmgr archive name is as follows: <path_to_current_directory>/< cbbackupmgr_archive_repository_name>

      For example:

      cbbackupmgr archive name: <path>/d77896f1-14d2-46d8-89f7-93ce6aaa6758

      cbbackupmgr archive repository name: d77896f1-14d2-46d8-89f7-93ce6aaa6758

      After you unzip the downloaded backup file (cbbackupmgr zip archive file), you can use the cbbackupmgr info command to view the backups.

      For example:

      cbbackupmgr info --archive <path>/d77896f1-14d2-46d8-89f7-93ce6aaa6758 --repo d77896f1-14d2-46d8-89f7-93ce6aaa6758

      See Also

      See the following pages for more information about creating, managing, and deleting bucket backups: