Skip to content Skip to navigation


You are here: Home » Content » Apache CouchDB - a quick start


Recently Viewed

This feature requires Javascript to be enabled.

Apache CouchDB - a quick start

Module by: Hannes Hirzel. E-mail the author

Summary: This module introduces you to the Apache CouchDB by giving you commented references. CouchDB is a non-relational document oriented database. A database is a collection of JSON documents. CouchDB documents are accessed and all operations are done through HTTP requests.


CouchDB is a store for documents. Documents are JSON strings. It can be queried in a MapReduce fashion using JavaScript. The database may be accessed from any computer language by using Http requests. CouchDB supports a RESTful API. There is a web gui to do administrative tasks. An outstanding feature is that you might easily replicate your database with another instance.


Using a web service

The easiest way to try out couchDB might be not to go for a local installation but just to get a free account on or


You install the CouchDB in Ubuntu by using apt-get.

sudo apt-get install couchdb

As of November 2012 this gives you version 1.0.1 in Ubuntu 12.04 ("Precise") which is fine for learning about couchDB. For a good experience with replication you need a newer version. The Apache wiki has instructions how to install it from the sources. They work fine but it takes about 30min to compile everything.

For testing and administration purposes (e.g. replication) it can be useful to have the cURL command line utility installed.

sudo apt-get install curl

Microsoft Windows

Download a setup file from It is a regular MSWindows installer. Please note that the default (checkbox checked) is to install it as a Windows service. So after installation there is no need to start the database. Just access the database as described below.

More information

For more detailled instructions about installation see the CouchDB wiki.

Was the installation successful?

To check if the installation was successful use a browser and go to or http://localhost:5984.

Accessing couchDB after installation

Database administration

You acess the database administration functions through a web gui called 'Futon'.


Futon web GUI


In the screen shot two databases 'adele' and 'components' have been created. This was done like this:

  • Click on 'Create database'
  • Type in a name of the database, e.g. 'adele'
  • Click on the 'create' button


A database contains documents. There is a GUI to create 'JSON' documents but the regular way to create documents is to have program creating them by accessing the database through Http requests.


On the side bar on the right-hand side click on 'Replicator' and fill in the addresses of the two databases.

List of databases

To ask on the command line which databases are in a couchDB installation you may use

curl http://localhost:5984/_all_dbs
or in a browser http://localhost:5984/_all_dbs

list of couchDB databases

Accessing the database

To access the database you issue http request like the following

curl http://localhost:5984/mydatabase/_all_docs
Alternativley you may access it from a browser with http://localhost:5984/mydatabase/_all_docs This gives a list of all the keys of the documents stored in the database. This is in the form of a JSON object string.

To get all documents with the content use http://localhost:5984/mydatabase/_all_docs?include_docs=true

To access a single document you do http://localhost:5984/mydatabase/theIDofMyDocument. This gives the document as a JSON object string. A HTML page might access the couchDB this way through an AJAX request.

Design documents

Design documents are special documents stored alongside the data documents in the same database. The design documents follow some conventions. A database may contain many design documents. The urls look like _design/myview1 or _design/myview2.

Further reading

Introduction on IBM developerworks

The following document is a follow-up reading on this cnx module. It includes practical examples.

Summary of the article: Relational databases define a strict structure and provide a rigid way to maintain data for a software application. Apache's open source CouchDB offers a new method of storing data, in what is referred to as a schema-free document-oriented database model. Instead of the highly structured data storage of a relational model, CouchDB stores data in a semi-structured fashion, using a JavaScript-based view model for generating structured aggregation and report results from these semi-structured documents. CouchDB has been developed from the ground up with Web applications as the primary focus and has its sights on becoming the de-facto database for Web application development.


CouchDB wiki:

On-line book CouchDB: The Definitive Guide The book is designed to guide you gently through using CouchDB with clear but practical scenarios.

API cheat sheet

The interaction with the couchDB goes through Http requests. The following gives a terse overview of the possible requests.

Content actions

Download module as:

Add module to:

My Favorites (?)

'My Favorites' is a special kind of lens which you can use to bookmark modules and collections. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need an account to use 'My Favorites'.

| A lens I own (?)

Definition of a lens


A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags? tag icon

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

| External bookmarks