Backing Up And Restoring Data In Couchbase Server

Recently I found myself needing to copy data from one Couchbase Server cluster to another. More specifically I needed to copy production data to my local instance so I could play around with it. This could be accomplished by backing up and restoring remote data in my local instance.

The problem is that I had never done this before.

Now I know what you’re thinking, doesn’t this guy work for Couchbase? The answer is yes, but I very rarely work with production data or find myself in this scenario.

We’re going to take a look at backing up and restoring Couchbase bucket data.

Let’s play along with the scenario I mentioned earlier. Where you have a production dataset that you want to manipulate in a development environment. This assumes that you have two separate instances or clusters of Couchbase Server running.

In my example, I’m using two instances of Couchbase Server 4.1, but anything greater than 3.0 should do the trick.

Backing Up a Particular Bucket in Couchbase Server

The first thing we want to do is back up our production database. We can either back up the entire database (all buckets) or just a particular bucket. In this example we’re only going to back up a particular bucket.

If Couchbase is installed, execute the following from your Terminal (Mac) or Command Prompt (Windows):

cbbackup http://PRD_HOST:8091 ~/Desktop/backups -u USER -p PASSWORD -b default

First of all, we’re executing the command line tool cbbackup which on Mac is found at:

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

If you’re using a Windows, the path to cbbackup can be found here:

C:/Program Files/Couchbase/Server/bin/cbbackup.exe

The first parameter in this backup call is the instance we wish to backup. In this scenario the instance is a cluster, but if you wish to only backup a particular node within the cluster you can include a --single-node tag.

The second parameter in our backup is the location we wish to save the backup. This is followed by the username and password for our cluster.

Finally since I only wished to backup a single bucket, I specified it. My bucket name is default which is not to be confused with a reserved tag in this example.

You should also note that I ran cbbackup from my local machine, not the remote machine. You only need access to the cbbackup application, it doesn’t matter where you run it from. In this scenario, the backup was also saved to my local machine.

More information about the Couchbase Backup Tool can be found in the official documentation.

Restoring a Backup in Couchbase Server

Now we need to restore the bucket we backed up in our development instance of Couchbase Server. Using the Command Prompt (Windows) or Terminal (Mac), execute the cbrestore application from the appropriate directory. For example on Mac it would be:

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

On Windows, the application would be at the following path:

C:/Program Files/Couchbase/Server/bin/cbrestore.exe

Don’t be fooled though, I only gave you the application name and path. To initiate the restore we would do something like this:

cbrestore ~/Desktop/backups http://localhost:8091 --bucket-source=default --bucket-destination=default

The above command will restore the default bucket that we backed up into the default bucket in our development instance, which in my case is locally running.

However, if you’ve been following along, you might end up with the following error message:

s0 error: async operation: error: map missing vbucket_id: 427; perhaps your source does not have vbuckets; if so, try using moxi (HOST:11211) as a destination on sink: http://localhost:8091(default@PRD_HOST:8091)
error: map missing vbucket_id: 427; perhaps your source does not have vbuckets; if so, try using moxi (HOST:11211) as a destination

I didn’t explain my setup in the beginning. I’m using a Mac to develop locally and an Ubuntu machine as my production unit. There is a slight disconnect between how Mac handles vBuckets in comparison to the other operating systems. More information on this can be found in this forum post.

If you’re receiving this error, include -x rehash=1 in your cbrestore command like so:

/Applications/Couchbase\ Server.app/Contents/Resources/couchbase-core/bin/cbrestore ~/Desktop/backups http://localhost:8091 --bucket-source=default --bucket-destination=default -x rehash=1

The error should be gone and your data should be restored.

More information on the cbrestore application can be found in the official documentation.

Conclusion

If you’re using a cluster of Couchbase Server nodes and have opted to, your data will be automatically replicated between them. However, you may find yourself in a scenario like I did where I need to transfer data to say a development instance. In this scenario the use of cbbackup and cbrestore do a great job.

The same things can be applied if you wish to run backups of your data for cold storage via a scheduled script.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in C#, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Unity. Nic writes about his development experiences related to making web and mobile development easier to understand.