At the Forge - CouchDB

Getting started with CouchDB, an increasingly popular non-relational database.

The surge in interest in non-relational databases—often known collectively as NoSQL—is now impossible for Web developers to ignore. Whether you are looking at a non-relational database for reasons of scalability, availability, cost, performance or just because it's a shiny new toy, there's no denying that serious Web developers need to consider non-relational options when designing an application. In the past few months, every project on which I've worked has at least considered a non-relational solution, even when the final decision was to use a relational database.

In the previous two installments of this column, I looked at MongoDB, an object (or “document”) database with a somewhat relational feel. MongoDB stores objects, but its query language should look somewhat familiar to those of you who have long used relational databases. If you're willing to consider a more radical departure from the world of relational databases and query syntax, instead of using the map-reduce paradigm, easy replication and a straightforward RESTful API, you might want to consider CouchDB, now part of the Apache Software Foundation. Even if you don't use CouchDB in production environments, you may find (as I do) that its use of JavaScript, coupled with its implementation of map-reduce, helps you think in new and different ways about old problems.

CouchDB Basics

Downloading and installing CouchDB is extremely easy. If it's not available via a simple apt-get install (or the yum equivalent) for your system, or if you simply prefer to install a source version, you can download it from the CouchDB home page at The version I'm running is slightly out of date (0.10), rather than the latest production version at the time of this writing (0.11). Nevertheless, the differences aren't that great, especially for the simple examples shown here.

After I installed CouchDB with apt-get, I started it with the following standard command on my server:

/etc/init.d/couchdb start

That starts the CouchDB server on port 5984. By default, this means I can access the CouchDB server as:

If you are interested in accessing your CouchDB server from another system, you can modify the CouchDB configuration file (/etc/couchdb/default.ini on my machine) by going to the “httpd” section and replacing the name-value pair:

bind_address =

with your IP address instead of (that is, localhost). Restart CouchDB, and it will be accessible not only to local HTTP clients, but also across the Internet.

Obviously, starting a CouchDB server on its well-known port and without any security restrictions is asking for trouble. If you are running a production instance of CouchDB, you should ensure that it cannot be accessed or modified by the general public. CouchDB comes with basic authentication options that make it possible to restrict access to databases, and you should look into those before deploying your system to a public server.

If you point your Web browser to your CouchDB server at port 5984, you will see the following:


This response tells you several things. First, you see that all communication in CouchDB takes place using JSON, the JavaScript object notation that has become a lightweight method for communication among Internet applications. Although CouchDB is written in Erlang, an open-source language designed for distributed processing, nearly everything associated with it uses JavaScript. Functions (as you soon will see) are written in JavaScript, and both inputs and outputs are sent using JSON.

CouchDB is also RESTful—it uses the entire vocabulary of HTTP verbs to describe what should happen and a URL to indicate the object on which the action should take place. Most people are familiar with HTTP's GET and POST verbs, but less so with PUT and DELETE. CouchDB uses all of these, combining HTTP, JSON and REST for rich effect.

Thus, when you point your Web browser to your CouchDB server on port 5984, asking for the document /, you actually are issuing a GET request for the document named /. CouchDB's response describes the server, rather than an individual document. The response is an object (equivalent to a “hash” or “dictionary” in languages such as Perl, Ruby or Python) with two keys. The first, “couchdb”, simply says “Welcome”. The second, named “version”, tells you the version of the server that is running—in this case, 0.10.0.

Let's change the URL somewhat, going instead to the URL /_utils. If you go to that document, you'll see a much more interesting response. Indeed, rather than receiving JSON, you will get a full-fledged Web page, with a CouchDB logo in the top right. This is Futon, the CouchDB Web-based interface. It is sometimes called the administrative interface, but it is also quite useful for experimenting with the database.

Along the right side of the main Futon page is the main “tools” menu. It normally comes up in the overview mode, but you can switch to a number of other screens by clicking on them. Most interesting to me is the test suite, which provides a Web-based interface to ensure that your CouchDB installation is working correctly. Although it is unlikely that your system has any problems, you still might want to run the test suite, just for personal satisfaction and thoroughness.



Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.


Jacques's picture

The quotes issue is more shell related than anything to do with curl or json.