Setting Up Continuous Bidirectional Replication Between Two CouchDB Instances

Desired Outcome

Establish continuous, bidirectional replication so that any document created, updated, or deleted on either CouchDB instance appears automatically on the other.

Prerequisites

• Two reachable CouchDB 2.x or 3.x servers (default HTTP port 5984).
• Admin username and password for both servers.
• Source and target databases already created (e.g., 'mysource' and 'mytarget').
• Network connectivity between the servers (firewall allows TCP 5984).

Procedure

1. Identify the URLs. Replace placeholders with your actual values:

   SOURCE_URL='http://admin:password@source-host:5984'
   TARGET_URL='http://admin:password@target-host:5984'
   DB_NAME='mydb'

   Run these assignments in a shell where you will execute the curl commands.
2. Create the replication document for source → target.

   curl -X POST "$SOURCE_URL/_replicate" \
     -H "Content-Type: application/json" \
     -d '{
           "source":"'$DB_NAME'",
           "target":"'$TARGET_URL'/'$DB_NAME'",
           "continuous":true,
           "create_target":false,
           "doc_ids":null
         }'
   

   The command must be run with a user that has _replicate privileges (typically an admin).
3. Create the reverse direction (target → source).

   curl -X POST "$TARGET_URL/_replicate" \
     -H "Content-Type: application/json" \
     -d '{
           "source":"'$DB_NAME'",
           "target":"'$SOURCE_URL'/'$DB_NAME'",
           "continuous":true,
           "create_target":false
         }'
   

4. Capture the replication IDs. Each POST returns a JSON object containing an "_id" field (e.g., "7a9b3c..."). Save these IDs for later checks.

Expected Checks

• Replication document state. After a few seconds, query the doc:

  curl "$SOURCE_URL/_local/"

  Look for "state":"completed" or "state":"triggered" and the absence of an "error" field.
• Changes feed. Monitor live changes on either side:

  curl "$SOURCE_URL/$DB_NAME/_changes?feed=continuous&since=now"

  Insert a test document on the opposite instance and verify it appears in the feed.
• Document count symmetry. Compare counts:

  curl "$SOURCE_URL/$DB_NAME/_all_docs?limit=1"

  and the same on the target; the "total_rows" value should match after a known write.

Recovery Options

• Inspect failures. If the replication document shows an "error" field, read the "reason" for clues (e.g., network timeout, unauthorized).
• Reset the replication. Delete the faulty doc and recreate it:

  curl -X DELETE "$SOURCE_URL/_local/"

  Then repeat the POST step.
• Check network/firewall. Verify TCP 5984 connectivity with telnet or nc -vz source-host 5984.
• Design document conflicts. Ensure that any design documents (especially validate_doc_update) do not reject writes from the replication user.

Limitations and Practical Verification

Continuous replication uses a long‑polling feed; under very high write rates it can increase CPU and memory usage. Monitor the CouchDB metrics (_stats endpoint) and consider throttling if needed. The verification steps above provide a practical way to confirm that replication is active without requiring special tools.