A newer version of this documentation is available.

View Latest


The cbrestore tool restores data from a file to an entire cluster or a single bucket in the cluster.


The basic syntax is:

cbrestore [options] [backup-dir] [destination]


  • [options]: Command options for cbrestore.

  • [backup-dir]: The backup directory for the source data created by cbbackup when performing the backup.

  • [destination]: This is a bucket in an existing cluster used as the destination bucket for the restored information. If you are restoring data to a single node in a cluster, provide the hostname and port of the node, If you are restoring an entire bucket, provide the URL of one of the nodes within the cluster. Be sure to create the destination bucket before restoring the data.


Items that had been written to file on disk are restored to RAM.

The cbbackup, cbrestore, and cbtransfer tools do not communicate with external IP addresses for server nodes outside of a cluster. Backup, restore, or transfer operations are performed on data from a node within a Couchbase cluster. They only communicate with nodes from a node list obtained within a cluster. If you install Couchbase Server with a default IP address, you cannot use an external hostname to access it.

The tool is in the following locations:

Operating system Location




C:\Program Files\Couchbase\Server\bin\cbrestore

Mac OS X

/Applications/Couchbase Server.app/Contents/Resources/couchbase-core/bin/cbrestore

Be sure to create the destination bucket before restoring the data.


The following are the command options:

Table 1. cbrestore options
Option Description

-h, --help

Command line help.

-a, --add

Used to not overwrite existing items in the destination. Use add instead of set.


Single named bucket from the backup directory to restore. If the backup directory only contains a single bucket, then that bucket is automatically used.


When --bucket-source is specified, overrides the destination bucket name. This allows you to restore to a different bucket and defaults to the same as the bucket-source.


Restore data from the date specified as yyyy-mm-dd *. By default, all data from the very beginning is restored.

The updated tool adds new options to support partial restore operations. The tool still supports the existing options for full restores.


Restore data until the date specified as yyyy-mm-dd*. By default, all data collected is restored. The updated tool adds new options to support partial restore operations. The tool still supports the existing options for full restores.

-i ID, --id=ID

Transfer only items that match a vbucket ID.

-k KEY, --key=KEY

Transfer only items with keys that match a regexp.

-m MODE, --mode=MODE

-n, --dry-run

No actual transfer. Just validate parameters, files, connectivity, and configurations.

-u USERNAME, --username=USERNAME

REST username for source cluster or server node.

-p PASSWORD, --password=PASSWORD

REST password for cluster or server node.


Use a single server node from the source only, not all server nodes from the entire cluster. This single server node is defined by the source URL.

-t THREADS, --threads=THREADS

Number of concurrent workers threads performing the transfer.

-v, --verbose

Verbose logging. More v’s provide more verbosity. Max: -vvv.

-x EXTRA, --extra=EXTRA

Provide extra, uncommon configuration parameters. Comma-separated key=val(key-val)* pairs.

  • The format of the DATE specification is YYYY-MM-DD, where:


    4-digit year


    2-digit month


    2-digit day

The following are extra, specialized command options with the cbrestore -x parameter.

Table 2. cbrestore -x options
-x option Description


Maximum back-off time during the rebalance period.


Transfer this # of bytes per batch.


Transfer this # of documents per batch.


Split backup file on destination cluster if it exceeds the MB.


By default, disable conflict resolution.


For value 1, transfer only data from a backup file or cluster.


The documents are restored from a backup file (created with the cbbackup) tool. For value 1, transfer only design documents from a backup file or cluster. Default: 0.


Max number of sequential retries if the transfer fails.


For value 0, display extended fields for stdout output.


0 or 1, where 1 retries transfer after a NOT_MY_VBUCKET message. Default: 1.


Amount of bytes for every TCP/IP batch transferred.


For value 1, rehash the partition IDs of each item as it is required when transferring data between clusters with the different number of partitions; for example, when transferring data from an Mac OS X server to a non-Mac OS X cluster.


Number batches transferred before updating the progress bar in the console.


Number batches transferred before emitting the progress information in the console.


By default, start seqno from beginning.


Transfer documents with metadata. Default: 1. The value of 0 is used only when transferring from 1.8.x to 1.8.x.


For value 1, restore data in uncompressed mode.


The following are syntax examples:

cbrestore /backups/backup-42 http://HOST:8091 \
--bucket-source=default --from-date=2014-01-20 --to-date=2014-03-31
cbrestore /backups/backup-42 couchbase://HOST:8091 \
cbrestore /backups/backup-42 memcached://HOST:11211 \
--bucket-source=sessions --bucket-destination=sessions2

Example for restoring design documents

The following example restores design documents from the backup file, ~/backup/a_bucket, to the destination bucket, my_bucket, in a cluster.

cbrestore ~/backup -x \
design_doc_only=1 -b a_bucket -B my_bucket

If multiple source buckets were backed up, this command must be performed multiple times. In the following example, a cluster with two data buckets is backed up and has the following backup files:

  • ~/backup/bucket_one/design.json

  • ~/backup/bucket_two/design.jsonT

The following command restores the design documents in both backup files to a bucket in a cluster named my_bucket.

cbrestore ~/backup -x design_doc_only=1 \
-b bucket_one -B my_bucket

cbrestore ~/backup -x design_doc_only=1 \
-b bucket_two -B my_bucket


The following example response shows a successful restore.

transfer design doc only. bucket msgs will be skipped.

Example for restoring data incrementally

The following example requests a restoration of data backed up between August 1, 2014, and August 3, 2014. The ‑b option specifies the name of the bucket to restore from the backup file, and the ‑B option specifies the name of the destination bucket in the cluster.

cbrestore -b source-bucket -B destination-bucket \
--from-date=2014-08-01 --to-date=2014-08-03 /backups/backup-1 \