How does CouchDB replication work and what is the replication protocol?

CouchDB replication is a document-level sync protocol that copies documents from a source database to a target database using standard HTTP. Either or both of source and target can be local or remote CouchDB instances. Replication is initiated by posting a replication document to the _replicator database or to the /_replicate endpoint directly.

The protocol works through these concrete steps:

1. Get peer info — the replicator calls GET /target to confirm the target is reachable and retrieves its UUID.
2. Read checkpoint — it reads the last replication checkpoint stored in a _local/ document on both source and target to know the last source sequence number already replicated.
3. Get changes — it calls GET /source/_changes?since={last_seq} to fetch all document IDs and their current revisions changed since the last checkpoint.
4. Check target revisions — it POSTs the changed IDs to POST /target/_revs_diff to find which revisions the target is missing.
5. Fetch missing docs — it fetches the missing document bodies from the source (with attachments if any) and POSTs them in bulk to /target/_bulk_docs.
6. Save checkpoint — it writes the new sequence number to _local/ docs on both peers so the next replication starts from there.

// Replication document in the _replicator database:
{
  "_id": "sync-orders-to-replica",
  "source": "http://admin:pass@primary:5984/orders",
  "target": "http://admin:pass@replica:5984/orders",
  "continuous": false,
  "create_target": true
}

The protocol is idempotent: re-running a replication never loses data or creates duplicates. Because it uses standard HTTP and checkpoint documents, any two CouchDB instances can replicate without special network infrastructure — making it practical for cloud-to-edge and offline-mobile scenarios.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.