Ruby Weekly is a weekly newsletter covering the latest Ruby and Rails news.

CouchRest: CouchDB, Close to the Metal

By Ric Roberts / September 2, 2009

couchI have been contemplating the use of document-stores in my Ruby apps for a few months (you might remember my MongoMapper post from back in June), and I've been following developments in the No-SQL movement. George Palmer's presentation at Rails Underground on his couch_foo gem inspired me to explore the possibilities further, and I've recently started work on incorporating CouchDB into some projects that I'm working on.

What is a "document store?"

Couch is one of several available document oriented databases (the other main contender being MongoDB, for which there's a good comparison on the Mongo website). Document stores go some way to bridging the gap between traditional functionality-rich relational databases (like MySQL, Postgres) and fast, highly scalable key/value stores (such as Toyko Cabinet). I think I should make it clear at this point that I'm not a SQL-hater: I worked as a DBA for a while a few years ago, and if you have truly relational data with a fixed schema and complex transaction requirements then you can't beat a good RDBMS.

With CouchDB and friends, data is held in documents. These documents don't have a fixed schema - they can have any number of arbitrary properties. This makes document stores great for holding collections of similarly (but not identically) stuctured items. CouchDB stores the data as JSON hashes, and provides a REST interface for creating, updating and querying.

Using CouchDB in your Ruby App

I've already mentioned couch_foo as one option for interacting with a CouchDB from Ruby app but after a bit of investigation, I eventually decided against it. Although it provides a familiar ActiveRecord-style interface and seems well-written, I wanted something that was a bit closer to couch's RESTful HTTP and JSON interface. Also, I wasn't convinced that extending the ActiveRecord paradigm to a document-based database was a good fit. I also dabbled with Alex Lang's couch_potato library, but finally decided on CouchRest.


CouchRest lightly wraps CouchDB's HTTP API (via RestClient, Heroku's Ruby HTTP wrapper), and provides a simple, Object-Mapper agnostic framework on which to build your application. Things just work as you'd expect: the JSON that comes back from CouchDB queries are presented as objects based on Ruby Hashes.

Models, Properties and Views

With CouchRest, you can define models for documents that share similar structures, deriving from CouchRest::ExtendedDocument. Properties that are common to each Model can be declared with CouchRest's property method. It also supports the automatic setting of created_at and updated_at properties, callbacks and validations.

In Couch, you query and filter your data via views. Views are declared as javascript map-reduce functions that iterate through all documents in the database, building an ordered index of key-value pairs. CouchRest lets you declare simple views in Ruby, so that you can look up documents by that property. If you need more control, there's also the option of passing the raw javascript to the Ruby method.

class Article < CouchRest::ExtendedDocument

  include CouchRest::Validation

  property :date
  property :title
  property :slug

  view_by :slug

  validates_present :title


  save_callback :before, :generate_slug_from_title

  def generate_slug_from_title
    self.slug = title.downcase.gsub(/[^a-z0-9]/,'-').squeeze('-').gsub(/^-|-$/,'') if new?

Hopefully this has given you a taster of what CouchDB might be good for, and how CouchRest can help you with integrating it into your Ruby app. Obviously there's much more too it than I've covered here, but this (draft) online O'Reilly book is a great place to start learning about CouchDB ...and it's co-written by J. Chris Anderson, author of the CouchRest Ruby library.

jslab.pngAlso...Jumpstart Lab is offering Ruby Jumpstart, an introduction to programming for total beginners, on 9/26-9/27 in Washington, DC. Save $30 with code "rubyinside"!


  1. Kevin Radcliffe says:

    This looks great, thanks for the post! It (perhaps) should be noted, that like a number of ruby related projects that seem very interesting, it's a bit difficult to get started with Couch on a Windows system. The install and deployment seems unintuitive at best.

    Luckily, I found the zips and install instructions for MongoDB to be a lot friendlier to a windows environment. I'm not "fighting" for Mongo here, I just wanted to note that it seemed much much easier to get it going on a Windows system.

  2. Christopher Petersen says:

    Thanks for the post, we have been using CouchDB and CouchRest in production for a few weeks now, and it's been great. I'm glad to see it getting some press.


  3. Ric Roberts says:

    Hi Kevin. I've got nothing against MongoDB - it's useful for slightly different things to CouchDB (which didn't suit my circumstances).

  4. Ric Roberts says:

    CouchDBX looks like a good way to get Couch up and running quickly (just for Macs for now, I think). Check out the CouchDB wiki for instructions regarding installing on Windows.

  5. Matjaž Gregorič says:

    I got CouchDB 0.9 running on Windows using the package mentioned in the following post:

    It's very simple to install (just unzip) and so far has been working well for me.

  6. renoke says:

    Thanks for this article and the other one talking about key-value storing alternative. I'm also convinced that document oriented databases have a bright future, not as replacement of relational database but for specific situations.

    I've started to developp a simple library to abstract document object: DocumentMapper. It has now two adapters: couchdb and mongodb, but the idea is to embrace the main document datagases and have tools for switching easily from one to another.

    I invite you to have a look.

  7. Peter Wagenet says:

    I've played around with CouchRest some and my biggest concern is that it doesn't play nicely enough with Rails. I'm glad that CouchRest doesn't just try to mirror ActiveRecord, but I would like to see them go to more effort to make it Rails like. Admittedly, CouchRest isn't Rails only so maybe this would be best done through some sort of CouchRest Rails plugin. I've actually played around with this on my own fork of CouchRest ( Anyway, something to consider when you're looking at CouchRest for a Rails project.

  8. James Nathan says:

    I am still having a hard time installing Ruby on my computer, and most of the files are zipped and can not unziped them to try and use the program. if so you can email me.

  9. Ric Roberts says:

    Peter: Check out CouchRest-Rails for extra Rails support:

  10. Robert Dempsey says:

    Hey Rick,

    Thanks for the article and the link to CouchDBX on Twitter. Do you have any links to complete examples of creating a basic Rails app using Couch as a backend, showing not only the models but the views as well? I've seen many examples of using it in Ruby apps, but not so much with Rails. I appreciate the help.

  11. Peter F. Dyle says:


    using CouchDB for something other than a small production environments is a bit crazy. Look at the PUT/POST times. Look at the View generation time consumption. You can't make bulk updates server side.

    This seems to be a "cool" project. "Futon" sells it like hot potatoes, 'cause its "cute". The talks given by usual 2 commiters are self.repeat. If you ask them about numbers, they can't seem to give them. Wait severall minutes for a view generation !?? Oh, nice for backups, not transaction intensive apps, even for document storage.

    I read lot's of people on the "cool couchdb", that test it a bit, and that's it.
    Can someone point to a decent talk ? I found severall and on this one the guy got asked about things and won't even respond (min.16; min.27;...)

    CouchDB's talks is just slides with the f* word and cool word....
    let's get some grip... CouchDb should be considered an incubation product on this phase.

  12. Ric Roberts says:

    Hi Peter. I am involved in a couple of projects which will use couch 'for real' in a production environment. Yes, updates are not super-fast, but the way it maintains indexes means that lookups can be kept quick. Whether Couch is suitable for your project depends on what structure the data takes and how frequently it is updated. I agree that it's not for everyone.

  13. Ric Roberts says:

    Just discovered that the official CouchRest repo is actually here: (I'll update the article accordingly).

Other Posts to Enjoy

Twitter Mentions