Port 5984: CouchDB — The Database That Speaks HTTP

Port 5984 is where your database becomes a web server. Every document gets a URL. Every query is an HTTP request. Every response is JSON. This is CouchDB, and it treats the web not as something to integrate with, but as the foundation itself.

What Runs on Port 5984

CouchDB's HTTP API listens on port 5984 by default. When you connect to this port, you're not connecting to some proprietary binary protocol. You're making HTTP requests.¹ GET /database/document retrieves a document. PUT /database/document creates or updates one. DELETE /database/document removes it. The database is the web server. The web server is the database.

# Get server info
curl http://localhost:5984/

# Create a database
curl -X PUT http://localhost:5984/mydb

# Store a document
curl -X PUT http://localhost:5984/mydb/doc1 -d '{"name": "hello"}'

# Retrieve it
curl http://localhost:5984/mydb/doc1

This isn't an API bolted onto a database. The HTTP protocol is the database protocol. CouchDB follows RFC 2616 (HTTP 1.1) with complete fidelity.² ETags are revision numbers. Conditional requests work exactly as the spec intends. Load balancers and proxies work without modification because they already speak the language.

The Insight That Started Everything

In April 2005, Damien Katz posted on his blog about a new database engine he was building. He called it CouchDB: Cluster Of Unreliable Commodity Hardware.³ The name was ambitious. The project was self-funded. Katz had quit his job at IBM, where he'd worked on Lotus Notes, to build something better.

Lotus Notes is one of the most misunderstood pieces of software ever created. Most people remember it as clunky email software. But underneath was something remarkable: a document database with multi-master replication that actually worked. You could take your laptop offline, edit documents, and sync them back days later. In the 1990s. On dialup.

Katz understood what Notes got right and what it got wrong. "Notes is a wonderful concept," he observed, but the implementation had calcified.⁴ The replication was brilliant. The architecture was not. He wanted to keep the synchronization magic and rebuild everything else on modern foundations.

"The replication stuff is the killer feature," Katz said later. "A lot of databases have some sort of replication capability, almost always master/slave, so reads can be spread across servers. CouchDB uses peer-based replication, so any update can happen on any node and automatically replicate out. We have the ability to take a database offline, individually query it, then push that back to the replicas. It's fairly unique in the database world."⁵

How CouchDB Actually Works

CouchDB stores JSON documents. Not rows. Not columns. Documents. Each document is a self-contained unit with its own structure. You don't define schemas upfront. You just store data.

Every document has two required fields: _id (a unique identifier) and _rev (a revision string). The revision system is the key to everything CouchDB does.⁶

When you update a document, you don't modify it in place. You create a new revision. The old revision still exists in the tree. This Multi-Version Concurrency Control (MVCC) means readers never block writers, writers never block readers, and concurrent modifications can be detected and resolved rather than corrupted.

To update a document, you must provide the current _rev. If someone else modified the document since you read it, your update fails with a 409 Conflict. This is optimistic locking at the HTTP level. No transactions needed. No connection state to manage. Just ETags and conditional requests, exactly as HTTP intended.

Views and MapReduce

CouchDB queries data through views, which are JavaScript MapReduce functions stored in design documents:

// A map function that indexes documents by author
function(doc) {
  if (doc.type === 'post') {
    emit(doc.author, doc.title);
  }
}

Views are pre-computed and incrementally updated. Query a view and you get results in logarithmic time regardless of database size. The first query builds the index. Subsequent queries are fast.

Why Erlang

CouchDB is written in Erlang, a language designed by Ericsson for telephone switches in the 1980s. This choice seems strange until you understand what telephone switches need: they must handle thousands of concurrent connections, never crash, and update themselves while running.

Erlang's actor model means every request runs in an isolated process. If one request crashes, it crashes alone. The database keeps running.⁷ "Regarding concurrent connections, you can have as many as the number of sockets that your operating system can handle, but latency will go up. There is no point where it crashes and burns. This is a property from Erlang."⁸

Erlang's "let it crash" philosophy sounds reckless but produces remarkably stable systems. Instead of defensive programming that tries to anticipate every error, you build supervision trees that restart failed processes cleanly. Telephone switches run for years without downtime. CouchDB inherits this resilience.

The Replication Protocol

CouchDB's replication protocol is HTTP-based and peer-to-peer. No master. No slave. Just peers that can sync in either direction.⁹

# Replicate from source to target
curl -X POST http://localhost:5984/_replicate \
  -d '{"source": "db1", "target": "http://remote:5984/db1"}'

The protocol works over the same HTTP API that everything else uses. Two CouchDB instances can synchronize through firewalls, proxies, and load balancers because they're just making HTTP requests to each other. Set up replication in both directions and you have multi-master sync.

When conflicts occur (two nodes modify the same document while disconnected), CouchDB doesn't lose data. It keeps all revisions and deterministically picks a winner that every node will agree on.¹⁰ The losing revisions remain accessible so applications can merge them or present the conflict to users.

This protocol became the foundation for PouchDB, a JavaScript implementation that runs in browsers. Your web application can store data locally, work offline for days, then sync everything back when connectivity returns.¹¹ The same protocol works on phones, Raspberry Pis, and data centers.

The Security Reality

CouchDB's history includes some serious vulnerabilities that administrators must understand.

CVE-2017-12635 and CVE-2017-12636 allowed privilege escalation and remote code execution in versions before 2.1.1. A difference in how Erlang and JavaScript parsed JSON meant attackers could create admin accounts by sending specially crafted requests.¹²

CVE-2022-24706 was rated 9.8 out of 10 for severity. Default CouchDB installations used a predictable Erlang cookie ("monster"), allowing unauthenticated attackers to gain admin privileges and execute arbitrary code. Within days of public disclosure, attackers were exploiting it to install cryptocurrency miners.¹³

The pattern in these vulnerabilities reveals CouchDB's design trade-off: simplicity and accessibility over security defaults. A fresh CouchDB installation accepts anonymous connections. The admin interface is wide open. This makes development easy and production deployment dangerous.

Essential hardening:

• Enable require_valid_user to block anonymous access
• Change the default Erlang cookie immediately
• Block port 4369 (EPMD) from external networks
• Use HTTPS (port 6984) for production traffic
• Put CouchDB behind a firewall or reverse proxy

Related Ports

Current Status

CouchDB is an Apache Top-Level Project, actively maintained with regular releases. IBM Cloudant runs a managed CouchDB-compatible service that powers "hundreds of thousands of service instances" managing "multiple petabytes of active application data."¹⁴ The BBC, Apple, and CERN use CouchDB in production.¹⁵

The ecosystem has matured around offline-first applications. PouchDB provides browser and Node.js sync. Couchbase (founded by Katz after leaving Apache CouchDB) offers an enterprise variant. The replication protocol has proven resilient enough that the Red Cross uses CouchDB for disaster relief applications where connectivity cannot be guaranteed.¹⁶

Port 5984 was officially assigned by IANA in November 2007.¹⁷ It remains the standard entry point for one of the Internet's most philosophically committed databases: a system that took HTTP seriously as an application protocol before that was fashionable, built synchronization as a core feature rather than an afterthought, and trusted that the web's protocols were sufficient for the web's data.