You are viewing the documentation for a prerelease version.

Backup Service

    The Backup Service allows full and incremental data-backups to be scheduled, and also allows the scheduling of merges of previously made data-backups.


    The Backup Service supports the scheduling of full and incremental data backups, either for specific individual buckets, or for all buckets on the cluster. It also allows the scheduling of merges of previously made backups. Data to be backed up can also be selected by service: for example, the data for the Data and Index Services alone might be selected for backup, with no other service’s data included.

    The service — which is also referred to as cbbs (Couchbase Backup Service) — can be configured and administered by means of the Couchbase Web Console UI, the CLI, or the REST API.

    The Backup Service and cbbackupmgr

    The Backup Service’s underlying backup tasks are performed by cbbackupmgr, which can also be used independently, on the command line, to perform backups and merges. The Backup Service and cbbackupmgr (when the latter is used independently) have the following, principal differences:

    • Whereas the Backup Service allows backup, restore, and archiving to be configured for the local cluster, and also permits restore to be configured for a remote cluster; cbbackupmgr allows backup, restore, and archiving each to be configured either for the local or for a remote cluster.

    • Whereas cbbackupmgr allows backups, merges, and other related operations only to be executed individually, the Backup Service provides automated, recurrent execution of such operations.

    See cbbackupmgr, for more information.

    Note that both the Backup Service and cbbackupmgr allow full and incremental backups. Unlike the Backup Service, cbbackupmgr requires a new repository to be created for each new, full backup (successive cbbackupmgr backups to the same repository being incremental). Both allow incremental backups, once created, to be merged, and their data deduplicated. Both use the same backup archive structure; and allow the contents of backups to be listed, and specific documents to be searched for.

    Backup-Service Architecture

    The Backup Service has a leader-follower architecture. This means that one of the cluster’s Backup-Service nodes is elected by ns_server to be the leader; and is thereby made responsible for dispatching backup tasks; for handling the addition and removal of nodes from the Backup Service; for cleaning up orphaned tasks; and for ensuring that global storage-locations are accessible by all Backup-Service nodes.

    If the leader becomes unresponsive, or is lost due to failover, the Backup Service ceases operation; until a rebalance has been performed. During the course of this rebalance, ns_server elects a new leader, and the Backup Service resumes, using the surviving Backup-Service nodes.


    The Backup Service is automated through the scheduling of plans, defined by the administrator. A plan contains the following information:

    • The data of which services is to be backed up.

    • The schedule on which backups (or backups and merges) will be performed.

    • The type of task to be performed: this can either be one or more backups, or one or more backups and one or more merges. Backups can be full or incremental.


    A repository is a location that contains backed up data. The location must be accessible to all nodes in the cluster, and must be assigned a name that is unique across the cluster. A repository is defined with reference either to a specific bucket, or to all buckets on the cluster. Data from each specified bucket will be backed up in the specified repository.

    A repository is defined with reference to a specific plan. Once repository-definition is completed, backups (or backups and merges) are performed of the data in the specified bucket (or buckets), with the data being saved in the repository on the schedule specified in the plan.

    Inspecting and Restoring

    The Backup Service allows inspection to be performed on the history of backups made to a specific repository. Plans can be created, reviewed and deleted. Individual documents can be searched for, in respositories.

    Data from individual or selected backups within a repository can be restored to the cluster, to a specified bucket. Document keys and values can be filtered, to ensure that only a subset of the data is restored.

    Archiving and Importing

    If a repository no longer needs to be active (that is, with ongoing backups and merges continuing to occur), it can be archived: this means that the repository is still accessible, but no longer receives data backups.

    An archived repository can be deleted, so that the Backup Service no longer keeps track of it. Optionally, the data itself can be retained, on the local filesystem.

    A deleted repository whose data still exists can be imported back into the cluster, if required. Once imported, the repository can be read from, but no longer receives data backups.

    See Also

    For information on using the Backup Service by means of Couchbase Web Console, see Manage Backup and Restore. For reference pages on the Backup Service REST API, see Backup Service API. For information on the port numbers used by the Backup Service, see Couchbase Server Ports. For a list of audit events used by the Backup Service, see Audit Event Reference.