CouchDB 101 - 2 : Install and Get Started

It is time to get down with the CouchDB. As I work on there tutorial there a number of assumptions I am making, the platform being used.

Platform Specifications

• OS: Ubuntu 9.10 (Linux 2.6.31-20-generic #58-Ubuntu SMP Fri Mar 12 05:23:09 UTC 2010 i686 GNU/Linux)
• Apache: Apache 2 (Server version: Apache/2.2.12 (Ubuntu) | Server built:   Mar  9 2010 21:20:44)
• Shell: bash (GNU bash, version 4.0.33(1)-release (i486-pc-linux-gnu))

Installing on Ubuntu 9.10

Update source

$ sudo apt-get update

Install couchdb

$ sudo apt-get install couchdb

Install curl - curl is a command line tool for transferring data with URL syntax, supporting FTP, FTPS, HTTP, HTTPS, SCP, SFTP, TFTP, TELNET, DICT, LDAP, LDAPS, FILE, IMAP, SMTP, POP3 and RTSP.

$ sudo apt-get install curl

Testing if the CouchDB is installed and running correctly. CouchDB runs on port 5984

$ curl http://127.0.0.1:5984/

if all is okay and the CouchDB is running correctly, you should get something like

{"couchdb":"Welcome","version":"0.10.0"}

If you get some message like this

curl: (7) couldn't connect to host

then the CouchDB is nor running. Start it manual and test it again

$ sudo /etc/init.d/couchdb start

Getting Started

Now that we know our CouchDB is installed and running correctly, lets do some basic task. We will make use of the curl tool to make it all happen.

Creating a new database

Creating a database is as easy

$ curl -X PUT http://127.0.0.1:5984/your-database-name

where your-database-name is the name of your database. So for example here I will create the database with a name ostools to store open source tools I use daily.

$ curl -X PUT http://127.0.0.1:5984/ostools

on successful excutions you should get a message

{"ok":true}

To see the database created, list all the databases on your save, run

$ curl -X GET http://127.0.0.1:5984/_all_dbs

you should get

["ostools"]

Try to create another database.

$ curl -X PUT http://127.0.0.1:5984/linuxdistro

and then list databases

$ curl -X GET http://127.0.0.1:5984/_all_dbs

you should get

["linuxdistro","ostools"]

Creating, updating, and deleting database documents

Creating.CouchDB databases are schema-free, meaning that their structure is not strictly defined, and as a result you can change them on the fly as your needs require. If one tool has a graphical front-end, you include it in that ostools’s document. If another tool doesn’t have a graphical front-end, you simply don’t include it. If a tool has several dependencies, you can set the dependency field to be an array of dependencies objects—there is no need to define separate tables.

Lets create a document:-

curl -X PUT http://127.0.0.1:5984/ostools/fish -d '{}'

you should get a response similar to the following:

{"ok":true,"id":"fish","rev":"1-967a00dff5e02add41819138abb3284d"}

You’ve just created a document with the document ID of fish. The CouchDB server has automatically generated a revision number and included this in its response.

Now that your document is in the database, let’s issue a command to retrieve it from CouchDB:

$ curl -X GET http://127.0.0.1:5984/ostools/fish

You should receive a response like the following:

{"_id":"fish","_rev":"1-967a00dff5e02add41819138abb3284d"}

At this point you’re probably thinking that this tool information isn’t very useful. All it has is a unique ID and a revision number; it has no tools-related data whatsoever. So, let’s just delete this contact altogether. Deleting a document in CouchDB is quite similar to deleting a database, except you must specify the latest revision number of the document you want to delete.

curl -X DELETE http://127.0.0.1:5984/ostools/fish?rev=1-967a00dff5e02add41819138abb3284d

All going well, you should receive a response similar to the following:

{"ok":true,"id":"fish","rev":"2-eec205a9d413992850a6e32678485900"}

Passing the wrong revision number will result to "Document update conflict." error.

Now you will create a new tool with some datab for the document. A document in CouchDB is simply a JSON object, and you simply include this JSON in your
curl request using the -d flag to send it along with your HTTP request.

{
 "name":"bash",
 "type":"shell",
 "license":"GPL",
 "url":"http://www.gnu.org/software/bash/"
}

Let create the document

curl -X PUT http://127.0.0.1:5984/ostools/bash -d '{"name":"bash","type":"shell","license":"GPL","url":"http://www.gnu.org/software/bash/"}'

You should get

{"ok":true,"id":"bash","rev":"1-41406722a8966f543acbf49e06c66968"}

To get back this document from the database, use the following command:

curl -X GET http://127.0.0.1:5984/ostools/bash

And guess what your document is back

{"_id":"bash","_rev":"1-41406722a8966f543acbf49e06c66968","name":"bash","type":"shell","license":"GPL","url":"http://www.gnu.org/software/bash/"}

Create another tool can be done using an existing tools as a template. Issue the following command:

curl -X COPY http://127.0.0.1:5984/ostools/bash -H "Destination":"kigm"

Respond will be like

{"id":"kigm","rev":"1-41406722a8966f543acbf49e06c66968"}

Checking on the document kigm, you will see it has the same informations as bash. So lets update that information to reflect the new information for kigm

curl -X GET http://127.0.0.1:5984/ostools/kigm

{"_id":"kigm","_rev":"1-41406722a8966f543acbf49e06c66968","name":"bash","type":"shell","license":"GPL","url":"http://www.gnu.org"}

So lets update that information to reflect the new information for kigm

{
 "name":"kigm",
 "type":"webapp",
 "license":"GPL",
 "url":"http://wiki.github.com/eferuzi/kiGM/",
 "requires":["apache","php","mysql"],
 "developer":"Emanuel Feruzi"
}

When doing an update, you must include the revision field in your JSON document, with the revision identifier that the changes are based on, this is to prevent multiple users from making changes to the same document at the same time.

curl -X PUT http://127.0.0.1:5984/ostools/kigm -d '{"_rev":"1-41406722a8966f543acbf49e06c66968","name":"kigm", "type":"webapp", "license":"GPL", "url":"http://wiki.github.com/eferuzi/kiGM/", "requires":["apache","php","mysql"],"developer":"Emanuel Feruzi"}'

Response

{"ok":true,"id":"kigm","rev":"2-f56ac37c3805fc6058c840462ae85756"}

Let’s check it out with a GET request at any rate:

curl -X GET http://127.0.0.1:5984/ostools/kigm

{"_id":"kigm","_rev":"2-f56ac37c3805fc6058c840462ae85756","name":"kigm","type":"webapp","license":"GPL","url":"http://wiki.github.com/eferuzi/kiGM/","requires":["apache","php","mysql"],"developer":"Emanuel Feruzi"}

Now you can experiment more and share your findings with us.

Next: CouchDB 101 - 3 Creating Views