Back to article
Snakes on a Couch! Using Python with CouchDB
Diving Right In
September 23, 2010
Even if you're not a database wonk, you've probably been hearing some talk about this newfangled thing called CouchDB. For one thing, the new Ubuntu desktop uses it for things like the addressbook and Tomboy notes. So what is CouchDB, anyway?
What is CouchDB?
If you're familiar with old-style relational databases, like MySQL, Postgres and Oracle ... forget all of it.
Couch is part of the new "NoSQL" movement, where your data, rather than living in one massive relational database on a single server, may be distributed on many machines across the web. Or it might be sitting in a DesktopCouch database on your local desktop machine.
To get started with couch, first install couchdb. It's probably available through your distro's package manager.
Couch and Python
The python-couchdb library makes it easy to talk to CouchDB from Python.
The first thing we need to do is create a database. You can do that from the python interpreter, pointing python-couchdb at your couchdb server -- typically http://localhost:5984/.
Let's make a database of restaurants:
$ python Python 2.6.5 (r265:79063, Apr 16 2010, 13:09:56) [GCC 4.4.3] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> import couchdb >>> server = couchdb.client.Server('http://localhost:5984/') >>> db = server.create('restaurants')
Now you need some data. In couchdb, a hunk of data is called a document. The name is a bit misleading: a Couch document is a single object, like a restaurant, not anything you'd normally think of as a document.
Your python objects can inherit from Document. Specify a few attributes and their types, then add the document to the database:
from couchdb.schema import Document import datetime class Restaurant(Document) : type = couchdb.schema.TextField() name = couchdb.schema.TextField() last_visited = couchdb.schema.DateTimeField() r = Restaurant(type="restaurant", name="Alice's Restaurant", last_visited=datetime.date(1965, 11, 25)) r.store(db)
Checking your work: Futon
An invaluable tool when you're working with CouchDB is its web interface, called Futon. Just point your browser to http://localhost:5984/_utils (don't forget the underscore!) and you'll see a screen like Figure 1. It shows that you have one database, called restaurants.
Click on that database to see the documents inside it -- only one so far. Clicking on the key for the document (Figure 2) shows all the Field/Value pairs inside the document: the name and last_visited time you assigned, plus two automatically assigned fields, _id and _rev, which become important when you change a document.
It's always helpful to keep an eye on Futon when you're developing a
CouchDB application. You can add and remove documents from Futon,
delete the database and start over,
and even do queries, as you'll see shortly.