Apache CouchDB Tutorial

Apache CouchDB Tutorial

Apache CouchDB is a document-oriented NoSQL database that stores records as JSON documents and exposes database operations through an HTTP API. This tutorial explains how to install CouchDB, open the Fauxton administration interface, create a database, work with documents, and perform basic CRUD operations through HTTP requests.

The examples use a local CouchDB server at http://127.0.0.1:5984. A secured installation may require administrator credentials when you use Fauxton, Postman, or command-line tools.

How Apache CouchDB Stores and Serves Data

• CouchDB is a NoSQL database that stores documents in JSON format.
• Each document has a unique _id value and a revision value named _rev.
• CouchDB provides an HTTP-based API for creating databases and managing documents.
• Indexes and queries can be defined with design documents, MapReduce views, or Mango queries.
• Replication can copy and synchronize databases between CouchDB instances.

CouchDB uses multi-version concurrency control. When a document is updated or deleted, the request normally has to include its current revision value. This prevents one client from silently overwriting a newer change made by another client.

Install Apache CouchDB on Your Operating System

To install CouchDB, visit https://couchdb.apache.org/ and click the download button shown below.

The download section provides installation packages or instructions for supported operating systems. Select the appropriate option for Windows, macOS, Debian, Ubuntu, RHEL, CentOS, or another supported platform.

The screenshots in this tutorial use the Windows x64 installer. The administration and HTTP API concepts are the same on macOS and Linux, although installation steps and service commands differ.

Run the downloaded installer and complete the setup steps. Configure an administrator account when prompted and keep the username and password available for later requests.

Verify the CouchDB Server on Port 5984

After installation, open http://127.0.0.1:5984/ in a browser. If CouchDB is running and reachable, the server returns a JSON response containing information such as the CouchDB version, features, vendor, and instance identifier.

If the page does not load, confirm that the CouchDB service is running and that a firewall or another application is not blocking port 5984.

Manage CouchDB with the Fauxton Web Interface

Fauxton is the web-based administration interface included with CouchDB. It can be used to create and delete databases, manage JSON documents, configure indexes, inspect active tasks, administer users, and configure replication.

Open Fauxton at http://127.0.0.1:5984/_utils/. Sign in with the CouchDB administrator credentials when authentication is enabled.

Depending on the CouchDB version and configuration, the left menu can provide access to areas such as:

• All Databases
• Setup
• Active Tasks
• Configuration
• Replication
• Documentation
• Verify

Create a Database in Apache CouchDB

In Fauxton, open the databases section from the left menu and click Create Database.

Fauxton displays a dialog in which you can enter the database name.

Enter a valid database name and click Create. CouchDB database names should be lowercase and should avoid spaces. A simple name such as tutorialkart works for the examples in this tutorial.

After the database is created, open it to add and manage documents.

Create the Same CouchDB Database with an HTTP Request

A database can also be created by sending an HTTP PUT request to the database URL.

curl -X PUT http://admin:password@127.0.0.1:5984/tutorialkart

Replace admin and password with your credentials. Avoid placing production passwords directly in shell history; this inline form is shown only to make the local example easy to follow.

{"ok":true}

Create a JSON Document in a CouchDB Database

Open the database in Fauxton and click Create Document.

Fauxton opens a JSON editor. Depending on the interface version, an _id may be generated automatically or you may provide one yourself.

Keep the generated _id or replace it with a meaningful unique identifier. Add fields using valid JSON syntax, then click Create Document.

A document might contain fields such as the following:

{
  "_id": "couchdb-tutorial",
  "tutorial": "Apache CouchDB Tutorial",
  "category": "NoSQL Databases",
  "number_of_topics": 9
}

CouchDB adds a revision field named _rev after the document is saved. Applications should not invent revision values; they must use the current revision returned by CouchDB.

View CouchDB Documents in Fauxton

Fauxton can display database results in three common formats:

1. Table
2. Metadata
3. JSON

CouchDB Document Table View

The table view presents document fields as columns and document values as rows. It is convenient for scanning documents that have similar fields.

CouchDB Document Metadata View

The metadata view focuses on information returned for each row, including identifiers, keys, and values associated with the result.

CouchDB Document JSON View

The JSON view displays the complete response as JSON. When document bodies are included, the doc field contains the stored document, while fields such as id, key, and value describe the result row.

Update a CouchDB Document in Fauxton

From the table, metadata, or JSON view, select the document that you want to edit.

Edit the required fields without removing the current _id or _rev. In this example, the tutorial field is changed to Apache CouchDB Tutorial and number_of_topics is changed to 9. Click Save Changes after editing the JSON.

Fauxton displays a saving message while it sends the update to CouchDB.

After a successful update, CouchDB assigns a new _rev value. The new revision must be used for the next update or deletion of that document.

Access a CouchDB Database Through the REST API

CouchDB maps database and document operations to HTTP methods. Common operations use GET to read data, PUT or POST to create data, PUT to replace a document, and DELETE to mark a document as deleted.

The basic document URL format is:

http://hostname:port/database_name/document_id

Read a CouchDB Document with an HTTP GET Request

To retrieve one document, send a GET request to its database and document URL.

If you are using Postman, send a GET request with the following URL:

http://127.0.0.1:5984/tutorialkart/c4e8630bfa328d3132965bd7cd001dd1

The returned JSON contains the document fields together with the current _id and _rev.

Update a CouchDB Document with an HTTP PUT Request

To update a document, send a PUT request to its URL and include the complete replacement document in the request body. The body must contain the current _rev value.

URL

 http://127.0.0.1:5984/tutorialkart/c4e8630bfa328d3132965bd7cd001dd1/

Body

{
    "_rev": "3-729ec8f85148981fdf155cbc4d3e41fd",
    "tutorial": "CouchDB Tutorial",
    "category": "NoSQL Databases",
    "number_of_topics": 7
}

Retrieve the latest _rev before updating the document. If an old revision is submitted after another update has already occurred, CouchDB normally returns an HTTP 409 Conflict response.

In a successful response, ok is true and rev contains the newly generated revision. A prefix such as 4- indicates the document has reached a new revision generation; the complete revision token must be treated as an opaque value.

Send another GET request to verify the stored document and obtain its latest revision.

Delete a CouchDB Document with an HTTP DELETE Request

To delete a CouchDB document, send an HTTP DELETE request to the document URL and include the current revision in the rev query parameter.

Use the document’s _id and current _rev values from the most recent GET response.

http://127.0.0.1:5984/tutorialkart/c4e8630bfa328d3132965bd7cd001dd1/?rev=4-3a0d4167a3ccbdf5a017b975798f145f

A successful response contains "ok": true, the document identifier, and a new revision value. CouchDB records a deletion revision rather than immediately removing every trace of the document, which allows deletion information to participate in replication.

Create and Update CouchDB Documents with curl

The following command creates a document with a chosen identifier. The Content-Type header tells CouchDB that the request body contains JSON.

curl -X PUT http://admin:password@127.0.0.1:5984/tutorialkart/couchdb-tutorial \
  -H "Content-Type: application/json" \
  -d '{"tutorial":"Apache CouchDB Tutorial","category":"NoSQL Databases"}'

Read the document and note the returned _rev value:

curl http://admin:password@127.0.0.1:5984/tutorialkart/couchdb-tutorial

To update the document, send the complete document again with its current revision:

curl -X PUT http://admin:password@127.0.0.1:5984/tutorialkart/couchdb-tutorial \
  -H "Content-Type: application/json" \
  -d '{"_rev":"CURRENT_REVISION","tutorial":"Apache CouchDB Tutorial","category":"NoSQL Databases","number_of_topics":9}'

Replace CURRENT_REVISION with the exact _rev returned by CouchDB.

Query CouchDB Documents with Mango Selectors

CouchDB supports declarative JSON queries through the Mango _find endpoint. For example, the following selector requests documents whose category is NoSQL Databases.

{
  "selector": {
    "category": "NoSQL Databases"
  },
  "fields": ["_id", "tutorial", "category"]
}

Send this JSON body with a POST request to:

http://127.0.0.1:5984/tutorialkart/_find

Indexes should be created for fields used by frequent or large queries. Without an appropriate index, CouchDB may scan more documents than necessary.

Replicate a CouchDB Database Between Servers

Replication copies document changes from a source database to a target database. It can be configured as a one-time operation or as continuous replication. The source and target can be on the same CouchDB instance or on different reachable servers.

Replication can be configured through Fauxton’s Replication section. Provide the source database, target database, authentication details when required, and choose whether the replication should continue monitoring for changes.

Replication is directional. To keep two databases synchronized in both directions, configure replication from the first database to the second and a separate replication from the second database to the first.

Common CouchDB Errors During CRUD Operations

• 401 Unauthorized: The request does not contain valid credentials.
• 404 Not Found: The database, document, or endpoint does not exist at the requested URL.
• 409 Conflict: The document identifier already exists during creation, or an update uses an outdated or missing revision.
• Invalid JSON: The request body contains a syntax error or is sent without an appropriate JSON content type.
• Connection refused: CouchDB is not running, the host or port is incorrect, or network access is blocked.

Apache CouchDB Tutorial FAQs

What is the default port for Apache CouchDB?

CouchDB commonly listens on port 5984. A local server is therefore often available at http://127.0.0.1:5984, unless the configuration has been changed.

What are _id and _rev in a CouchDB document?

_id uniquely identifies the document inside a database. _rev identifies its current revision and is required for normal update and delete requests.

Why does CouchDB return a 409 Conflict response?

A conflict commonly occurs when a document is created with an existing identifier or when an update uses an old _rev. Retrieve the latest document, apply the intended changes, and submit the update with the current revision.

What is the difference between Fauxton and the CouchDB REST API?

Fauxton is a browser-based administration interface. It performs operations against CouchDB on your behalf. The REST API is the underlying HTTP interface used directly by applications, Postman, curl, and other clients.

Does deleting a CouchDB document remove it immediately?

A normal delete request creates a deletion revision so the deletion can be replicated. CouchDB later manages old revisions and storage through compaction and related maintenance processes.

Apache CouchDB Tutorial Summary

This Apache CouchDB tutorial covered installation, server verification, Fauxton, database creation, JSON documents, document views, updates, HTTP CRUD requests, revision handling, Mango queries, and replication. The key detail for reliable CouchDB updates and deletions is to use the document’s current _rev value.