Creating a backup
This tutorial demonstrates how to use the CouchBackup utility to back up and restore a CouchDB or IBM® Cloudant® for IBM Cloud® instance. CouchBackup backs up the database to a file. If the database fails, you can use the backup file to restore the information to an existing database.
Objectives
- Install CouchBackup.
- Create a sample database with documents.
- Set an environment variable.
- Back up a database.
- Create a log file.
- Restore a backup from a text file.
Installing CouchBackup
Install CouchBackup by running the install
command.
npm install -g @cloudant/couchbackup
Creating a sample database
Create a sample couchbackup-demo
database for use with this tutorial.
-
Create a database by running this command.
curl "https://username:password@myhost.cloudant.com/couchbackup-demo" -X PUT
-
Review the results.
{ "ok": true }
Creating documents in the sample database
The documents that you create in this exercise contain the data that you back up and restore in later exercises.
-
Copy the sample text to a data file named
bulkcreate.dat
to create all five documents.{ "docs": [ { "_id": "doc1", "firstname": "Sally", "lastname": "Brown", "age": 16, "location": "New York City, NY" }, { "_id": "doc2", "firstname": "John", "lastname": "Brown", "age": 21, "location": "New York City, NY" }, { "_id": "doc3", "firstname": "Greg", "lastname": "Greene", "age": 35, "location": "San Diego, CA" }, { "_id": "doc4", "firstname": "Anna", "lastname": "Greene", "age": 44, "location": "Baton Rouge, LA" }, { "_id": "doc5", "firstname": "Lois", "lastname": "Brown", "age": 33, "location": "Syracuse, NY" } ] }
-
Run this command to create the documents.
curl "https://username:password@myhost.cloudant.com/couchbackup-demo/_bulk_docs" -X POST -H "Content-Type: application/json" -d \@bulkcreate.dat
-
Review the results.
[ { "ok": true, "id": "doc1", "rev": "1-57a08e644ca8c1bb8d8931240427162e" }, { "ok": true, "id": "doc2", "rev": "1-bf51eef712165a9999a52a97e2209ac0" }, { "ok": true, "id": "doc3", "rev": "1-9c9f9b893fcdd1cbe09420bc4e62cc71" }, { "ok": true, "id": "doc4", "rev": "1-6aa4873443ddce569b27ab35d7bf78a2" }, { "ok": true, "id": "doc5", "rev": "1-d881d863052cd9681650773206c0d65a" } ]
Setting an environment variable
You can use environment variables or options to specify the URL and database for the CouchDB or IBM Cloudant instance that you want to work with CouchBackup.
In this tutorial, you set the COUCH_URL
and specify the database by using the --db
parameter.
Set the COUCH_URL
environment variable to specify the URL for the CouchDB or IBM Cloudant instance.
export COUCH_URL=https://username:password@myhost.cloudant.com
Backing up a database
The CouchBackup utility backs up your database to a text file to preserve your data and make it easier to restore.
-
Run the
couchbackup
command to direct the contents of your database to a text file.couchbackup --db couchbackup-demo > couchbackup-demo-backup.txt
-
Review the results.
================================================================================ Performing backup on https://****:****@myhost.cloudant.com/couchbackup-demo using configuration: { "bufferSize": 500, "log": "/var/folders/r7/vtctv4695hj_njxmr2hj4jyc0000gn/T/tmp-3132gHPWk9A9yGVe.tmp", "mode": "full", "parallelism": 5 } ================================================================================ Streaming changes to disk: batch 0 couchbackup:backup written 0 docs: 5 Time 0.604 +0ms couchbackup:backup finished { total: 5 } +4ms
-
Check the directory to verify that the
couchbackup-demo-backup.txt
file was created. -
Open the file and review the list of documents that are backed up from the database.
[ { "_id": "doc2", "_rev": "1-2c5ee70689bb75af6f65b0335d1c92f4", "firstname": "John", "lastname": "Brown", "age": 21, "location": "New York City, NY", "_revisions": { "start": 1, "ids": [ "2c5ee70689bb75af6f65b0335d1c92f4" ] } }, { "_id": "doc3", "_rev": "1-f6055e3e09f215c522d45189208a1bdf", "firstname": "Greg", "lastname": "Greene", "age": 35, "location": "San Diego, CA", "_revisions": { "start": 1, "ids": [ "f6055e3e09f215c522d45189208a1bdf" ] } }, { "_id": "doc1", "_rev": "1-cce7796c7113c5498b07d8e11d7e0c12", "firstname": "Sally", "lastname": "Brown", "age": 16, "location": "New York City, NY", "_revisions": { "start": 1, "ids": [ "cce7796c7113c5498b07d8e11d7e0c12" ] } }, { "_id": "doc4", "_rev": "1-0923b723c62fe5c15531e0c33e015148", "firstname": "Anna", "lastname": "Greene", "age":44, "location": "Baton Rouge, LA", "_revisions": { "start": 1, "ids": [ "0923b723c62fe5c15531e0c33e015148" ] } }, { "_id": "doc5", "_rev": "1-19f7ecbc68090bc7b3aa4e289e363576", "firstname": "Lois", "lastname": "Brown", "age": 33, "location": "Syracuse, NY", "_revisions": { "start": 1, "ids": [ "19f7ecbc68090bc7b3aa4e289e363576" ] } } ]
Creating a log file
A log file records the progress of your backup. With CouchBackup, you use the --log
parameter to create the log file. You can also use it to restart a backup from where it stopped and specify the output file name.
The couchbackup
command uses these parameters to specify the database, log file, and resume option.
--db
couchbackup-demo
--log
couchbackup-demo.log
--resume
true
-
Run the
couchbackup
command to create a log file.couchbackup --db couchbackup-demo --log couchbackup-demo-backup.log > couchbackup-demo-backup-log.txt
-
Review the results.
================================================================================ Performing backup on https://****:****@myhost.cloudant.com/couchbackup-demo using configuration: { "bufferSize": 500, "log": "couchbackup-demo-backup.log", "mode": "full", "parallelism": 5 } ================================================================================ Streaming changes to disk: batch 0 [{"_id":"doc2","_rev":"1-2c5ee70689bb75af6f65b0335d1c92f4", "firstname":"John","lastname":"Brown","age":21, "location":"New York City, NY", "_revisions":{"start":1,"ids":["2c5ee70689bb75af6f65b0335d1c92f4"]}}, {"_id":"doc4","_rev":"1-0923b723c62fe5c15531e0c33e015148", "firstname":"Anna","lastname":"Greene","age":44, "location":"Baton Rouge, LA", "_revisions":{"start":1,"ids":["0923b723c62fe5c15531e0c33e015148"]}}, {"_id":"doc1","_rev":"1-cce7796c7113c5498b07d8e11d7e0c12", "firstname":"Sally","lastname":"Brown","age":16, "location":"New York City, NY", "_revisions":{"start":1,"ids":["cce7796c7113c5498b07d8e11d7e0c12"]}}, {"_id":"doc5","_rev":"1-19f7ecbc68090bc7b3aa4e289e363576", "firstname":"Lois","lastname":"Brown","age":33, "location":"Syracuse, NY", "_revisions":{"start":1,"ids":["19f7ecbc68090bc7b3aa4e289e363576"]}}, {"_id":"doc3","_rev":"1-f6055e3e09f215c522d45189208a1bdf", "firstname":"Greg","lastname":"Greene","age":35, "location":"San Diego, CA", "_revisions":{"start":1,"ids":["f6055e3e09f215c522d45189208a1bdf"]}}] couchbackup:backup written 0 docs: 5 Time 0.621 +0ms couchbackup:backup finished { total: 5 } +4ms
-
Open the log file,
couchbackup-demo-backup.log
, and review the actions that are taken during the backup or restore.:t batch0 [ {"id":"doc1"}, {"id":"doc5"}, {"id":"doc3"}, {"id":"doc4"}, {"id":"doc2"} ] :changes_complete 5-g1AAAAXkeJyl1MFNwzAUBmBDk RAnugEc4Nji2ImTnOgGsAH4-dkqVZoi1J5hA9gANoA NYAPYADaADUqMEYlBIWl7caTI-l7e_-xkhJDusINkD 0FNLvQAIenDuKdUD2XWo7yvsskMZT7t53qaFbvXJYH t-Xw-GnYkGRcvNsM0lRwAydYsR23Oco2-GDWI0C1W2 PFQFCYwKf2N7v-gAWtSd6168K2ufaksoQwD3dbx2wi aClJb8NBvQyVIk6Q-m6a0YWDRIw8NKA85M_Vo2IQe W_TEi0YIGiETLZlFZ3FqC068LqgBpHFQ30Vj3ucWv fRQYTAGwZbPO98oVnJVPAr3uoSTIGYcw3qYt4JvHHx b-WIpIqpwhYPu5Dsn35eyxNRI-c-9bArYwQ8OfqwcFY ghEdCSWib_J1fz2dZcdxcpAh2lpiW1zGheXM3XMsBY CcHonxO68GjenPxeyopyrXW86mg-HFz9NZiQh1FUhUefOhzMIg :d batch0
Restoring from a backup text file
From the couchbackup-demo-backup.txt
file, you can restore your data to a new, empty database by using the couchrestore
command.
Restoring a backup is only supported when you restore into an empty database. If you delete all documents from a database, document deletion records are still present for replication consistency purposes. A database that contains only deleted documents is not considered empty, and so cannot be used as the target when you restore a backup.
-
(Prerequisite) Create a new, empty database where you can restore your data.
curl "https://username:password@myhost.cloudant.com/couchbackup-demo-restore" -X PUT
-
Run the
couchrestore
command.cat couchbackup-demo-backup.txt | couchrestore --db couchbackup-demo-restore
-
Review the results.
================================================================================ Performing restore on https://****:****@myhost.cloudant.com/couchbackup-demo-restore using configuration: { "bufferSize": 500, "parallelism": 5 } ================================================================================ couchbackup:restore restored 5 +0ms couchbackup:restore finished { total: 5 } +1ms
You completed the backup and restore of a database and created a log file. For more information, see Disaster recovery and backup, Configuring IBM Cloudant for cross-region disaster recovery, and IBM Cloudant backup and recovery.