User Tools

Site Tools



CouchDB is a member of the NoSQL (“Not only SQL”) database family. It stores schemaless documents instead of records in predefined formats. It also supports the Map-Reduce programming paradigm that lets you search big amounts of data in parallel.

A nice feature of CouchDB is that it comes with a RESTful HTTP interface that allows you to start issuing request right away with a browser or 'curl'.


apt-get install couchdb

After that CouchDB listens on localhost port 5984 by default.

You can verify that CouchDB is running by issuing:

curl http://localhost:5984/

If CouchDB is running you will be greeted with a JSON document telling you the version of CouchDB.

Quick Tutorial

We are going to create a small inventory database for a hobby workshop. We will add and query parts in this inventory.

Creating a database

Before we can do anything useful with CouchDB, we need a database:

curl -vX PUT http://localhost:5984/inventory

Adding and updating documents

Now we are going to create the first entry in the database by using HTTP POST:

curl -X POST http://localhost:5984/inventory/ -d '{"type":"part","article_name":"MFT/3-ZK","friendly_name":"Zusatzklemmung","amount":"1","part_number":"495541","ean":"4014549099421","manufacturer":"Festool"}' -H 'Content-Type:application/json'

We could have used HTTP PUT instead of POST - which is in fact recommended, because PUT is safer in case the request is repeated. But POST automatically generates a unique document ID. The document ID is the key that identifies the document inside of your CouchDB database. You will notice it in the URLs later.

So now we are going to repeat the same command with PUT instead of POST. Later we are going to delete the duplicate entry.

curl -X PUT http://localhost:5984/inventory/festool.mft_3_zk -d '{"type":"part","article_name":"MFT/3-ZK","friendly_name":"Zusatzklemmung","amount":"1","part_number":"495541","ean":"4014549099421","manufacturer":"Festool"}'

CouchDB answers with a JSON document that contains the revision ID of the document you just stored. Write it down, we are going to need it in a second.

Oops, we forgot to add the manufacturer. No problem though, we can just write a new revision of the document using the same URL.

curl -X PUT http://localhost:5984/inventory/festool.mft_3_zk -d '{"_rev":"revision-id","type":"part","article_name":"MFT/3-ZK","friendly_name":"Zusatzklemmung","amount":"1","part_number":"495541","ean":"4014549099421","manufacturer":"Festool"}'

Make sure to replace the revision-id placeholder with the ID you wrote down earlier.

Reading documents

How do we read the entry? You probably already guessed it:

curl -X GET http://localhost:5984/inventory/festool.mft_3_zk

You can drop the -X GET part since this is curl's default behavior. It has been added here for demonstration purposes.

Using the built in web GUI: Futon

While using curl is perfect to get a feeling for the HTTP API, at some point the typing effort gets cumbersome.

Introducing: Futon. Just open the following URL in your browser an you get a simple web frontend for managing your database and documents.

couchdb.txt · Last modified: 2015/05/17 17:44 (external edit)