Configure One-Way Continuous CouchDB Replication Using _replicator

Desired outcome

You want changes written to a source CouchDB database to appear automatically on a target CouchDB database, and you want the sync to keep running after restarts and network interruptions. The useful takeaway is to insert a replication document into the source node’s _replicator system database with continuous: true. CouchDB reads that document, starts a replication job, and retries it when connectivity returns.

Prerequisites and assumptions

• Two CouchDB nodes reachable over TCP port 5984: a source node and a target node.
• Admin credentials, or a user account with write access to _replicator on the source node.
• The source and target databases exist, or create_target: true is set and the account can create databases on the target.
• These steps assume CouchDB 3.x or later. Default bind addresses, authentication requirements, and CORS behavior differ in earlier releases.

Prepare network and authentication

Before creating the replication document, confirm that the source node can reach the target’s hostname and port. If CouchDB is bound to localhost only, remote replication will fail. If authentication is enabled, include credentials in the source and target URLs. Do not rely on CORS alone; CORS governs browser requests, while replication is server-to-server.

Create the replication document

Run the following against the source node. Replace placeholders with your hostnames, database name, and credentials.

curl -X PUT "https://admin:PASSWORD@SOURCE_HOST:5984/_replicator/source-to-target" \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "source-to-target",
    "source": "https://admin:PASSWORD@SOURCE_HOST:5984/source_db",
    "target": "https://admin:PASSWORD@TARGET_HOST:5984/target_db",
    "continuous": true,
    "create_target": true
  }'

Permissions: the requesting user needs write access to _replicator, typically through an admin account. Risk: credentials embedded in the URLs are readable by anyone who can read _replicator. Consider restricting read access to that database or using an account with limited privileges.

Expected checks

1. Confirm the job started. Poll GET /_active_tasks on the source node and look for a task whose type is replication, continuous is true, and source and target match your URLs.
2. Confirm data transfer. After the initial sync, compare update_seq from GET /source_db and GET /target_db, or compare document totals. The target may lag briefly because replication is eventually consistent.
3. Check logs if the task is missing or failing. Look for replication errors in CouchDB’s log output. A crashing or error state often indicates authentication failure, network unreachability, or a missing target database.

Stop or remove the replication job

Deleting the replication document stops the job. There is no separate cancel endpoint for _replicator entries.

curl -X DELETE "https://admin:PASSWORD@SOURCE_HOST:5984/_replicator/source-to-target?rev=REV"

Get the current REV with GET /_replicator/source-to-target. After deletion, confirm the task disappears from _active_tasks. This stops future syncing; documents already copied to the target remain there. This is not a rollback of replicated data.

Limitations

• One-way continuous replication copies changes from source to target only. Deletes and conflicts propagate, so it is not a backup or conflict-resolution strategy.
• Large initial syncs or high write churn can consume substantial network bandwidth and disk I/O.
• Network partitions can leave the task in a crashing or error state until connectivity is restored and CouchDB retries.

Practical verification

After creating the document, wait for the initial sync, then run GET /_active_tasks and verify the replication task appears with continuous: true. Then delete the document and verify the task is gone. If the task never appears, check the _replicator document status and CouchDB logs before adjusting credentials or network rules.