More than seven

Writing about code. Occasional other topics. Made by @garethr.

Using Curl to play with CouchDB

Dec 11, 2007 · 3 minute read

As a big big fan of all things HTTP, the new Erlang based database, CouchDB, piqued my interest. With the recent release of 0.7 it’s now intended for widespread use. Now I’m a fan of databases as long as I don’t have to go too near them. SQL, triggers and stored procedures are all a little too close to magic for me.

The reason CouchDB looks particularly good fun was it’s build around a REST API using JSON for data transport. I’m generally not an acronym guy, but REST, JSON, API and HTTP in one open source piece of code? Sounds like fun to me.

The CouchDB community have built up an already excellent wiki with all the information you need to get started and get the software installed. I just used the magic of MacPorts but the page covers all the various dependencies and setups (though nothing on their yet about the N800).

<code>sudo port install couchdb</code>

You might then need to set-up a user and some permissions. Again the wiki has more detailed installation instructions. All being well you should then be able to fire up CouchDB:

<code>sudo -u couchdb couchdb</code>

So first things first. Their are getting started code examples on the wiki in all the usual languages so you can just dive in. CouchDB also comes with a few in-build tools which are both pretty attractive and useful. You have a database browser, a full test suite and a command shell.

Curl, for those not familiar with it, is a fantastic command line utility for throwing around HTTP requests. I already use it for testing and generally prodding sites but it’s absolutely perfect for demonstrating CouchDB. Let’s start with creating a database called test:

<code>curl -X PUT http://localhost:8888/test/</code>

That should have created the database. Let’s get some information back about the database:

<code>curl -X GET http://localhost:8888/test/</code>

Everything should be returning JSON strings telling us something about what it finds. Let’s add a blank document to the database:

<code>curl -X POST http://localhost:8888/test/ \
-H "Content-Type: application/json" -d {}</code>

Note the blank JSON object {} passed as Post data. What about retrieving a list of document from the database?

<code>curl -X GET http://localhost:8888/test/_all_docs</code>

We’re now done with that database so let’s delete it.

<code>curl -X DELETE http://localhost:8888/test/</code>

I’ve just done the basics here, but the APIs are simple and nicely documented enough for you easily to find out more. This is the beauty of RESTfully designed APIs, they are just about self documenting. For the most part you just have a predefined HTTP method and a defined URL.

The Erlang base of CouchDB makes for some interesting horizontal scaling possibilities (as well as a good excuse to play with Erlang.) Even if CouchDB wasn’t cool enough already, it comes with probably the best start-up message I’ve seen in software for ages:

<code>CouchDB has started. Time to relax.</code>