Apache CouchDB Tutorial

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.

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

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.

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/.

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.

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

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

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.

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

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.

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.

Metadata

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

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.

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.

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.

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

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:

http://127.0.0.1:5984/tutorialkart/c4e8630bfa328d3132965bd7cd001dd1

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

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

Body

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

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

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.

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.

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

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.