Apache CouchDB is a distributed, fault-tolerant and schema-free document-oriented database accessible via a RESTful HTTP/JSON API.
Normally a Pylons web application will use some sort of RDBMS for storing data and persistence – such as MySQL or PostgreSQL. I’ve decided to go a different route and integrate Pylons with CouchDB. Right now there is a Python library, couchdb-python, that will help us communicate with our CouchDB’s HTTP/JSON api.
For this article, I will assume you have Pylons installed and you are somewhat familiar with it. We are going to create a simple page counter application.
CouchDB is written in Erlang, a functional programming language with high concurrency. Let’s install Erlang.
You should now have erlang installed. If you type erl and hit enter, you should see something like this.
Now let’s install CouchDB. The latest version can be found on this page.
Okay. CouchDB should now be installed. Let’s start it up.
Alright, we are almost there. Let’s install the couchdb-python library.
or the latest development version:
Now that we’ve got CouchDB all setup and running, let’s open up the web interface and create a database. CouchDB has a great web interface, located at http://localhost:5984/_utils/.
When you are at the web interface, go to create database, and let’s name it tutorial. After you have created the new database, you are redirected and are shown an empty database with no documents.
We now have created our CouchDB database and we are ready to start adding new documents.
Let’s create a new Pylons project named tut1, delete the default index.html, and a create a controller called main.
For this tutorial, we aren’t really going to go into too much detail. We are just going to make one page with a simple page counter. The next tutorial will be about some more advanced topics.
Okay, open up your config/routing.py file so we can add a route to our index page in the main controller.
Now let’s open up the file controllers/main.py. Let’s add an import for the couchdb-python module.
For the counter to work, we are going to just create a simple document that will store the visits.
Here is what our method for index will look like.
First, a server object is created, and then the database is selected. After, we check to see if the counter document exists, and if it doesn’t, we initialize it. CouchDB stores a documents as a dictionary. A document can have as many key/value pairs as it wants. For this example, we just have one key, visits, which stores an integer.
Now that our index method is done, let’s run our pylons application.
Open up the site in a web browser, at http://localhost:5000.
You should see the following on your first visit.
And on subsequent visits…
You have successfully created a CouchDB powered page counter! Now, this isn’t meant to be a production page counter, but it should give you a basic example of how CouchDB stores and retrieves documents.
In the next tutorial, we will integrate CouchDB with Pylons more, use Forms, CouchDB-Python’s Schemas, and more.