Integrate Rails with CouchDB using ActiveCouch

This document assumes you have CouchDB 0.8.1 + as well as Rails 2.1.1 + installed.
To install CouchDB please refer Installing CouchDb on windows
.
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.

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. You can install activecouch gem by the command
$ gem install activecouch

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

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")

Extract db data

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.