Shahzad Bhatti Welcome to my ramblings and rants!

September 2, 2009

Introduction to CouchDB

Filed under: Computing — admin @ 6:51 pm

I have been following growth and popularity of CouchDB for a while and even attended an excellent talk by J Chris Anderson of However, only recently I am getting chance to actually use it. I am building an internal Search Engine based on Lucene, but I am storing documents in CouchDB. Though, CouchDB is pretty easy to setup, but its documentation is sporadic. Here are basic steps to get it running:

Installation and Launch

I installed CouchDB on my MacPro notebook using:

 sudo port install couchdb

CouchDB is available for Linux distributions and you can use yum or apt to install it, though official binaries are not available for Windows. You can also setup to load it at startup on Mac usng:

 sudo launchctl load -w /opt/local/Library/LaunchDaemons/org.apache.couchdb.plist

Once you installed it, you can start the couchdb server using:

 sudo /opt/local/bin/couchdb

Alternatively, you can skip installation & launch and instead use hosting solution from using “booom-couch” password for private beta.

Verify Installation

Once couchdb is started you can point your browser to or type in:


As CouchDB uses JSON format for communication, it would show something like:


Alternatively, you can use curl to communication with couchd server:


Creating a database

CouchDB is REST based service, and you can review all APIs at CouchDB uses PUT operation to create a database, e.g.

 curl -X PUT

It will return


Based on REST principles, PUT is used when adding a new data where the resource is specified by the client. However, if you call this API again with the same arguments, it will return in error, e.g.:

 {"error":"file_exists","reason":"The database could not be created, the file already exists."}

Adding documents

Each document is a JSON object that consists of name value pairs. Also, each document is specified a unique identifier or uuid. You can generate uuid in your application or get it from the CouchDB server. For example, to generate 10 UUIDs, call

 curl -X GET

and it will return something like:


You can then add a document using:

 curl -X PUT -d '{"name":"Sally", "message":"hi there"}'

It will return verification message:


Note, it generated a version of the document. Alternatively, you can use POST request to add document using server-generated UUID, e.g.

 curl -X POST -d '{"name":"John", "message":"hi there"}'

That returns UUID and version of newly created object, e.g.


Also, you can add binaries such as images to the CouchDB as well, e.g.

 curl -vX PUT -d@image.jpg -H "Content-Type: image/jpg"

Reading documents

CouchDB uses GET operation to read the document and you pass the id of the document, e.g.

 curl -X GET

which returns

 {"_id":"152019530472f7b0b364367bc2ec571d","_rev":"1-3525253587","name":"Sally","message":"hi there"}

Updating documents

CouchDB uses optimistic locking to update documents so this version number must be passed when we update document. Also, CouchDB is append-only database so it will create a new version of the document upon updated. For example, if you type same command again you would see:

 {"error":"conflict","reason":"Document update conflict."}

In order to update the document, the version must be specified, e.g.

 curl -X PUT -d '{"_rev":"1-3525253587", "name":"Sally", "message":"hi there", "date":"September 5, 2009"}'

This will in turn, create a new version and will return:


Deleting document/database

You can delete a document using DELETE operation, e.g.

 curl -X DELETE -d '{"rev":"1-657551114"}'

Similarly, you can delete a database using:

 curl -X DELETE

Querying Documents

CouchDB uses Javascript based map and reduce functions to query and view documents, where map function takes a document object and returns (emits) attributes from the document. Here is simplest map function that returns entire document:

 function(doc) {
       emit(null, doc);

Here is another example, that returns names of people who posted to guestbook:

 function(doc) {
     if (doc.Type == "guestbook") {
         emit(null, {name:});

Reduce function is similar to aggregation functions in most relatinal databases, for example to count all names you could define map function as

 function (doc) {
     if (doc.Type == "guestbook") {
         emit(, 1);

and reduce function as

 function (name, counts) {
     int sum=0;
     for (var i=0; i<counts.length; i++) {
     return sum;

All Databases

You can list names of the database using:

 curl -X GET

You can also get all documents for a particular database (guestbook):

 curl -X GET

CouchDB also comes with a web based Futon application to create, update, and list databases and documents, simply go to and you will all databases in the system.
You can also control replication from that UI, which is pretty handy. Also, you can poll database changes using:

 curl -X GET ''

Also, you can get statistics using:

 curl -X GET

And Config via:

 curl -X GET


CouchDB is written in Erlang and uses many of internal features of Erlang such as replication of databases (that use Mnesia). In order to replicate, just create a database on another server, e.g.

 curl -X PUT

Then replicate using:

 curl -X POST -H 'Content-Type: application/json' -d '{"source":"guestbook", "target":""}'


You can add user/password based basic authentication by editing /opt/local/etc/couchdb/local.ini file. You will then need to pass user/password when accessing CouchDB server, e.g.

 curl -basic -u 'user:pass' -X PUT


I just started using CouchDB and I am still learning more advanced features and its capabilities in enterprise level environment. Though, it looks very promising, but I am keeping Berkely DB in the back pocket in case I run into severe issues.

No Comments »

No comments yet.

RSS feed for comments on this post. TrackBack URL

Leave a comment

You must be logged in to post a comment.

Powered by WordPress