Apache CouchDB: replication you can watch happen
Seamless multi-primary syncing database with an intuitive HTTP/JSON API, designed for reliability
At a glance
- What is it?
- A document database whose defining feature is not its query language but its conflict model. Here is what the repository shows about the multi-primary design, the dev workflow, and the parts that still carry their Erlang history.
- Who is it for?
- CouchDB is the rare database where you can watch replication happen, and the repository makes clear that this is a deliberate architectural position rather than a feature bolted on. Writes go into a per-database append-only log, every node keeps its own, and any node can accept a write at any time, which is why conflicting revisions are a normal outcome that the API surfaces rather than hides.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly Erlang, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on October 11, 2026, and from our analysis. They are not legal advice.
Editorial analysis
What the repository is for, given that you did not come here to read it
Almost nobody reads the CouchDB source to learn how to use it. The README is written for two narrower audiences: people trying to install the thing and people who want to hack on it. Installation gets two pointer lines to `INSTALL.Unix` and `INSTALL.Windows` and a link to docs.couchdb.org. Everything else is developer workflow.
That is worth stating plainly because it changes what the repository can tell you. The README will not explain replication, conflicts or the query language. It will tell you, with unusual precision, how to get three CouchDB nodes running on your laptop, which is the detail that most database repositories bury in a wiki.
The tree explains the rest. This is an Erlang project with a Clojure or JavaScript front end: `src/` for the server, `bin/` for build tooling, `build-aux/`, `config/`, `rel/` for release assembly, `share/`, `dev/` for the development scripts, `test/`, and `extra/` which holds the `nouveau` Gradle-based interface tooling. There are two Makefiles, `Makefile` and `Makefile.win`, with a comment at the top of the first warning that edits to one must be mirrored in the other.
Three nodes and an optional proxy, in four commands
The manual setup section says you need to install the dependencies documented in the install docs and then run:
./configure && makeThen the part that is genuinely useful, because you do not need `make install`. The dev scripts spin up a local three-node cluster directly:
./dev/runThree nodes is not an arbitrary default. A single-node CouchDB demonstrates nothing about the thing that makes it interesting, so the default dev experience is already a cluster. You can point it at admin credentials or leave it in admin party mode:
./dev/run --admin=admin:admin
./dev/run --with-admin-party-pleaseAnd there is a caching proxy in front if you want one, which matters because a load balancer in front of a replicated database changes how you think about read routing:
./dev/run --with-haproxy --haproxy=/path/to/haproxyThe result is a local cluster listening on port 5984, CouchDB's well-known port. `make check` runs the test suite.
One documentation gap is worth naming: there is a note that the Fauxton admin interface cannot fix admin party mode by itself, so you have to start the cluster with the admin flag instead. Fauxton is the web admin UI, and this is the kind of small operational trap that the devcontainer path exists to avoid entirely.
The devcontainer is the recommended path, and that is a signal
The README leads with a VS Code Remote Containers badge that clones the source into a container volume and spins up a dev environment automatically. The container runs `./configure && make` the first time it is created, which the README acknowledges costs extra startup time and frames as a trade for being able to run the dev scripts and the test suite immediately.
A project that ships a devcontainer as the recommended path is telling you something about its build. CouchDB needs an Erlang toolchain, a JavaScript build, and platform-specific configuration, and getting all three right on an arbitrary laptop is real work. The devcontainer makes that work disappear behind an image, at the cost of a slower first start.
The build system itself is visible at the top of the Makefile and reflects that complexity. There are separate binaries for `rebar`, `rebar3` and `erlfmt`, plus a Gradle wrapper for the `extra/nouveau` tooling, all defaulting to paths under `bin/` and `extra/`. A `version.mk` is included first, and the version resolution logic has four branches depending on whether you are building from a tarball, a clean release tag, an RC tag, or a working tree.
That last branch is the interesting one. On a clean tag it uses the tag; otherwise it builds from `version.mk` plus a git SHA plus dirty status. In other words, a development build identifies itself as a development build, which is the behaviour you want from a database and do not always get.
What the design commits you to
The repository description says multi-primary syncing database with an intuitive HTTP/JSON API, and both halves of that phrase are a decision. Multi-primary means any node can accept a write, which means concurrent writes to the same document can arrive at different nodes independently. Syncing means those nodes reconcile later. The consequence is that a document can end up in conflict, and CouchDB's approach is to represent that explicitly rather than resolve it automatically behind your back.
This is the honest trade. You get an HTTP API you can drive with curl, documents that sync between sites or between a server and a browser without special machinery, and no single point of write availability. You give up transactions across documents, and you give up the ad hoc aggregation that document stores are usually criticised for, since the query interface is deliberately narrow rather than a general computation engine.
The comparison with MongoDB is the one people actually ask about, and the difference is less about feature lists than about where disagreement goes. MongoDB resolves concurrent writes with rules the server applies. CouchDB surfaces the conflict, keeps both revisions, and makes the application decide. Which is right depends entirely on whether your domain can express a merge. When it can, explicit conflict handling is the more honest design. When it cannot, you end up writing merge logic that a server-side rule would have done for you.
It is not a SQL database, and no amount of MapReduce or view language will change that. If your workload is reporting across joins, this is the wrong tool and it is better to say so early.
Support, sponsorship and the export paperwork
The README's acknowledgements section lists the organizations that support the project: IBM Cloudant, MacStadium, Neighbourhoodie, DigitalOcean and netcup. For a database whose most recognizable commercial descendant is a hosted service, that is a reasonable map of who depends on it.
Support channels are listed plainly rather than vaguely. There is a mailing list reached through couchdb.apache.org, an IRC channel on Libera Chat, and a troubleshooting page under the install docs for cryptic error messages. The docs site also carries a changelog at a whatsnew URL, which is where release notes live given that this repository records no releases of its own.
The last section of the README is the one that surprises people: a cryptographic software notice. CouchDB ships an HTTP client called ibrowse with SSL functionality, and because that makes the distribution fall under US export control, the README spells out the ECCN classification, the License Exception it relies on, and a pointer to the Wassenaar Arrangement. The notice is careful to say the classification describes the software's cryptographic functionality rather than accusing anyone of anything, and it tells you to check your own country's rules before deploying it.
It is an unusual thing to find in a database README and a reminder that Apache-2.0 covers the code, not the regulatory context around it.
Where the state of the project is actually recorded
The repository itself is honest that it is not where to learn the current version. There are no releases recorded, and the version information is assembled at build time by the Makefile from a tag, a git SHA and dirty status. That is a well-behaved build system doing the right thing, but it does mean the definitive record of what shipped is the changelog on docs.couchdb.org under the whatsnew section.
The project is not archived. The last recorded push on the default branch is 2026-09-21, with roughly 7,000 stars, about 1,080 forks and 377 open issues. The topic tags still list Erlang, HTTP, JavaScript, database, big-data and cloud, which is a fair description of the project as a whole even though the interesting engineering today is the replication and clustering layer rather than the storage format.
Two directories are worth watching if you go looking. `test/` is where the cluster behaviour is exercised, which for a database with a multi-primary model is the only part of the test suite that matters much. And `dev/` contains the scripts that make a three-node cluster cheap, which is quietly the highest-leverage contribution anyone could make to this project, because it is what lets everyone else reproduce the replication behaviour locally rather than theorize about it.
If you want to evaluate this rather than read about it, the devcontainer path gets you a replicated three-node cluster on port 5984 faster than any document will.
Editorial conclusion
CouchDB is the rare database where you can watch replication happen, and the repository makes clear that this is a deliberate architectural position rather than a feature bolted on. Writes go into a per-database append-only log, every node keeps its own, and any node can accept a write at any time, which is why conflicting revisions are a normal outcome that the API surfaces rather than hides. The cost is that you give up joins and ad hoc aggregation, and the practical test is whether your data is document-shaped and your writes are conflict-tolerant. For development, the devcontainer plus the dev scripts get a three-node cluster with optional haproxy in front on port 5984, which is the fastest way to see the replication model for yourself. The repository records no releases here, so the changelog on docs.couchdb.org and the last recorded push on 2026-09-21 are where current state lives.
Frequently asked questions
What is CouchDB used for?
It is used where documents have to converge between places that are not always talking to each other: a server and a browser, an edge site and a datacenter, or two offices with a slow link between them. Multi-primary writes with later syncing is the design, and the HTTP and JSON API means no special client library is needed to drive it.
What is the difference between MongoDB and CouchDB?
The difference is where disagreement goes. MongoDB applies server-side rules to resolve concurrent writes on the same document. CouchDB keeps both revisions, marks the document as conflicted, and leaves the merge to your application. That is more honest and more work, and it suits domains where you can express a merge.
Is CouchDB a SQL database?
No. It is a document database with a deliberately narrow query interface built around views, and there are no joins across documents and no ad hoc aggregation over arbitrary fields. If your workload is reporting across joined tables, this is the wrong shape of tool.
What are the disadvantages of CouchDB?
Three stand out. Concurrent writes to the same document can conflict, and resolving them is application work rather than a server rule. There is no multi-document transaction, so a change that must touch several documents atomically is awkward. And the query surface is narrow, so the kind of arbitrary reporting SQL makes easy will need to be restructured or done elsewhere.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/apache-couchdb)