Open Source Apache CouchDB: Another JSON Document DBMS

Main Features

ACID Semantics

CouchDB provides ACID semantics. It does this by implementing a form of Multi-Version Concurrency Control, meaning that CouchDB can handle a high volume of concurrent readers and writers without conflict.

Built for Offline

CouchDB can replicate to devices (like smartphones) that can go offline and handle data sync for you when the device is back online.

Distributed Architecture with Replication

CouchDB was designed with bi-directional replication (or synchronization) and off-line operation in mind. That means multiple replicas can have their own copies of the same data, modify it, and then sync those changes at a later time.

Document Storage

CouchDB stores data as "documents", as one or more field/value pairs expressed as JSON. Field values can be simple things like strings, numbers, or dates; but ordered lists and associative arrays can also be used. Every document in a CouchDB database has a unique id and there is no required document schema.

Eventual Consistency

CouchDB guarantees eventual consistency to be able to provide both availability and partition tolerance.

Map/Reduce Views and Indexes

The stored data is structured using views. In CouchDB, each view is constructed by a JavaScript function that acts as the Map half of a map/reduce operation. The function takes a document and transforms it into a single value that it returns. CouchDB can index views and keep those indexes updated as documents are added, removed, or updated.

HTTP API

All items have a unique URI that gets exposed via HTTP. It uses the HTTP methods POST, GET, PUT and DELETE for the four basic CRUD (Create, Read, Update, Delete) operations on all resources.

CouchDB also offers a built-in administration interface accessible via Web called Fauxton.

Special Features

CouchDB implements a form of multiversion concurrency control (MVCC) so it does not lock the database file during writes. Conflicts are left to the application to resolve. Resolving a conflict generally involves first merging data into one of the documents, then deleting the stale one.

Other features include (incremental) MapReduce, and (incremental) replication. One of CouchDB's distinguishing features is multi-master replication, which allows it to scale across machines to build high-performance systems. A built-in Web application called Fauxton (formerly Futon) helps with administration.

Installing CouchDB on Ubuntu Linux

Update Your System

Your system packages must be updated to the newest version. Run the following command:

sudo apt-get update && sudo apt-get upgrade

Install Software Properties Common Package

Next, install the software-properties-common package. This package provides an abstraction of the used apt repositories and allows you to manage distribution and independent software vendor software sources easily. Use the following command:

sudo apt-get install software-properties-common

Add CouchDB Repository

After installing the software-properties-common package, import the GPG key. Run the following command:

curl https://couchdb.apache.org/repo/keys.asc | gpg --dearmor | sudo tee /usr/share/keyrings/couchdb-archive-keyring.gpg >/dev/null

Then, using the signed-by option to specify the keyring file, we will add the CouchDB on Ubuntu repository:

echo "deb [signed-by=/usr/share/keyrings/couchdb-archive-keyring.gpg] https://apache.jfrog.io/artifactory/couchdb-deb/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/couchdb.list

Install CouchDB

Now, you're ready to install CouchDB. Use the following command:

sudo apt-get update && sudo apt-get install couchdb

(126MB of data on hard disk.)

During the installation, you'll be asked to select the type of CouchDB installation. You can choose between a standalone or clustered setup. If you're installing CouchDB on a single server, select ‘standalone'. For multiple servers, select ‘clustered'. If your CouchDB instance is a standalone installation, you can input any string value as the cookie. This value will not matter unless you are setting up a cluster of CouchDB instances.

During installation, I make the following choices:

1. standalone, not cluster.
2. I choose magic cookie skyblue.
3. I bind to IP address 127.0.0.1
4. Password for the admin user: skyblue

Further Configure CouchDB on Ubuntu

After successful installation, open your web browser and navigate to http://localhost:5984/_utils/. This will open the CouchDB interface, Fauxton. Here, you can configure your CouchDB installation further.

To allow external access, you need to modify the CouchDB configuration file to bind the HTTP server to all network interfaces.

Open the local.ini file with a text editor:

sudo nano /opt/couchdb/etc/local.ini

Find the section [chttpd] and change the bind_address from 127.0.0.1 to 0.0.0.0:

[chttpd]
port = 5984
bind_address = 0.0.0.0

Save the file and exit the text editor.

Restart CouchDB for the changes to take effect:

sudo systemctl restart couchdb

(Alternatively, check status with: systemctl status couchdb)

Now, you should be able to access the CouchDB web interface from any machine in your network using the server IP address and port 5984. Make sure your network allows inbound connections to this port.

Verifying the Installation

To verify the installation of CouchDB, use the curl command:

curl http://127.0.0.1:5984/

If the installation is successful, you'll get a response similar to this:

{"couchdb":"Welcome","version":"3.3.2","git_sha":"11a234070","uuid":"db4a4dee584977354d66c0eecf184718","features":["access-ready","partitioned","pluggable-storage-engines","reshard","scheduler"],"vendor":{"name":"The Apache Software Foundation"}}

First Steps with CouchDB: Access CouchDB Using HTTP API Endpoints (curl)

You can access CouchDB using the HTTP API to send database standard GET and PUT requests to the backend server. Follow the steps below to use the Curl utility with the -u option to prompt you for the administrator password for every API request to the CouchDB localhost port 5984.

Use the -X flag to specify a method (like GET or PUT) for curl.

1. Get a list of all databases

   $ curl -u admin:skyblue -X GET http://127.0.0.1:5984/_all_dbs

   Output:

   ["exampledb"]

2. Create a new database

   Such as test_database.

   $ curl -u admin:skyblue -X PUT http://127.0.0.1:5984/my_database

   Output:

   {"ok":true}

3. Delete a database

   For example, test_database.

   $ curl -u admin:skyblue -X DELETE http://127.0.0.1:5984/my_database

4. Retrieve database information

   $ curl -u admin:skyblue http://127.0.0.1:5984/my_database

5. Create a new document in a database

   Replace the -d option value with your own JSON document data.

   $ curl -u admin:skyblue -X POST -H "Content-Type: application/json" -d '{"name": "John Doe"}' http://127.0.0.1:5984/my_database

   ---

   When adding a document to the database you may specify the unique ID of the record you want to create, then use -d to pass along the record's information in JSON format.

6. Get a document's JSON data stored

   To GET a document, specify the document's ID at the end of the URL.

   Replace test_database,ff66 with your database and document ID values respectively.

   $ curl -u admin:skyblue http://127.0.0.1:5984/my_database/ff66

   ---

   Alternatively, you may pass in an object with a selector key matching an object after switch -d. In that case, remember to include a content type specification (-H "Content-Type: application/json"). For example:

   curl -u admin:skyblue  -X POST -H "Content-Type: application/json" http://127.0.0.1:5984/computing/_find -d '{"selector": { "term": "ethereum"}}'

   What about adding a "fields": ["term", "name", "definition"] key-value pair?

   curl -u admin:skyblue  -X POST -H "Content-Type: application/json" http://127.0.0.1:5984/computing/_find -d '{"selector": { "term": "ethereum"}, "fields": ["term", "name", "definition"]}'

   Last, you may make the selector match an empty object and only include the "fields" key-value pair:

   curl -u admin:skyblue  -X POST -H "Content-Type: application/json" http://127.0.0.1:5984/computing/_find -d '{"selector": {}, "fields": ["term", "name", "definition"]}'

7. Delete a document

   Replace ff66 with your document ID and 1-b9a5713ff0a5b6eee4347d4040a7f6bf with your actual revision number.

   $ curl -u admin:skyblue -X DELETE http://127.0.0.1:5984/my_database/ff66?rev=1-b9a5713ff0a5b6eee4347d4040a7f6bf

8. Get all documents in a database such as test_database

   $ curl -u admin:skyblue http://127.0.0.1:5984/my_database/_all_docs

9. Compact a database

   $ curl -u admin:skyblue -X POST -H "Content-Type: application/json" http://127.0.0.1:5984/my_database/_compact

10. Get active tasks

    $ curl -u admin:skyblue http://127.0.0.1:5984/_active_tasks

Fauxton

Welcome to Futon!

After having seen CouchDB's raw API, let's get our feet wet by playing with Futon, the built-in administration interface. Futon provides full access to all of CouchDB's features and makes it easy to work with some of the more complex ideas involved. With Futon we can create and destroy databases; view and edit documents; compose and run MapReduce views; and trigger replication between databases.

To load Futon in your browser, visit (locally):

http://127.0.0.1:5984/_utils/