(Deprecated) The cbrestore tool restores data backed up by cbbackup to a Couchbase cluster


      cbrestore [--username <user>] [--password <password>] [--ssl]
                  [--no-ssl-verify] [--cacert <path>] [--bucket-source <name>]
                  [--bucket-destination <bucket>] [--id <vbid>] [--key <regexp>]
                  [--from-date <start>] [--to-date <end>] [--add] [--dry-run]
                  [--verbose] [--silent] [--threads <num>] [--extra <options>]
                  [--help] backup_dir destination


      DEPRECATION WARNING: This tool has been deprecated please use cbbackupmgr instead.

      This tool restores data that was backed up using cbbackup the command will take some options as well as the backup_dir which is the path to the folder created by cbbackup that has to be restored and the destination which is the target cluster. The target cluster can be the same cluster from which the data was backed up or a different one. The tool does not create buckets so the buckets must exist in the target cluster.

      Conflict Resolution

      By default, when restoring from a backup using cbrestore, Couchbase Server will perform conflict resolution on all documents to be restored. The conflict resolution behavior is the same as cross data center replication (XDCR), which is detailed in Availability. This is so that documents which have been updated after the backup are not incorrectly overwritten by the restore process. As a result, after running the restore process, some documents may not match the content of the backup file. In certain cases where a document has been recently deleted on the cluster, the document may not be restored at all due to this conflict resolution. To restore the contents of a backup while overwriting current documents with the same key, pass the extra parameter conflict_resolve=0 as part of the cbrestore command. To ensure that only the documents contained in the backup exist in the bucket after performing the restore, flush the bucket prior to performing the restore.

      The tool can be found in the following directories:

      Operating system Location




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

      Mac OS X



      -u,--username <user>

      Specifies the username of the user executing the command. If you do not have a user account with permission to execute the command then it will fail with an unauthorized error.

      -p,--password <password>

      Specifies the password of the user executing the command. If you do not have a user account with permission to execute the command then it will fail with an unauthorized error.


      (Deprecated) Specifies that the connection should use SSL verification. If this flag is used then SSL will be used but the cluster certificate will not be verified by the Certificate Authority. This flag is deprecated and not recommended. If you wish to use SSL encryption it is recommended that you specify the cluster host name using either couchbases:// or https://. Each of these connection schemes will ensure that the connection is encrypted with SSL. You may then use either --no-ssl-verify or --cacert in order to customize how your SSL connection is set up.


      Specifies that SSL verification should be used but that verifying that the cluster certificate is valid should be skipped. Use of this flag is not recommended for production environments because it does not protect the user from a man-in-the-middle attack.

      --cacert <path>

      Specifies that the SSL connection should use the cacert provided when connecting to the cluster. This argument takes the path the certificate file as its value. This is the most secure way to connect to your cluster.

      -b,--bucket-source <bucket>

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

      -B,--bucket-destination <bucket>

      Specify the bucket to restore the data to in the target cluster. If not provided it will default to match the --bucket-source.

      -i,--id <vbid>

      Transfer only items that match a vBucket ID.

      -k,--key <regexp>

      Transfer only items with keys that match the given regular expression.

      --from-date <start>

      Restore data from the first specified backup in the format yyyy-mm-dd*. By default the starting point will be the first backup.

      --to-date <end>

      Restore data until the date specified as yyyy-mm-dd*. By default, all data collected is restored.


      Used to not override the existing items in the destination.


      When specified the tool will not transfer data but only validate parameters, files, connectivity and configuration.


      Verbose logging; more -v’s provide more verbosity. Max is -vvv


      Reduces the logging verbosity to only include errors.

      -t,--threads <num>

      Number of concurrent worker threads performing transfer, defaults to 1.

      -x,--extra <options>

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


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

      Table 1. cbbackup -x options
      -x options Description


      Maximum backoff 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 MiB.


      By default, disable conflict resolution.

      This option doesn’t work in Couchbase Server versions 4.0 and 4.1 but will be re-implemented in version 4.1.1 and in subsequent versions.


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


      For value 1, transfer only design documents from a backup file or cluster. Default: 0.

      Back up only design documents which include view and secondary index definitions from a cluster or bucket with the option design_doc_only=1. Restore only design documents with cbrestore -x design_doc_only=1.


      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 id’s of each item. This is required when transferring data between clusters with different number of partitions, such as when transferring data from an Mac OS X server to a non-Mac OS X cluster.


      Number batches transferred before updating progress bar in console.


      Number batches transferred before emitting progress information in console.


      By default, start from sequence number 0.


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


      For value 1, restore data in uncompressed mode.

      This option is unsupported. To create backups with compression, use cbbackupmgr, which is available for Couchbase Server Enterprise Edition only. See Backup.


      The most basic operation is to restore all the backed in our backup directory ~/backups. The directory will have a format as the one bellow:

      └── 2019-06-25T141453Z
          ├── 2019-06-25T141453Z-full
          │   └── bucket-beer-sample
          └── 2019-06-25T141553Z-diff
              └── bucket-beer-sample

      To restore we use the command bellow. Note that cbrestore does not create the buckets in the target cluster so in this case our cluster already has a bucket named beer-sample.

      $ cbrestore ~/backups -u Administrator \
        -p password

      When executed the command will restore all the data in the ~/backups directory into the target cluster, if any of the buckets in the backup do not exist in the target cluster cbrestore will return an error. We can restore one bucket to a different bucket using the -b and -B flags as follows.

      $ cbrestore ~/backups -u Administrator \
        -p password -b beer-sample -B new-bucket

      This will restore the backed up data for beer-sample into the bucket new-bucket in the target cluster. If the backup contains multiple buckets we can restore only one by using the -b flag.

      The restore also has the ability to select only a subset of the backups to be restored. If the backup directory contained 4 backup such as:

      └── 2019-06-25T141453Z
          ├── 2019-06-25T141453Z-full
          │   └── bucket-beer-sample
          ├── 2019-06-26T141553Z-diff
          │    └── bucket-beer-sample
          ├── 2019-06-27T151453Z-full
          │   └── bucket-beer-sample
          └── 2019-06-28T161553Z-diff
              └── bucket-beer-sample

      Then we can restore only the first two by using the following command:

      $ cbrestore ~/backups -u Administrator \
        -p password -b beer-sample --from-date 2019-06-25 --to-date 2019-06-27

      The tool also gives the capability of filtering documents based on keys, giving a regular expression to the -k flag will result in only documents that have keys that match the expression being restored. An example can be sen bellow

      $ cbrestore ~/backups -u Administrator \
       -p password -b default --k '^user:.*'

      The command above will only restore documents with keys that have the prefix 'user:'.


      Couchbase Server on Mac OS X uses a different number of configured vBuckets than Linux and Windows installations. Because of this, restoring to Mac OS X from a Linux or Windows backup or restoring to Linux/Windows from a Mac OS X backup requires the rehash=1 option.

      To backup the data (from any operating system), use the standard cbbackup tool and options.

      To restore the data to a cluster with a different operating system, connect to the 8091 port, and use the rehash=1 option to rehash the information and distribute the data to the appropriate node within the cluster. rehash=1 rehashes the partition IDs of each item. This is required when transferring data between clusters with a different number of partitions, such as when transferring data from a Mac OS X cluster to a non-Mac OS X cluster.

      cbrestore /path/to/backup -u [username] -p [password]
        -x rehash=1
        --bucket-source [my_bucket]
        --bucket-destination [my_bucket]gen_docs couchbase-cli-backup-service.adoc 1
      If you backed up multiple buckets from Mac OS X and are restoring to either Linux or Windows, each bucket must be restored individually.