When restoring a backup, you have to select the appropriate restore sequence based on the type of restore you are performing. There are a number of methods of restoring your cluster:
Restoring a cluster to a previous state, to the same cluster
This method should be used when you are restoring information to an identical cluster, or directly back to the cluster form which the backup was made. The cluster will need to be identically configured, with the same number of nodes and identical IP addresses to the cluster at the point when it was backed up.
For advice on using this method, see Section 18.104.22.168, “Restoring to the same cluster”.
Restoring a cluster to a previous state, to a different cluster
If your cluster environment has changed in any way for example changes to the hardware or underlying configuration, for example disk layout or IP addresses, then you should use this method. When using Couchbase Server within a virtual or cloud environment, the IP address and/or size configuration is likely to have changed considerably.
For advice on using this method, see Section 22.214.171.124, “Restoring to a different cluster”.
Restoring a cluster to a different configuration
If you want to restore data to a cluster with a different configuration, or in the event of a corruption of your existing cluster data, then you can use the cbrestore tool. This natively restores data back into a new cluster and new configuration.
For advice on using this method, see Section 126.96.36.199, “Restoring using cbrestore tool”.
Make sure that any restoration of files also sets the proper ownership of those files to the couchbase user
To restore the information to the same cluster, with the same configuration, you must shutdown your entire cluster while you restore the data, and then restart the cluster again. You are replacing the entire cluster data and configuration with the backed up version of the data files, and then re-starting the cluster with the saved version of the cluster files.
When restoring data back in to the same cluster, then the following must be true before proceeding:
The backup and restore must take between cluster using the same version of Couchbase Server.
The cluster must contain the same number of nodes.
Each node must have the IP address or hostname it was configured with when the cluster was backed up.
You must restore all of the
config.dat configuration files as
well as all of the database files to their original
The steps required to complete the restore process are:
Stop the Couchbase Server service on all nodes. For more information, see Section 3.2, “Startup and Shutdown of Couchbase Server”.
On each node, restore the database and configuration file
config.dat) from your backup copies
for each node.
Restart the service on each node. For more information, see Section 3.2, “Startup and Shutdown of Couchbase Server”.
To restore the data to a different cluster you take a backup of the data, and recreate the bucket configuration on a new cluster. This enables Couchbase Server to load the data into the new cluster and repopulate the database with the backed up data. You cannot change the topology or number of nodes within the cluster using this method, but you can modify the physical characteristics of each node, including the hardware configuration or IP addresses.
You can use this feature to migrate an entire cluster into new set of machines. This is particularly useful when:
In cloud environments, where the IP addresses of nodes will have changed
Hardware configuration, such as RAM size, disk hardware or disk configuration and/or environment has changed.
To create dev/test clusters with the same data as the production cluster
To restore a cluster using this method, the following must be true:
You have a backup of each of the buckets in your cluster made using the cbbackup command.
The two clusters must have the same number of nodes.
The original cluster must be in a healthy state. This means that all nodes should be up and running and no rebalance or failover operation should be running.
It is a best practice for both clusters to be of the same OS and memory configuration.
The necessary steps for migrating data using this method are as follows:
Take a backup of the data files of all nodes, using the above procedure. Alternately, shut down the couchbase-server on all nodes and copy the DB files.
Install Couchbase Server (of at least version 1.7.1) on new nodes and cluster together. If using the web console to setup your cluster, a 'default' bucket will be created. Please delete this bucket before proceeding.
Place the copies of the original files into the data directory on all the new nodes.
You must ensure that each set of original data files gets placed onto one and only one node of the new cluster.
Please ensure that you retain file ownership properties for those files which you placed on the destination node.
Start couchbase-server on the new nodes
Create a bucket with the same name and SASL configuration on the new nodes.
After the bucket creation, each node will start loading items from the data files into memory.
The cluster will be in a balanced state after warm up.
Do not start a rebalance process while nodes are still warming up.
If any nodes go down during the warmup, it is a best practice to restart all nodes together.
There are a number of bugs in older versions of the mbrestore script. Anyone using mbrestore should make sure to get the latest script to ensure proper functionality. You can download the latest from here. The latest version of the script will work with any previous versions of Couchbase.
This is useful if:
You want to restore data into a cluster of a different size
You want to transfer/restore data into a different bucket
You have a broken or corrupted database file (usually from running out of space on a disk drive)
The cbrestore tool provides the following options:
cbrestore opts db_files (use -h for detailed help) -a --add Use add instead of set to avoid overwriting existing items -H --host Hostname of moxi server to connect to (default is 127.0.0.1) -p --port Port of moxi server to connect to (default is 11211) -t --threads Number of worker threads -u --username Username to authenticate with (this is the name of the bucket you are sending data into) -P --password Password to authenticate with (this is the password of the bucket you are sending data into)
Depending on the amount of data, this script can take an extended amount of time to run. It is a best practice to make sure that your connection to the server running the script is not broken, or that you are using something to let the script run in the background (i.e. screen). For example, on Linux:
shell> cbrestore -a default default-0.mb default-1.mb default-2.mb default-3.mb
For better speed/efficiency you can run the command on multiple nodes, with each node using a separate backup file. For example:
shell-node1> cbrestore -a -t 8 default default-0.mb ... shell-node2> cbrestore -a -t 8 default default-1.mb ... shell-node3> cbrestore -a -t 8 default default-2.mb ... shell-node4> cbrestore -a -t 8 default default-3.mb
On Windows, ensure you correctly quote the filename arguments:
shell> cbrestore -a "C:/backup/2010-12-22/default" "C:/backup/2010-12-22/default-0.mb" \ "C:/backup/2010-12-22/default-1.mb" "C:/backup/2010-12-22/default-2.mb" "C:/backup/2010-12-22/default-3.mb"