Apache CouchDB Tutorial

Welcome to CouchDB Tutorial. In this CouchDB Tutorial, we will learn how to install CouchDB, create database in CouchDB, create documents in a database, replication between CouchDBs, configure databases, and many other concepts.

What is CouchDB?

  • CouchDB is a NoSQL Database that uses JSON for documents.
  • CouchDB uses JavaScript for MapReduce indexes.
  • CouchDB uses HTTP for the REST API.

CouchDB Installation

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

CouchDB Tutorial - Download CouchDB

When you click on the download button, it scrolls to the section, where based on your Operating System, you can download the installer.

CouchDB tutorial - CouchDB Download setup file for your Operating System

In this tutorial, we have downloaded for Windows (x64), and it should not make any difference if you download for macOs or Debian/Ubuntu/RHEL/CentOS.

Double click the downloaded installer and follow through the steps.

Once the installation is complete, you can check if CouchDB is installed successfully by requesting the URL http://127.0.0.1:5984/ in your browser.

CouchDB Tutorial - Installation Successful

This is CouchDB saying welcome to you, along with information about CouchDB version, GIT hash, UUID, features and vendor.

Fauxton

Fauxton is a web based interface built into CouchDB. You can do actions like creating and deleting databases, CRUD operations on documents, user management, running MapReduce on indexex, replication between CouchDB instances.

You can access CouchDB through Fauxton available at the URL  http://127.0.0.1:5984/_utils/.

CouchDB Web Interface

Here you can access the following tabs in the left menu.

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

Create Database in CouchDB

To create a CouchDB Database, click on Databases tab in the left menu and then click on Create Database.

CouchDB Tutorial - Create Database

After you click on the ‘Crete Database’ button, a pop up appears as shown below.

CouchDB Tutorial - Create Database

Enter the database name you like to create and click on Create button.

CouchDB Database tutorial

Now that a Database is created. We shall look into Documents inside Database.

Create a Document in CouchDB Database

To create a document in database, click on the Create Document button.

CouchDB Tutorial - Create Document

Now you will see a JSON document as shown below, with _id field pre-populated.

CouchDB Tutorial - Create Document JSON

You may keep the _id as is, or you can change. You can add more fields to the JSON document. And click on Create Document button.

CouchDB Tutorial - Create New Document

View documents of CouchDB Database

You can view the documents of CouchDB Database in three views.

  1. Table
  2. Metadata
  3. JSON

Table

The table view contains all the key values across documents as column names and their corresponding values for each document as row.

CouchDB Tutorial - View Documents - Table

Metadata

The Metadata view contains id, key and value as columns.

CouchDB Tutorial - View Documents - Metadata

JSON

The JSON view shows every document in JSON format.

You can see here clearly what each document is comprised of, other than the value we provide while creating a document. The meta information consists of id, key and value fields. The doc field is the actual document we provide when we created a document in this database.

CouchDB Tutorial - View Documents - JSON

Update CouchDB Document

To update CouchDB Document, from any of the View (Table, Metadata, or JSON), click on the document you would like to edit.

CouchDB Tutorial - Edit Document

You can edit any of the fields. We will change tutorial field to Apache CouchDB Tutorial and  number_of_topics to 9. Make the changes to fields and click on Save Changes button.

CouchDB Tutorial - Edit Document Fields

Once you click on Save Changes, a message Saving document. is displayed.

CouchDB Tutorial - Saving Document

You can also add new fields to the document.

Accessing CouchDB Database through REST API

You can access CouchDB Database through REST API using HTTP requests like GET, PUT, etc., for operations like view, update and delete operations.

View Document – GET request

To get Document, send a GET request to the document URL http://hostname_or_IP:Port/databasename/document_id.

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

CouchDB Tutorial - HTTP - GET Document

Update Document – PUT request

To update Document, send a PUT request with the document URL (http://hostname/databasename/document_id/) and pass the JSON data for update in the body.

URL

Body

Get “_rev” for the document which you would like to edit and send it along with the fields with updated values.

CouchDB Tutorial - HTTP - Update Document

In the response, ok field is true, which means the update is successful. Also the revision field rev is updated to 4-xxxxx meaning fourth revision.

To verify the document update, you may send GET request with the database and document id in url.

CouchDB Tutorial - GET document updated

Delete Document

To delete document from CouchDB Database, send HTTP DELETE request with the url http://hostname/database_name/document_id/ with parameter ver.

We made HTTP GET request in the above section where we updated the document. We will delete that document, hence use the _id and _ver.

CouchDB Tutorial - HTTP - DELETE Document

In the response, we get ok field with true value. Therefore, the document is deleted. The response also contains the document id and revision number.

Concluding this CouchDB Tutorial

Summarizing what we have learned in this CouchDB Tutorial: What CouchDB is? How to install CouchDB, How to create a database, How to create Document in Database, and the CRUD operations using web interface and HTTP requests.