Flask-CouchDBKit provides simple integration with CouchDB database using the powerful CouchDBKit library.


Assuming you already have CouchDB installed (and if you don’t, look at the CouchDB Installation Guide), you can install the extension using one of the following commands:

$ pip install Flask-CouchDBKit

or if you are required to use easy_install:

$ easy_install Flask-CouchDBKit

How to Use

Flask-CouchDBKit is a thin wrapper around CouchDBKit. All you have to do is create a CouchDBKit object and declare models using the Document base class. These objects behave as you would expect their non-Flask counterparts to behave, so see the CouchDBKit documentation for additional guidance.

Setting up Flask-CouchDBKit is easy:

from flask import Flask
from flaskext.couchdbkit import CouchDBKit
app = Flask(__name__)
app.config['COUCHDB_DATABASE'] = 'testapp'
couchdb = CouchDBKit(app)

class Guestbook(couchdb.Document):
    author = couchdb.StringProperty()
    content = couchdb.StringProperty()

In case you want late-binding of a CouchDBKit object, you can use CouchDBKit.init_app() to bind it to your app object after it has been created:

from flaskext.couchdbkit import CouchDBKit
couchdb = CouchDBKit()

from flask import Flask
app = Flask(__name__)

The extension makes use of four configuration variables, but only COUCHDB_DATABASE is required. The full list of all available configuration variables can be found below:


The database URI that should be used for the connection. For example,

  • http://localhost:5984/
  • http://user:pass@remote:5984/
COUCHDB_DATABASE The database name to connect into.
COUCHDB_VIEWS Path where views definition are stored. Default to _design.
COUCHDB_KEEPALIVE Amount of connections that should be kept open in the pool. Set this to None will use the default pool size.

Defining Views

Views are defined in a directory named _design inside the project directory. This is done in a way that is compatible with CouchApp views. Let’s look at the typical structure of a typical views directory:


Any directory placed at the root of the _design directory will be treat as a design document. It is followed by the views directory and a view name. In this example, guestbook is the design document with all and by_author as its view.

The map.js may looks like the following:

function (doc) {
    if (doc.doc_type == 'Guestbook') {
        emit(doc._id, doc);

The local views can then be sync to the CouchDB server using CouchDBKit.sync():

>>> from yourapplication import couchdb
>>> couchdb.sync()

It is not recommended to sync local views with the server on every request using after_request() since CouchDBKit will make no effort in trying to determine which view has changed, but will simply replace them.

To retrieve documents from the design document, you can use Document.view():

>>> Document.view('guestbook/all')

For more information regarding views, please read Introduction to CouchDB views.

API Documentation

class flaskext.couchdbkit.CouchDBKit(app=None)

This class is used to control CouchDB integration to a Flask application.

Parameters:app – The application to which this CouchDBKit should be bound. If an

app is not provided at initialization time, it may be provided later by calling init_app manually.


Bind an app to a CouchDBKit instance and initialize the database.

Parameters:app – The application to which the CouchDBKit instance should be



Initialize database object from the COUCHDB_DATABASE configuration variable. If the database does not already exists, it will be created.


Sync the local views with CouchDB server.

Fork me on GitHub