Interfacing CouchDB with Python


Apache CouchDB is a database that is focused on ease of use. It can be interfaced with the versatile Python programming language, as shown in this tutorial.

Apache CouchDB is a popular open source database that is used as a document-oriented NoSQL database. Like most other NoSQL databases, it uses the JSON format to store data. JSON (JavaScript Object Notation) is the open standard data file format that is used as an alternate to XML, to transmit data between multiple incompatible and heterogeneous servers.

 Key features

  • It has a distributed architecture with easy and fast replication of a database for multiple instances of the server
  • Quick retrieval of data and indexing
  • Interface based on REST for insertion, updates, retrieval and deletion of documents
  • JSON-based document format (easily translatable across different languages)
  • Assorted libraries available for multiple languages, or simply for the localisation and internationalisation of content
  • Subscription of data updates is very rapid
  • Document storage
  • ACID based semantics
  • MapReduce indexes and views
  • All items have a unique URI for HTTP
  • Consistency
  • Replication for devices, including smartphones for handling offline and online data sync•
  • In-built administration panel that can be accessed using a Web GUI admin panel called Futon
  • Lock-free database updates
  • Free-form document format
Figure 1: Futon

Installing CouchDB

To install on Ubuntu/Debian Linux, type:

 $ sudo aptitude install couchdb

To install on Gentoo Linux, type:

$ sudo emerge couchdb

Services can be started or stopped using the init scripts in all the distributions as follows:

$ /etc/init.d/couchdb start

For Windows, the CouchDB installer is available on It is installed on the system can be executed in standalone mode as well as in service mode.

Futon-the GUI administrator panel

Futon is the Web based GUI panel that is built for CouchDB. It provides the basic interface for a majority of the functions including creation, deletion, updating and viewing of documents. It provides access to the configuration parameters and an interface for initiating replication.

Figure 2: Creating a database in a Futon panel

Interaction of CouchDB with Python

Python is a popular programming language that is both general-purpose and cross-platform. It can be used as a standalone suite or a Web based implementation with the APIs.

To interface Python with CouchDB, a specialised package, couchdb, is used with the following main modules:

  • couchdb.client – A client library for interfacing with CouchDB
  • couchdb.mapping – This module provides the advanced mapping between the JSON documents of CouchDB and Python objects
  • couchdb.view – This module implements the view based server for the views written in Python
>>> import couchdb

Import CouchDB

>>> couch = couchdb.Server()

This function couchdb.Server() creates the Server Object.
On live servers, it will be like:

>>> couch = couchdb.Server(‘’)

>>> db = couch.create(‘test’)

To create a new database, type:

>>> db = couch[‘mydb’]

To use the existing database, type:

>>> doc = {‘Country’: ‘India’}

After selection of a database, create a document and insert it into the database:


The save() method returns ID and “rev” for the currently created document.

>>> db.delete(doc)
>>> couch.delete(‘test’)

The above cleans the document and database.

Couchdbkit: The framework for Python

The goal of couchdbkit is to provide a dedicated framework for the Python application to manage and access CouchDB.

The following features are inherent in couchdbkit:

  •  The HTTP backend is used through py-restclient
  •  Documents are managed dynamically
  • Threadsafeview
  • Design docs are attached with the application and sent to CouchDB
  • Manages documents with a dynamic schema

You can install couchdbkit using Pip as follows:

$ curl -O

$ sudo python
$ easy_install pip

To install or upgrade to the latest released version of couchdbkit, type:

$ pip install couchdbkit

To program with couchdbkit, type the following code:

from couchdbkit import Server
myserver = Server()
db = myserver.create_db(“couchbdkit_test”)
db[‘myid’] = { ‘x’: ‘Hello’ }
doc = db[‘myid’]

To map a CouchDB object to a Python object easily with a dynamic schema, type:

from couchdbkit import Document
class WelcomeNote(Document):
author = StringProperty()
content = StringProperty()
date = DateTimeProperty()
WelcomeNote = WelcomeNote() = “AuthorName”
WelcomeNote.homepage = “”

Once this is done, the first CouchDB document will be shown as:

import datetime
from couchdbkit import *
class WelcomeNote(Document):
author = StringProperty()
content = StringProperty()
date = DateTimeProperty()

Here is the code to save a WelcomeNote on the ‘WelcomeNote’ database. Let’s also look at how to create a database.

server = Server()
db = server.get_or_create_db(“WelcomeNote”)
WelcomeNote = WelcomeNote

Research areas and scope of project work in CouchDB and Python

There is huge scope for research in the domain of Big Data analytics. There are libraries available in Python for interfacing with Twitter, Facebook and other social media applications. Research scholars, academicians and practitioners can work on the following research topics:

  • Classification and prediction of live social media tweets
  • Analysis and prediction of patterns from Twitter’s followers list
  • Big Data analytics and rule mining in recommendation systems
  • Solving cold start problems by designing a unique recommendation system

There are a lot of other research topics in this field, based on which excellent and unique work can be done for grants and academic degrees.

Previous articleRelax with Apache CouchDB
Next articlePPP3: Working with Databases
The author is the managing director of Magma Research and Consultancy Pvt Ltd, Ambala Cantonment, Haryana. He has 16 years experience in teaching, in industry and in research. He is a projects contributor for the Web-based source code repository He is associated with various central, state and deemed universities in India as a research guide and consultant. He is also an author and consultant reviewer/member of advisory panels for various journals, magazines and periodicals. The author can be reached at
The author is an assistant professor in the National Institute of Technical Teachers’ Training and Research at Chandigarh.


Please enter your comment!
Please enter your name here