Document-Oriented Persistence with CouchDB

… a scalable, NoSql database

Three Steps to CouchDB Heaven …

leave a comment »

… just follow and you will plain-lee see!

Well, actually there are way more than three steps, but today, we’ll keep it to three, in honour of the King of Rock and Roll who died this day in 1977, aged 42.

Step 1: Find some JSON documents in need of some CouchDB love

So, let’s say you have some JSON documents, all in a folder, like this:

JSON Documents in a Folder

The documents contain valid JSON. The best way to verify this is using

So anyway, these documents aren’t happy. They have so much to offer to the world, yet here they are languishing on your hard disk.

Let’s cheer them up a little by putting them on the Couch.

Now, if you haven’t got your “CouchDB in the cloud” yet stop reading this and go to and get one. You can also get one from the similarly excellent

One tip. When you create your cloud instance of CouchDB, be sure not to leave it in “admin party” mode. Secure it with a username and password instead.

Step 2: PUT your documents on the Couch

So, how do we get your love-sick documents off your disk and up and into the heavens?

Well, we know that we can speak with CouchDB at any time using HTTP. To use HTTP from the command line, we can use the curl command. If you are using windows, you can install curl for windows:

I’m using Ubuntu Linux because it’s free and it’s awesome.

To create a database on your new cloud-based CouchDB, you need to do this from the command line or terminal window:

curl -X PUT

To put a single document on to the database, do this:

curl -X PUT -d @test.json

Note a couple of things: you need to replace username, password, mick, universities, test with whatever your own variables are.

Also, please note that I used PUT not POST. Why? Well, we use PUT when we already know the _id of the JSON document. If you want CouchDB to assign a system-generated _id to your document, that’s when you use POST instead. More details here:

… all being well, the server replies as follows:


… and we can go and look at our test document here:

To upload an entire folder to the Couch, I had to learn some bash scripting (on windows the same would be achieved with a windows batch file script).

for filepath in $FILES
# get the file name from the file path
jsonfilename=$(echo $filepath | sed -e 's/.\/universities\///g')
# remove the .json extension to get the docname
docname=$(echo $jsonfilename | sed -e 's/.json//g')
# put the document into CouchDB
echo curl -X PUT "$url" -d @"$filepath"
curl -X PUT "$url" -d @"$filepath"

This page helped me to write the bash script.

I saved this bash script into a file called loop. I then ran it by invoking bash loop from the terminal, and watched my documents fly off to heaven, where they live now for everyone to enjoy.

You can see the individual documents like this:

… put the output into so you can see the structure of the JSON document properly.

Step 3: Put on a SHOW

Last time we looked at how design documents can hold HTML, and apply the HTML to any document we have.

Our example was this, pretty simple and lame.

… but, since it’s all “just HTML”, you can do this as well, to use the latitude and longitude on a Google map. (I used the example map code from

So let’s change _show/id in the url to _show/googlemap, so that the output is produced by a different server-side javascript function.

So, all I’ve done here is add a show to my design document. The name of the show is “googlemap”.

The design document is here.

The design document also contains a view and a list, which enables us to link to all the individual google maps.


Written by klena02

August 16, 2010 at 10:50 am

Posted in CouchDB

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: