Skip to content

How to Use ActiveCouch with Rails

bbwharris edited this page Sep 12, 2010 · 11 revisions

This document assumes you have CouchDB 0.8.1 as well as Rails 2.1.1 installed. Please note, ActiveCouch has been around since early this year and we’ve been learning a lot of lessons along the way. Hopefully, we can get newer and better ideas into ActiveCouch and make it a kick-ass Ruby wrapper for CouchDB.

For the curious, we at www.wego.com have been using CouchDB 0.7.3 in our production system since May 2008. Recently (Oct 2008) we made the switch to CouchDB 0.8.1 with the latest version of ActiveCouch and things have worked quite well for us so far. (touchwood) For the even more curious, we use CouchDB to save hotel details information as documents, i.e. all the details regarding a hotel such as name, geo coordinates, addresses, are stored as documents inside CouchDB databases.

So a lot of the evolution of ActiveCouch correlates with the level of frustration with the library and making it better implies making our lives better. There are maybe better/more-lightweight wrappers for CouchDB out there. But as Ezra says, monoculture is bad and I think it’s good that there are different approaches to the same problem. Competition is always good.

To use ActiveCouch with Rails prior to 0.2.x used to be a PITA. Whereas the previous versions of ActiveCouch were designed to be used as a standalone gem, and you had to use a little bit of funkiness to get it to work with Rails. The latest version aims to solve a lot of those problems.

Install ActiveCouch as a Rails Plugin

The biggest advantage of ActiveCouch v0.2.x is that it can be used as a Rails plugin as well as, as a standalone gem.

ActiveCouch uses the JSON gem for fast JSON serialization/deserialization, so install that first:


$ gem install json

Then, create your Rails project


$ rails couchify

Then, install ActiveCouch as a plugin:


$ cd couchify $ ./script/plugin install git://github.com/arunthampi/activecouch.git

Tada, this installs ActiveCouch in RAILS_ROOT/vendor/plugins

Follow up – Get it started

You need to create a file called activecouch.yml in RAILS_ROOT/config which looks something like this (Of course, depending on your deployment strategy, your test and production sites will be something else)


development:
  site: http://localhost:5984/
test:
  site: http://localhost:5984/
production:
  site: http://localhost:5984/ 

Create your ActiveCouch model

This is now very simple in ActiveCouch. At the root of your Rails project, simply enter

$ ./script/generate activecouch_model cat

This generates a cat.rb file in RAILS_ROOT/app/models which looks something like this:


class Cat < ActiveCouch::Base
    site YAML::load(File.open(File.join(Rails.root,
                  'config', 'activecouch.yml')))[Rails.env]['site']
end

All set to use CouchDB database depending on your Rails environment. Now ActiveCouch assumes that you already have a database called ‘cats’ created in CouchDB, so that you can start creating all your CouchDB documents. No matter, Rake tasks to the rescue:

Creating your database

If you goto RAILS_ROOT of your app, and enter the following:


$ rake --tasks

You will see some of the following:


rake activecouch:create_db           # Creates a database in CouchDB
rake activecouch:delete_db           # Deletes a database from CouchDB
rake activecouch:delete_view         # Deletes a view in CouchDB
rake activecouch:save_view           # Saves a view in CouchDB

So to create your database, just enter


$ rake activecouch:create_db db=cats

And boom, you have your database called cats created in ActiveCouch.

If for some reason, you need to delete your database, the answer is simple:


$ rake activecouch:delete_db db=cats

Awesome, now you can go ahead and edit your model to have various fields, for example a cat should probably have a name, so your model will look something like this:


class Cat < ActiveCouch::Base
    site YAML::load(File.open(File.join(Rails.root,
                  'config', 'activecouch.yml')))[Rails.env]['site']

    has :first_name
    has :last_name
end

Creating your first ActiveCouch Objects

To see if this works, open up ./script/console and type in the following:


> cat = Cat.new(:first_name => "Mr.", :last_name => "Jinks")
> cat.save

Or


> cat = Cat.create(:first_name => "Mrs.", :last_name => "Jinks")

That’s great, how do I start finding stuff?

CouchDB lets you query your database using something called Views. The CouchDB wiki has a lot of information on how views work. You should also probably consider watching Jan Lenhardt’s awesome talk on CouchDB , which explains a lot of the differences between Relational Databases and Document-Oriented Databases.

ActiveCouch tries to abstract a lot of the view behaviour from you (some people have said it is inelegant , so I’m hoping for some better ideas from people reading this). For example, for the Cat model above, suppose you want to query for all cats by their last name, you can create a view at /cats/design/by_last_name/by_lastname and ActiveCouch lets you query your CouchDB database like so:


cats = Cat.find(:all, :params => {:last_name => "Jinks"})

The price you pay for the somewhat unwieldy view names, is that you get very convenient find methods. Of course if you have created your custom views, you can always use the find_from_url method which works something like this:


cats = Cat.find_from_url("/cats/_view/by_last_name/by_last_name?key=%22Jinks%22")

Ok, back to views. ActiveCouch lets you create your views using a very simple generator. So from your RAILS_ROOT again,


$ ./script/generate activecouch_view ByLastName

This creates an ActiveCouch::View class in RAILS_ROOT/app/models. You can edit the view as given below, so that you can start querying by last name:



class ByLastName < ActiveCouch::View
  define :for_db => 'cats' do 
    with_key 'last_name'
  end
end


Done. But this view is not yet in the CouchDB database, so you need to save it into the database.

Saving your view

To save your view, you can use the built-in Rake task to save your views:


$ rake activecouch:save_view db=cats view=ByLastName

And boom, your view is saved.

Now suppose you want your view to be saved in many databases inside CouchDB. i.e. you have databases such as dogs, people, etc. and all of them need to be queried by their last name. No matter, you can use db=_all_dbs as part of your Rake task and this will save the view into all databases.


$ rake activecouch:save_view db=_all_dbs view=ByLastName

Now you are ready to start querying your database and finding objects.

Clone this wiki locally