Create and restore backups of a whole CouchDB server, with simple tar.gz files.

pip install coucharchive==2.4.0



Use coucharchive to create and restore backups of a whole CouchDB server / cluster of servers, or to simply replicate it to another server / cluster.

Backup archives are saved as single tar.gz file, and can be imported later to any other CouchDB server.

Useful for making backups, or replicating your database to a secondary test environment.


Using pip:

$ pip3 install --user coucharchive


Make a backup archive from a running server:

$ coucharchive create --from \
                      --output test.tar.gz

Restore this archive to another server:

$ coucharchive restore --to \
                       --input test.tar.gz

Simply load a backup in a temporary CouchDB server:

$ coucharchive load -i test.tar.gz
Launched CouchDB instance at http://root:L76mqQE5fE@localhost:38095

Replicate from a CouchDB installation to another one:

$ coucharchive replicate --from \

Slow down replication (to decrease servers load) so that it runs in one hour:

$ coucharchive replicate --from \
                         --to \
                         --ideal-duration 3600

Don't pass credentials on the command line:

$ coucharchive create --from -o test.tar.gz
CouchDB admin for root<ENTER>
CouchDB password for p4ss<ENTER>

How do archives work?

coucharchive spawns a local CouchDB instance locally, using a temporary directory for storing data and configuration.

When dumping, it replicates your source CouchDB server (i.e. replicates all dbs, including _users) to the fresh local one, then saves and compresses its data to a tar.gz archive.

When loading, it uncompresses the archive, has the local CouchDB instance use it as its data, then replicates to your remote CouchDB server.

Go further

For repetitive backups, you can use a config file:

$ cat config.ini
url = http://root:password@my-server:5984

ignore_dbs = db_to_ignore, other_useless_db

$ coucharchive -c config.ini create -o test.tar.gz

To save a backup on AWS S3 and notify somebody via email:

$ aws s3 cp /tmp/archive.tar.gz s3://my-backups/archive.tar.gz
$ cat >/tmp/email.txt <<EOM
Subject: New backup saved on S3

A CouchDB backup called archive.tar.gz was successfully created and pushed
on Amazon S3.
$ sendmail </tmp/email.txt


OSError: [Errno 28] No space left on device

coucharchive uses the /tmp folder, which can be to small.

If it's the case you can try to enlarge it, for example:

sudo mount -o remount,size=32G,noatime /tmp