Trying out CouchDB for the first time

CouchDB is a document-oriented database written in the Erlang programming language. It is a NoSQL product designed for local replication and to scale vertically along a wide range of devices.

There are several good libraries that will abstract accessing CouchDB from various programing languages. However, in order to understand what goes on in the libraries, I think it is important to first understand what is going on on a lower lever, so that is what I will show you.

Step 1, install CouchDB. CouchDB for OSX can be downloaded here, the bundle contains bouth the Erlang runtime and CouchDB – no compiling or installing needed, just download the .dmg, mount it and run the application! If you are on Linux it is quite likely that CouchDB is in the repository of your distribution. In Ubuntu CouchDB is found in “Universe” and can easily be installed using apt. I haven’t tried CouchDB on Windows so I can’t give you any guidance here, if you try it out, please leave a comment.

Now when CouchDB is installed lets explore it using use one of my favorite tools, good old cURL. Port 5984 is the default port for CouchDB.

$ curl -X GET http://localhost:5984/
{"couchdb":"Welcome","version":"0.10.0"}

CouchDB is up running! Lets create a new database:

$ curl -X PUT http://localhost:5984/testdb
{"ok":true}

CouchDB’s responses are also in JSON form. Lets inspect the database we just created:

$ curl -X GET http://localhost:5984/testdb
{
  "db_name":"testdb",
  "doc_count":0,
  "doc_del_count":0,
  "update_seq":0,
  "purge_seq":0,
  "compact_running":false,
  "disk_size":79,
  "instance_start_time":"1266963717052501",
  "disk_format_version":4
}

CouchDB returns some statistics of the database, we can see that it contains 0 documents. Lets store an empty document in the database:

$ curl -X POST http://localhost:5984/testdb/ -H "Content-Type: application/json" -d {}
{
  "ok":true,
  "id":"ef40feff87010a6ef3a45a16df5af977",
  "rev":"1-967a00dff5e02add41819138abb3284d"
}

CouchDB returns the unique id for the document and the version number (did i mention that all documents are version controlled?:)). Next step is to fetch all documents:

$ curl -X GET http://localhost:5984/testdb/_all_docs
{
  "total_rows":1,
  "offset":0,
  "rows":[{
    "id":"ef40feff87010a6ef3a45a16df5af977",
    "key":"ef40feff87010a6ef3a45a16df5af977",
    "value":{"rev":"1-967a00dff5e02add41819138abb3284d"}
  }]
}

Yes! it is there! Now you should also be able to see your database “testdb” and the document you created in the CouchDB GUI.