Apache CouchDB: Replication, Conflicts & Offline Sync

Apache CouchDB

Apache CouchDB is a document database whose defining feature is replication. Every CouchDB database can synchronize with any other — another server, a cluster in another region, or a browser or phone running the compatible PouchDB library — in either direction, continuously or on demand, surviving long disconnections. Documents are JSON, everything is accessed over a plain HTTP REST API, and every change carries a revision that lets replicas detect when the same document was edited in two places.

That design makes CouchDB a strong fit for offline-first applications — field workers, point-of-sale systems, mobile apps in areas with poor connectivity — and for data that must flow between many sites. The trade-off is that applications must handle conflicts explicitly and model queries around indexes rather than ad hoc joins.

TL;DR

Documents are JSON with an _id and a _rev; every update must supply the current revision.
The entire API is HTTP and JSON: create, read, update, delete, query, and replicate with plain requests.
Query with Mango (_find) backed by indexes, or MapReduce views for aggregations.
The changes feed (_changes) streams every modification — the basis of replication and integrations.
Multi-master replication can run continuously in any direction; concurrent edits create conflicts that the application resolves.
PouchDB brings the same model to browsers and mobile apps for offline-first sync.

Quick Example

Create, update, and query documents over HTTP:

Offline-first sync from a browser with PouchDB, plus conflict resolution:

Core Concepts

Documents and Revisions

Each document has an _id (chosen by you or generated) and a _rev like 2-a1b2c3...: a generation number and a hash. Updates must include the revision they modify; if someone else changed the document first, CouchDB rejects the write with 409 Conflict, giving optimistic concurrency on a single node. Documents can carry attachments (binary files) alongside JSON.

Querying

Without a matching index, Mango falls back to scanning the whole database — fine in development, disastrous at scale. Design document IDs and indexes around the queries you need; there are no joins.

The Changes Feed

_changes lists every document change since a given sequence, in order, optionally as a long-poll or continuous stream with filters. Replication, search indexing, and integrations with other systems are built on it.

Replication and Conflicts

Replication copies changes from a source database to a target — one-shot or continuous, one direction or both, optionally filtered to a subset of documents. Any number of replicas can accept writes (multi-master). When the same document is edited on two replicas before they sync, both revisions survive: CouchDB picks a deterministic winner so every replica shows the same current version, and lists the others in _conflicts. The application must detect conflicts and merge them — CouchDB never silently discards one.

Clustering

A CouchDB cluster splits each database into shards (q) with replicas (n, typically 3) across nodes, with tunable read and write quorums. Partitioned databases group documents by a partition key for efficient queries within a partition.

Security and Access

Require authentication: CouchDB 3 requires an admin to be created; keep admin credentials out of applications.
Per-database security objects list member and admin users and roles; anyone in members can read and write every document in that database.
Document-level access is limited, so multi-user apps often use one database per user or group, replicating shared data as needed.
Validation functions (validate_doc_update) in design documents can reject invalid writes or unauthorized changes.
Terminate TLS at CouchDB or a proxy, and never expose the admin interface publicly.

When CouchDB Fits

Compare with MongoDB for general-purpose document storage and Cloud Firestore for managed real-time sync. See Local-First for the broader offline-first approach.

Operations

Compaction reclaims space from old revisions and must run regularly (automatic compaction is configurable).
Index builds happen lazily on first query by default; warm critical views after deploys.
Monitoring: watch replication task status, active tasks, request latency, and disk usage through _active_tasks, _scheduler/jobs, and metrics endpoints.
Backups: replicate to a backup database or snapshot data directories consistently, and test restores.
Revision limits: _revs_limit controls how much history is kept; deleted documents leave tombstones that replicate.

Best Practices

Design for Conflicts From the Start

Decide how each document type merges — last edit per field, append-only events, or user choice — and run conflict resolution in the application or a background worker.

Prefer Small, Focused Documents

Documents edited by many people at once conflict more often. Split them (for example, one document per comment or order line) to reduce conflicts.

Index Every Production Query

Create Mango indexes or views for each query pattern and check _explain output so no request scans the database.

Partition Access by Database

Use per-user or per-team databases when users must only see their own data, and replicate shared reference data into them.

Common Mistakes

Ignoring _rev

Assuming Replication Prevents Conflicts

Shared Databases for Private Data

FAQ

What is CouchDB used for?

Storing JSON documents accessed over HTTP, especially when data must replicate between servers, sites, and offline devices — for example offline-first mobile and web applications with PouchDB.

How does CouchDB handle conflicts?

When the same document is changed on different replicas, CouchDB keeps all versions, chooses a deterministic winning revision, and lists the others in _conflicts. The application reads the conflicting revisions, merges them, and deletes the losing ones.

What is the difference between CouchDB and MongoDB?

Both store JSON-like documents. CouchDB emphasizes an HTTP API, multi-master replication, and offline sync with conflict handling. MongoDB emphasizes rich queries, aggregation pipelines, drivers, and primary-replica replication within a cluster.

What is PouchDB?

A JavaScript database for browsers and Node.js that implements the CouchDB replication protocol, so apps can store data locally and sync with CouchDB when online.

Does CouchDB support queries without indexes?

Mango queries without a suitable index fall back to scanning the database, which is slow for large datasets. Production queries should always be backed by indexes or views.