Configure Continuous Replication Between Two CouchDB Instances

Desired Outcome

Establish a continuous replication link from a source CouchDB database to a target CouchDB database so that any create, update, or delete operation on the source is automatically propagated to the target, and the replication survives node restarts.

Prerequisites

• Two CouchDB instances (version 3.x recommended) running and accessible via HTTP/HTTPS.
• Network connectivity between the instances (firewall rules allow traffic on the CouchDB port, default 5984).
• A user account with the _replicator role and read/write access to both the source and target databases (e.g., replicator user).
• Both instances should have the same major version to avoid protocol mismatches.

Procedure

1. Create the replication document

Replication jobs are stored as documents in the _replicator database. You can create the document on any node; here we use the source node for clarity.

# Replace placeholders with your actual values
curl -X PUT http://replicator:password@source-host:5984/_replicator/my-replication \
  -H "Content-Type: application/json" \
  -d '{
    "_id": "my-replication",
    "source": "http://replicator:password@source-host:5984/source-db",
    "target": "http://replicator:password@target-host:5984/target-db",
    "continuous": true,
    "create_target": true
  }'

Explanation of fields:

_id – unique identifier for the replication job.
source – URL of the source database (include credentials if authentication is required).
target – URL of the target database.
continuous – set to true to keep the job running after the initial sync.
create_target – optional; creates the target database if it does not exist.

2. Verify the job is started
After posting the document, CouchDB launches a replication process. Check the active tasks list:
curl -s http://replicator:password@source-host:5984/_active_tasks | jq '.[] | select(.type=="replication")'

You should see an entry with "status":"running" (or "triggered" briefly before it becomes running). The replication document itself will have a field _replication_state that transitions from "triggered" to "running".
3. Confirm data synchronization
Insert a test document into the source database and verify it appears on the target.
# Add a test doc to source
curl -X POST http://replicator:password@source-host:5984/source-db \
  -H "Content-Type: application/json" \
  -d '{"test":"value","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'

Wait a few seconds (latency depends on network and load) then query the target:
curl -s http://replicator:password@target-host:5984/target-db/_all_docs?include_docs=true | jq '.rows[] | select(.doc.test=="value")'

If the document appears, replication is working. Repeat with an update or delete to confirm those operations propagate as well.
4. Monitor for errors
Replication errors are stored in the replication document’s _last_error field. Periodically check:
curl -s http://replicator:password@source-host:5984/_replicator/my-replication | jq '._last_error'

An empty value or null indicates no recent errors. Also watch the _replication_id field; a steadily increasing value shows ongoing activity.
Expected Checks

Replication document exists in _replicator with correct source and target URLs.
_active_tasks shows a replication task with status running (or completed for one‑shot).
The replication document’s _replication_state is running (continuous) and _last_error is empty.
Test create/update/delete operations on the source are visible on the target within expected latency.

Recovery Options
If replication stops:

Check connectivity: verify that both hosts can reach each other on the CouchDB port (e.g., telnet target-host 5984).
Inspect credentials: ensure the replicator user still exists and has the required roles.
Review logs: CouchDB logs (/opt/couchdb/log/couch.log by default) contain replication‑specific messages.
Restart the job: you can delete and recreate the replication document, or simply set continuous to false then back to true to trigger a restart.
Handle conflicts: if the same document was updated on both sides, CouchDB stores conflicting revisions. Use the _conflicts endpoint to examine them and apply application‑level resolution.

Limitations
Continuous replication generates persistent network traffic; monitor bandwidth usage, especially in high‑write environments. Document conflicts are not resolved automatically—your application must decide which revision wins. Replication does not transfer design documents or security objects unless they are included as regular documents in the source database.