A newer version of this documentation is available.

View Latest

cbrestore

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

Syntax

The basic syntax is:

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

Where:

  • [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.

Description

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

Linux

/opt/couchbase/bin/cbrestore

Windows

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.

Options

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.

-b BUCKET_SOURCE, --bucket-source=BUCKET_SOURCE

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

-B BUCKET_DESTINATION, --bucket-destination=BUCKET_DESTINATION

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.

--from-date=FROM_DATE

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.

--to-date=TO_DATE

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.

--single-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:

    YYYY

    4-digit year

    MM

    2-digit month

    DD

    2-digit day

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

Table 2. cbrestore -x options
-x option Description

backoff_cap=10

Maximum back-off time during the rebalance period.

batch_max_bytes=400000

Transfer this # of bytes per batch.

batch_max_size=1000

Transfer this # of documents per batch.

cbb_max_mb=100000

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

conflict_resolve=1

By default, disable conflict resolution.

data_only=0

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

design_doc_only=0

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_retry=10

Max number of sequential retries if the transfer fails.

mcd_compatible=1

For value 0, display extended fields for stdout output.

nmv_retry=1

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

recv_min_bytes=4096

Amount of bytes for every TCP/IP batch transferred.

rehash=0

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.

report=5

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

report_full=2000

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

seqno=0

By default, start seqno from beginning.

try_xwm=1

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

uncompress=0

For value 1, restore data in uncompressed mode.

Examples

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 \
--bucket-source=default
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 http://10.3.1.10:8091 -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 http://10.3.1.10:8091 -x design_doc_only=1 \
-b bucket_one -B my_bucket

cbrestore ~/backup http://10.3.1.10:8091 -x design_doc_only=1 \
-b bucket_two -B my_bucket

Response

The following example response shows a successful restore.

transfer design doc only. bucket msgs will be skipped.
done

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 \
http://example.com:8091