CouchDB Replication

introduction (Local Replication)

First, we’ll create a target database. Note that CouchDB won’t automatically create a target database for you, and will return a replication failure if the target doesn’t exist (likewise for the source, but that mistake isn’t as easy to make). Let us then create our target database for replication, albums-replica:

curl -X PUT http://admin:password@127.0.0.1:5984/albums-replica

Now we can use the database albums-replica as a replication target:

curl -X POST http://admin:password@127.0.0.1:5984/_replicate \
     -d '{"source":"http://admin:password@127.0.0.1:5984/albums","target":"http://admin:password@127.0.0.1:5984/albums-replica"}' \
     -H "Content-Type: application/json"

If you now have a look at the albums-replica database, you should see all the documents that you created in the albums database.

Note As of CouchDB 2.0.0, fully qualified URLs are required for both the replication source and target parameters.

Note CouchDB supports the option "create_target":true placed in the JSON POSTed to the _replicate URL. It implicitly creates the target database if it doesn’t exist.

CouchDB maintains a session history of replications. The response for a replication request contains the history entry for this replication session. It is also worth noting that the request for replication will stay open until replication closes. If you have a lot of documents, it’ll take a while until they are all replicated and you won’t get back the replication response until all documents are replicated. It is important to note that replication replicates the database only as it was at the point in time when replication was started. So, any additions, modifications, or deletions subsequent to the start of replication will not be replicated.

Remote Replication

What we have just done is called local replication in CouchDB terms. You created a local copy of a database. This is useful for backups or to keep snapshots of a specific state of your data around for later. You might want to do this if you are developing your applications but want to be able to roll back to a stable version of your code and data.

There are other types of replication than local. The source and target members of our replication request are actually links (like in HTML) and so far we’ve seen links relative to the server we’re working on (hence local). You can also specify a remote database as the target:

curl -X POST http://admin:password@127.0.0.1:5984/_replicate \
     -d '{"source":"http://admin:password@127.0.0.1:5984/albums","target":"http://user:password@example.org:5984/albums-replica"}' \
     -H "Content-Type:application/json"

Using a local source and a remote target database is called push replication. We’re pushing changes to a remote server.

(Since we don’t have a second CouchDB server around just yet, we’ll just use the absolute address of our single server, but you should be able to infer from this that you can put any remote server in there.)

Remote replicacion is useful for sharing local changes with remote servers or collaborators.

You can also use a remote source and a local target to do a pull replication. This is good for getting the latest changes from a server that is used by others:

curl -X POST http://admin:password@127.0.0.1:5984/_replicate \
     -d '{"source":"http://user:password@example.org:5984/albums-replica","target":"http://admin:password@127.0.0.1:5984/albums"}' \
     -H "Content-Type:application/json"

Finally, you can run remote replication between two remote machines, especially if you are an administrator:

curl -X POST http://admin:password@127.0.0.1:5984/_replicate \
     -d '{"source":"http://user:password@example.org:5984/albums","target":"http://user:password@example.org:5984/albums-replica"}' \
     -H "Content-Type: application/json"