cbbackupmgr merge

Merges two or more backups together

SYNOPSIS

cbbackupmgr merge [--archive <archive_dir>] [--repo <repo_name>]
                  [--start <backup>] [--end <backup>]

DESCRIPTION

The merge command is used in order to merge two or more backups together. Since cbbackupmgr is a utility that always takes incremental backups it is necessary to reclaim disk space from time to time. Merging data will de-duplicate similar keys in backup files being merged together in order to create a single smaller backup file. Doing merges should replace the full backup step by taking multiple incremental backups of a Couchbase cluster and converting them into a single full backup. Since this process takes place in the backup archive there is no cluster overhead to merging data together. See cbbackupmgr-strategies for suggestions on using the merge command in your backup process.

OPTIONS

Below are a list of required parameters for the merge command.

Required

-a,--archive <archive_dir>

The archive directory to merge data in.

-r,--repo <repo_name>

The name of the backup repository to merge data in.

--start <backup>

The name of the first backup to be merged or an index value which references an incremental backup. Valid index values are any positive integer, "oldest", and "latest". If a positive integer is used then it should reference the index of the incremental backup starting from the oldest to the most recent backup. For example, "1" corresponds to the oldest backup, "2" corresponds to the second oldest backup, and so on. Specifying "oldest" means that the index of the oldest backup should be used and specifying "latest" means the index of the most recent backup should be used.

--end <backup>

The name of the last backup to be merged or a index value which references an incremental backup. Valid index values are any positive integer, "oldest", and "latest". If a positive integer is used then it should reference the index of the incremental backup starting from the oldest to the most recent backup. For example, "1" corresponds to the oldest backup, "2" corresponds to the second oldest backup, and so on. Specifying "oldest" means that the index of the oldest backup should be used and specifying "latest" means the index of the most recent backup should be used.

EXAMPLES

In order to merge data, you need to have a backup repository with at least two backups. Below is an example of merging a backup repository named "example" that has two backups in it. The first backup contains the initial dataset. The second backup was taken after four items were updated.

$ cbbackupmgr list -a /data/backups
Size      Items          Name
148.70MB  -              /
148.70MB  -              + example
98.66MB   -                  + 2016-03-01T16_27_10.093782029-08_00
98.66MB   -                      + travel-sample
300B      0                          bucket-config.json
98.66MB   31592                      + data
98.66MB   31592                          shard_0.fdb
2B        0                          full-text.json
4B        0                          gsi.json
1.72KB    1                          views.json
50.04MB   -                  + 2016-03-01T16_27_51.349151165-08_00
50.04MB   -                      + travel-sample
300B      0                          bucket-config.json
50.04MB   4                          + data
50.04MB   4                              shard_0.fdb
2B        0                          full-text.json
4B        0                          gsi.json
1.72KB    1                          views.json
$ cbbackupmgr merge -a /tmp/backup -r example \
 --start 2016-03-01T16_27_10.093782029-08_00 \
 --end 2016-03-01T16_27_51.349151165-08_00
$ cbbackupmgr list -a /tmp/backup
Size      Items          Name
98.84MB   -              /
98.84MB   -              + example
98.84MB   -                  + 2016-03-01T16_27_51.349151165-08_00
98.84MB   -                      + travel-sample
300B      0                          bucket-config.json
98.84MB   31592                      + data
98.84MB   31592                          shard_0.fdb
2B        0                          full-text.json
4B        0                          gsi.json
1.72KB    1                          views.json

Upon completion of the merge the number of items in the backup files is the same. This is because the keys in the second backup were also contained in the first backup, but the keys in the second backup contained newer values and overwrote the keys in the first backup during the merge. The timestamp of the backup folder is also the same as the timestamp of the latest backup because the new backup is a snapshot of the cluster at that point in time.

DISCUSSION

It is important that internally the merge command is able to merge backups together without corrupting the backup archive or leaving it in an intermediate state. In order to ensure this behavior cbbackupmgr always creates a new backup and completely merges all data before removing any backup files. When a merge is started a .merge_status file is created in the backup repository to track the merge progress. cbbackupmgr then copies the first backup to the .merge folder and begins merging the other backups into .merge folder. After each backup is merged the .merge_status file is updated to track the merge progress. if all backups are merged together successfully, cbbackupmgr will start deleting the old backups and then copy the fully merged backup into a folder containing the same name as the backup specified by the --end flag. If the cbbackupmgr utility fails during this process, then the merge will either be completed or the partial merge files will be removed from the backup repository during the next invocation of the cbbackupmgr.

Since the merge command creates a new backup file before it removes the old ones it is necessary to have at least as much free space as the backups that are to be merge together.

For more information on suggestions for how to use the merge command in your backup process see cbbackupmgr-strategies

ENVIRONMENT AND CONFIGURATION VARIABLES

CB_ARCHIVE_PATH

Specifies the path to the backup archive. If the archive path is supplied as a command line argument then this value is overridden.

FILES

.merge_status

File storing information on the progress of the merge.

.merge

Directory storing intermediate merge data.

CBBACKUPMGR

Part of the cbbackupmgr suite