cbbackupmgr tutorial

Before getting started with cbbackupmgr we must first decide the directory where to store all of our backups. This directory is referred to as the backup archive. The backup archive contains one or more backup repositories. These backup repositories are where your backups will be contained. The easiest way to think of a backup repository is that it corresponds directly to a single cluster that you want to back up. The backup repository also contains a configuration for how to back that cluster up. A backup repository is created by using the config subcommand. In this tutorial we will use a backup archive located at /data/backup. The backup archive is automatically created if the directory specified is empty. Below is an example of how to create a backup repository called "cluster" which will backup all data and index definitions from all buckets in the target cluster.

One of the most important aspects of backup repository creation is that we can configure that backup repository in many different ways to change the way backups in each backup repository are taken. Let’s say we want a separate backup of only the index definitions in the travel-sample bucket. To do this we can create a separate backup repository called "single".

The config subcommand provides many options in order to customize how you backup your data. See the cbbackupmgr-config page for more information about what options are available and how they are used.

Now that we have created some backup repositories we should take a look at our backup archive to see what it looks like. The easiest way to do this is to use the info subcommand. This subcommand is used to retrieve information form a backup archive. It will return the size as well as information about the repositories, backups and item counts.

The info subcommand gives us a directory print out of all of the backup repositories and backups in the backup archive. Since there are no backups yet we can just see our archives information in the output of this command. There is also information about how much disk space each repository contains. More information about the info subcommand can be found in the cbbackupmgr-info page.

Now that we have our backup repositories configured it’s time to start taking backups. Since the backup repository contains all of the configuration information for how the backup should be taken we just need to specify the backup repository name and the information for the target cluster we intend to back up. Below is an example of how to take a backup on the "cluster" backup repository. We will assume that we have our cluster running on localhost.

When the backup command is executed it will by default print out a progress bar which is helpful for understanding how long your backup will take to complete and the rate of data movement. While the backup is running the progress bar will give an estimated time to completion, but this will change to average backup rate when the backup finishes. Information is also provided on the total data and items already backed up and the current rate of data movement. If the backup completes successfully you will see the "Backup completed successfully" message and a break down of mutations and deletions backed up per bucket.

Let’s also run the backup on the "single" backup repository to see how the two backup runs differ.

Since the "single" backup repository is only configured to back up index definitions for the travel-sample bucket we do not see a progress bar for the beer-sample bucket. We can also see that the backup executed quicker since there was much less data to actually back up.

Since we now have backups in our backup archive let’s take a look at the state of our backup archive has changed by using the info subcommand.

Now that we have some backups defined the output of the info subcommand is much more useful. We can see that our "cluster" backup repository contains one backup with a name corresponding to the time the backup was taken. That backup also contains two buckets and we can see the number of views, indexes, mutations, tombstones and more in the bucket. The "single" backup repository also contains one backup, but this backup only contains the travel-sample bucket and contains 0 data items but we can see it has 10 indexes. Note that the info command also supports JSON output if that is preferable. See cbbackupmgr-info page.

One of the most important features of cbbackupmgr is that it is an incremental-only backup utility. This means that once we have backed up some data we will never need to back it up again. In order to simulate some changes on the cluster we can run the 02-modify.sh script from the backup-tutorial github repository mentioned at the beginning of the tutorial. If you do not have this script then you will need to modify two documents and add two new documents to the travel-sample bucket. After we have modified some data we will run the backup subcommand on the "cluster" backup repository again.

In this backup notice that since we updated 2 items and created two items that this is all that we need back up during this run. If we list the backup archive using the info subcommand then we will see that the backup archive looks like something like what is below. We can see that our incremental contains 4 items all of which are mutations. Those correspond to the 2 modifications and the 2 additions.

The backup subcommand provides many options in order to customize how you backup your data. See the cbbackupmgr-backup page for more information about what options are available and how they are used.

Now that we have some backup data let’s restore that data backup to the cluster. In order to restore data we just need to know the name of the backup that we want to restore. To find the name we can again use the info subcommand in order to see what is in our backup archive. The backup name will always be a timestamp. For example, let’s say we want to restore the 2016-03-22T10_26_08.933579821-07_00 from the "cluster" backup repository. In order to do this we run the command below.

In the command above we use the --start and --end flags to specify the range of backups we want to restore. Since we are only restoring one backup we specify the same value for both --start and --end. We also added the --force-updates flag in order to skip Couchbase conflict resolution. This tells cbbackupmgr to force overwrite key-value pairs being restored even if the key-value pair on the cluster is newer and the one being restored. If we look at the two values that we updated on the cluster we will now see that they have been reverted back to what they were at the time we took the initial backup. If you used the script in the backup-tutorial github repository to update documents then you can use the 03-inspect.sh script to see the state of the updated documents after the restore.

The restore subcommand also allows for you to exclude data that was backed up from the restore and provides various other options. See the cbbackupmgr-restore page for more information on restoring data.

Using an incremental backup solution means that each backup we take increases disk space. Since disk space in not infinite we need to be able to reclaim this disk space. In order to do this we use the cbbackupmgr-merge subcommand to merge two or more backups together. Since we have two backups in the "cluster" backup repository we will merge these backups together using the command below.

After merging the backups together we can use the list subcommand to see the effect the merge subcommand we just ran had on the backup archive.

We can see from the list command that there is now a single backup in the "cluster" backup repository. This backup has a name that reflects the name of the most recent backup in the merge. It also has 31593 data items in the travel-sample bucket. This is two more items than the original backup we took because the second backup had two new items. The two items that were updated were deduplicated during the merge so they do not add extra items to the count displayed by the info subcommand.

For more information on how the merge command works as well as information on other ways the merge command can be used see the cbbackupmgr-merge page.

If no longer need a backup repository then we can use the remove subcommand to remove the backup repository. Below is an example showing how to remove the "cluster" backup repository.

If we now run the list subcommand you will see that the "cluster" backup repository no longer exists. For more information on the remove subcommand see the cbbackupmgr-remove page.