Setting Up Continuous Replication in CouchDB

Quick answer

To keep two CouchDB databases in sync, create a continuous replication job by POSTing a replication document to the _replicate endpoint. The job runs in the background, checkpoints the last processed sequence, and resumes after interruptions without re‑sending unchanged documents.

How continuous replication works

Continuous replication uses the _changes feed to stream updates from a source database to a target. When you set continuous:true, CouchDB persists a replication document, opens a long‑poll _changes connection, and saves the last processed sequence number as a checkpoint. If the connection drops or the node restarts, the job resumes from that checkpoint.

Example configuration

Run the following curl command on any host that can reach both CouchDB instances. You need admin credentials (or a user with the _replicator role).

curl -X POST http://admin:password@localhost:5984/_replicate \
  -H "Content-Type: application/json" \
  -d '{
    "source": "http://src-host:5984/mydb",
    "target": "http://tgt-host:5984/mydb",
    "continuous": true,
    "create_target": true
  }'

Placeholders:

  
src-host – hostname or IP of the source CouchDB node
  
tgt-host – hostname or IP of the target CouchDB node
  
mydb – name of the database to replicate
  
admin:password – replace with an admin user and password (or use cookie/auth token)

Expected checks:

  
The command returns a JSON object with "ok":true and a replication ID.
  
Visit http://localhost:5984/_active_tasks and look for an entry where "type" is "replication" and "status" is "running".

Verifying the replication
Insert a test document into the source:
curl -X PUT http://admin:password@src-host:5984/mydb/testdoc \
  -H "Content-Type: application/json" \
  -d '{"foo":"bar"}'

After a few seconds, query the target:
curl http://admin:password@tgt-host:5984/mydb/testdoc

If the document appears with the same content, continuous replication is working. Subsequent updates to the source will propagate automatically.
Limits and common mistakes
Resource consumption
Each active replication pair opens one long‑poll _changes socket. Running many concurrent replications can exhaust file descriptors or network ports. Monitor _active_tasks and consider consolidating replications or using a proxy.
Misconfigured URLs
If the source or target points to a non‑existent database, CouchDB will retry indefinitely, filling logs and consuming CPU. Always verify the URLs before starting the job.
Large attachments
Attachments are streamed with each change. Very large binaries can cause time‑outs or stall the replication feed. Store large binaries externally (e.g., in an object store) and keep only references in CouchDB.
Conflict handling
Concurrent updates to the same document on source and target create conflicting revisions. These are stored as _conflicts and must be resolved by your application or a custom conflict handler; otherwise they accumulate and increase database size.
Cleaning up (rollback)
Setting up continuous replication creates a replication document in the _replicator database. To stop the job, delete that document:
curl -X DELETE http://admin:password@localhost:5984/_replicator/?rev=

Obtain  and  from the response of the original POST or by querying _all_docs in _replicator. Deleting the document stops the background job; no data is removed from the source or target databases.