cloudparts

Apache CouchDB

A JSON document database spoken to entirely over HTTP, built around replication: any two copies can sync in either direction and keep conflicting edits instead of losing them.

Apache · Top-level project
What it is
Document databases
Type
Open source
Made by
Apache Software Foundation
Foundation
The Apache Software Foundation, top-level project, joined February 2008
License
Apache 2.0
Facts checked
24 October 2026
Website Source code

What it is

CouchDB stores JSON documents in databases and exposes everything, from creating a database to querying it, as a REST API over HTTP. Every document has an _id and a _rev. To update one you send back the revision you read; if someone else saved first, the write fails with an edit conflict, so there are no locks, only optimistic concurrency. Storage is append-only: documents and their B-tree indexes are written at the end of the file and committed data is never overwritten, which is why a crash can’t corrupt the database and why it needs periodic compaction. A single-document update is all-or-nothing, but there are no transactions across documents.

Replication is the feature the rest is built around. A replication task reads one database’s changes feed and copies whatever revisions the other side lacks, once or continuously, and two tasks in opposite directions keep a pair in sync. Any node can take writes. When the same document was changed on both sides, CouchDB keeps both revisions, picks the same winner deterministically on every replica, and leaves the loser for the application to merge. The same Couch Replication Protocol is spoken by PouchDB in browsers and phones, so an app can work offline against a local copy and sync later.

Queries come in two forms. Views are JavaScript map (and optional reduce) functions whose results CouchDB stores as an index and updates incrementally when it is read. Mango, added in 2.0, is a declarative JSON query (_find) over indexes you declare. Since 2.0 a cluster splits each database into q shards (2 by default) with n copies of each (3 by default); reads and writes wait for a quorum, two of three, though view and _find queries read only one copy. The current release is 3.5.3, from October 2026.

Why teams pick it

  • Multi-primary replication with conflicts kept, not lost, which suits devices that go offline and sync later
  • Plain HTTP and JSON: curl is a client, and caches and proxies work in front of it
  • Append-only storage that survives crashes without a repair step
  • Apache 2.0 under the Apache Software Foundation, with PouchDB speaking the same sync protocol in the browser

Watch out for

  • No transactions across documents, and the application must find and merge conflicting revisions itself
  • Views and Mango indexes are built when queried, so the first read after many writes can be slow
  • Append-only files grow with every update until compaction runs, which costs disk space and I/O
  • View and _find queries read only one copy of each shard, so in a cluster they can miss a write that a quorum has already accepted

Good for

Specs

Compare with alternatives →
Data model
JSON documents, each with an _id and a _rev
Query language
Mango JSON queries (_find) and JavaScript map/reduce views
Client protocol
REST API over HTTP with JSON
Secondary indexes
Map/reduce views and declared Mango indexes, updated when queried
Transactions
One document at a time; none across documents
Consistency
Quorum reads and writes (two of three); views and _find read one copy
How it scales
Each database split into q shards (2 by default) with n copies (3 by default)
Replication
Multi-primary from changes feeds, one-off or continuous; conflicting revisions kept
Storage engine
Append-only B-tree files, compacted periodically

Alternatives

What all document databases have in common →Compare side by side →
MongoDBCommercialA document database that stores JSON-like records with a flexible schema, from one replica set to a sharded cluster.SurrealDBCommercialA multi-model database in Rust that stores documents, graph edges, vectors and time series in one engine, queried with an SQL-like language, SurrealQL, and able to run embedded, as a server or as a cluster.RealmDeprecatedOpen sourceAn embedded object database for mobile apps, a replacement for SQLite and Core Data, whose cloud sync service MongoDB shut down in 2025.Amazon DynamoDBAWSAlso good for writes in several regions at onceAWS’s serverless key-value and document database, with single-digit-millisecond reads at any size.DocumentDBOpen sourceA MongoDB-compatible document database built as PostgreSQL extensions plus a gateway, so MongoDB drivers and tools talk to Postgres underneath.RethinkDBDormantOpen sourceA clustered JSON document database whose queries can stay open as changefeeds, pushing every change to the client instead of the app polling for it.FaunaArchivedCommercialA serverless, globally replicated document database with strictly serializable transactions and its own query language, FQL; the service shut down in May 2025.

How it fits with other technologies

Write a document, index a field and query it with Mango · bash

DB=http://admin:secret@localhost:5984/books
curl -X PUT $DB                                   # create the database

curl -X PUT $DB/dune -H 'Content-Type: application/json' \
  -d '{"title": "Dune", "year": 1965}'
# {"ok":true,"id":"dune","rev":"1-..."}  send this _rev back to update it

curl -X POST $DB/_index -H 'Content-Type: application/json' \
  -d '{"index": {"fields": ["year"]}, "name": "year-index", "type": "json"}'

curl -X POST $DB/_find -H 'Content-Type: application/json' \
  -d '{"selector": {"year": {"$gt": 1960}}, "fields": ["_id", "title"], "sort": [{"year": "asc"}]}'

# keep a copy on another server in sync, in one direction, until cancelled
curl -X POST http://admin:secret@localhost:5984/_replicate -H 'Content-Type: application/json' \
  -d '{"source": "books", "target": "http://admin:secret@backup:5984/books", "continuous": true}'

See it in a real stack

No architecture uses Apache CouchDB yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2005–2026

Damien Katz, who had worked on Lotus Notes at IBM, started CouchDB in April 2005 and funded it himself for almost two years. It was a database of JSON documents with an HTTP API and peer-to-peer replication, designed so that separate copies could be edited apart and brought back together. It entered the Apache Incubator in February 2008 and became a top-level project that November. The first stable release, 1.0, came in July 2010.

At the NoSQL meetup in San Francisco in June 2009, CouchDB was one of the databases presented alongside Cassandra, HBase and MongoDB. Katz left in early 2012 to work on Couchbase Server, a separate product. Cloudant, which ran CouchDB as a service, had built a clustered version called BigCouch on ideas from Amazon’s Dynamo paper, and contributed it to Apache in 2013.

That code became CouchDB 2.0 in September 2016, which added native clustering, the Mango query language and a new web console, Fauxton. The project has continued under Apache since, with 3.x releases.

Why it’s built this way

Replication as the core feature
Every database can sync with any other in either direction, incrementally, from a server cluster down to PouchDB in a browser, so an app can keep working on its own copy while offline.
Keep conflicts instead of rejecting writes
Disconnected copies will be edited at the same time. Storing both revisions and choosing the same winner everywhere means replicas converge without coordination, and no edit is silently lost.
HTTP and JSON as the only interface
Any language and any web tool could talk to it without a driver, and HTTP caching and proxies work unchanged.
Append-only storage
Never overwriting committed data makes crashes safe and lets readers see a consistent snapshot without locks, at the price of compaction.

Timeline

  1. 2005

    Damien Katz starts CouchDB

  2. 2008

    Enters the Apache Incubator in February and graduates in November

  3. 2009

    Presented at the first NoSQL meetup in San Francisco

  4. 2010

    CouchDB 1.0, the first stable release

  5. 2013

    Cloudant’s clustered BigCouch code is merged into Apache CouchDB

  6. 2016

    CouchDB 2.0 adds clustering, Mango queries and Fauxton

  7. 2026

    CouchDB 3.5.3 released in October

Sources6 · facts checked 24 October 2026

Improve this page on GitHub