Getting Started

Apache CouchDB Introduction

Learn CouchDB — the database that syncs. A document-oriented database with offline-first capabilities and built-in HTTP API.

What is Apache CouchDB?

Apache CouchDB is an open-source, document-oriented database that uses JSON for documents, JavaScript for queries (MapReduce), and HTTP for its API. What makes CouchDB unique is its emphasis on replication and sync — it was designed from the ground up to replicate data reliably between multiple instances, including offline mobile clients.

CouchDB's motto is "Relax" — it's designed to be reliable, and its architecture naturally handles the complexity of distributed data.

CouchDB vs. MongoDB

Both are document databases, but they have very different philosophies:

Feature	CouchDB	MongoDB
API	REST over HTTP	Custom binary protocol
Query language	MapReduce (JS) + Mango Query	Aggregation pipeline
Replication	Built-in, peer-to-peer, offline-first	Replica sets (primary-focused)
Offline sync	First-class (PouchDB integration)	Not built-in
Concurrency	MVCC (no locks)	Document-level locking
Best for	Sync-heavy, offline-first apps	General-purpose document storage

The HTTP API

CouchDB's entire interface is a REST API. Every database operation is an HTTP request. This makes it universally accessible from any language without a driver.

bash

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

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

# Create a document
curl -X POST http://admin:password@localhost:5984/mydb \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Get a document
curl http://admin:password@localhost:5984/mydb/DOC_ID

# Get all documents
curl http://admin:password@localhost:5984/mydb/_all_docs?include_docs=true

Document Revisions

Every CouchDB document has a _rev (revision) field. When you update a document, you must include the current _rev. This implements optimistic concurrency control — if two clients update the same document simultaneously, the second write will fail with a conflict (not silently overwrite).

json

{
  "_id": "user-alice",
  "_rev": "3-abc123",
  "name": "Alice Smith",
  "email": "alice@example.com"
}

This revision system is the foundation of CouchDB's replication — revisions allow the database to detect and handle conflicts when syncing between instances.

Running CouchDB

bash

# Docker
docker run -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=password \
  -p 5984:5984 -d couchdb:3

# Access the Fauxton web UI
open http://localhost:5984/_utils

Installing a Client

bash

npm install nano     # Official Node.js CouchDB client

javascript

import nano from 'nano';
const couch = nano('http://admin:password@localhost:5984');
const db = couch.db.use('myapp');

// Insert
const result = await db.insert({ name: 'Alice', role: 'user' });
console.log(result.id, result.rev);

// Read
const doc = await db.get(result.id);
console.log(doc);

Example

javascript

// Node.js with nano client
import nano from 'nano';

const couch = nano('http://admin:password@localhost:5984');

async function setupDb() {
  // Create database if it doesn't exist
  try {
    await couch.db.create('users');
  } catch (err) {
    if (err.statusCode !== 412) throw err; // 412 = already exists
  }
  return couch.db.use('users');
}

const db = await setupDb();

// Insert a document
const { id, rev } = await db.insert({
  name: 'Alice',
  email: 'alice@example.com',
  createdAt: new Date().toISOString(),
});

// Update (must include _rev)
await db.insert({ _id: id, _rev: rev, name: 'Alice Smith' });

Want to run this code interactively?

Try in Compiler