CouchDB Surfing: Learn by Doing Apache CouchDB

I’ve been hearing a lot about the Erlang-based CouchDB recently for storing data, and as I’ve got a good project coming up soon I thought I should give it a quick test to find out how easy it is to use. In this tutorial, I will help you get up to speed quickly with simple installation, configuration, and code examples. There are some great books on how to get under the hood of CouchDB, but for now I’m going to just get in and get my hands dirty.

Installing CouchDB (on Ubuntu)

Step 1) Begin by installing CouchDB using your package manager of choice, or compiling from source

sudo apt-get install couchdb

Step 2) Ensure that CouchDB is up. Point to http://127.0.0.1:5984/ in a browser. You should see:

{“couchdb”:”Welcome”,”version”:”0.10.0″}

If you are not getting this, you are likely to have some problems with your local IP settings. Try http://localhost:5984/. Step 3) Check to see existing schema’s, go to http://127.0.0.1:5984/_all_dbs in a browser. You get this cryptic message back: [] This means that there are no databases installed so far. So, let’s get some more tools in place to store and access data. As I’ve just got a new install of Ubuntu on my laptop, I also need to get all the usual dependency goodies on it

sudo apt-get install apache2 mysql-server mysql-client phpmyadmin php-cli

And some handy tools for using the (web-based) database:

sudo apt-get install python curl wgetCreating and Deleting Databases in CouchDB

Let’s start off by putting a new database together. The following command actually creates a database – it’s that easy!

$ curl -X PUT http://127.0.0.1:5984/contacts
{"ok":true}

So – let’s try to create it again…

$ curl -X PUT http://127.0.0.1:5984/contacts
{"error":"file_exists","reason":"The database could not be created,
                                       the file already exists."}

Good – it fails with a proper error. This error should be in whatever language wrapper you are using.. Right – let’s create another new database;

$ curl -X PUT http://127.0.0.1:5984/dates
{"ok":true}

And list the databases that we have in the system now. Note that this is a ‘GET’ and not a ‘PUT’.

$ curl -X GET http://127.0.0.1:5984/_all_dbs
["contacts","dates"]

We can also use a ‘DELETE’ to actually delete a table or document in a table:

curl -X DELETE http://127.0.0.1:5984/dates
{"ok":true}

CouchDB Documents and Records

So – let’s take a look at an sample record in a CouchDB database, and then get into it’s design. { “_id”: “james”, “_rev”: “2-5e2216396c06370e4dc33b99fc1147f6″, “name”: “James”, “phone”: “0113228882″, “address”: “12 Main Street, Smallville” } This is what the records, or documents look like within the databases on a CouchDB server. They are very free-form and simple. There is no data integrity within the table, or any ability to actually check that the data is of the right form. This is obviously a big change for those who are used to relational database. Please note that everything on the site is in JSON format – this is an Internet standard, and is based on the way that javascript stores data. It’s similar in a lot of ways to XML, but has a different notation that I believe is easier to read. When I created that, I just put it together on the fly. I didn’t worry about how the database is going to look. If you are used to relational databases like mysql, this is obviously a different way of thinking. It’s a lot more “Web 2.0″ and quicker to get working. It’s also much easier to change. _id is an internal ID for the document which stays the same. _rev is something that keeps track of changes. This is important, so CouchDB knows you’ve been editing an up to date copy of the document.

Using the CouchDB Web Interface

The Web interface can be a useful utility for modifying documents and records. It is called Futon, and is part o fthe CouchDB installation. Step 1) Point your browser here http://127.0.0.1:5984/_utils/index.html Step 2) And click on the example contacts database – http://127.0.0.1:5984/_utils/database.html?contacts Step 3) and click on ‘new Document’ Step 4) Now, click on ’source’ and copy the example record into the space: { “_id”: “james”, “_rev”: “2-5e2216396c06370e4dc33b99fc1147f6″, “name”: “James”, “phone”: “0113228882″, “address”: “12 Main Street, Smallville” } Step 5) Now, click back on fields and you can see the result.

Step 6) Save the document.

Programming CouchDB with Python

Now, let’s try to do something in Python with our CouchDB database.This example uses python-couchdb which I installed at the start of this document.

import couchdb
# Let's pull in the CouchDB into Python
couch = couchdb.Server()
# And collect to your local CouchDB
db = couch['contacts']
# And connect to the database
db
#Which DB are we connected to?
 
db['james']
# Let's pull out the document with the id 'james'
 
contact=db['james']
#And put the variable 'contact' to be equal to it.
contact['name']                #Now we have all the data to use
'James'
db['dave'] = {'name': 'David','phone': '0913277665'}
#And we can also create a new element
dave=db['dave']
db.delete(dave)                # ...and delete it...
db['dave'] = {'name': 'David','phone': '0913277665'}
#...and we can also create it again

Here, we are connecting to the database ; pulling off the record that we created and looking at the details of it. You should be able to see how much easier this is than having to worry about SQL queries etc. Also note the way that I’ve added and delete a new document in the database very quickly and easily.

Programming CouchDB with PHP

Looking at php, we can use the same database to show information. Obviously this makes it very easy to pass information between different systems, languages and computers. This is a simple PHP command line program which shows how to get the information we have put into the CouchDB database.

?PHP #connect to the server... 

$couch_dsn = "http://localhost:5984/"; $couch_db = "contacts";
 
 /** include the library - this is from here -
 http://github.com/dready92/PHP-on-Couch
 just download and put this file into a sub-directory, or change the ../lib
 to be linked to your lib couch directory */
 
require_once "../lib/couch.php";
require_once "../lib/couchClient.php";
require_once "../lib/couchDocument.php";
 
 /** * create the couch client object */
$client = new couchClient($couch_dsn,$couch_db);
 
/** *Let's see all the info that we can get from the database
we created earlier...
*Like the python code above, our data comes back as local variables.
*We are obviously not using any SQL code or similar to get it going. * */ 
 
$all_docs = $client-getAllDocs();
<a href="http://www.php.net/echo">echo</a> "Database got ".$all_docs-total_rows." documents.\n";
foreach ( $all_docs-rows as $row ) {
    <a href="http://www.php.net/echo">echo</a> "Document ".$row-id."\n";
    $doc = $client- getDoc($row-id);
    <a href="http://www.php.net/echo">echo</a> "Document retrieved: ".<a href="http://www.php.net/print_r">print_r</a>($doc,true)."\n";
}

You should able to get an idea about how quick and easy it is to get a CouchDB system running and using a couple of languages to use it. Please note – you can even get the client-side JavaScript talking directly to the CouchDB server, but it does take a little tweak to get it working as it’s running on a different port and you need to use Apache proxy, or something similar to bridge the connections due to the permissions of the local JavaScript code. Otherwise – you can be clever and put the html within CouchDB itself.

Apache, and Apache CouchDB are Copyright the Apache Software Foundation and Licensed
under the Apache 2.0 License

Tags: apache CouchDB Data Document Oriented Database Exclusive json php Python