Skip to content


Subversion checkout URL

You can clone with
Download ZIP
CouchModel provides an interface to easly handle CouchDB documents.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



The intent of CouchModel is, to provide an easy interface handle CouchDB documents. It also comes with a ActiveModel implementation to integrate into an Rails 3 application.

The current version is under development and open for everyone to find bugs and post them into the issue tracker.

The code has been tested Ruby 1.9.1, CouchDB 0.10.0 and Rails 3.0.0.beta.


If CouchModel is used without Rails, the ruby standard library (tested with 1.9.1) if the only requirement.

If the activemodel gem is installed, CouchModel automatically provides an interface to Rails 3.

To run the test suite, rspec (tested with 1.2.9) is required. A CouchDB instance is just required for the integration tests (task spec:integration).


The gem is part of the gemcutter archive. It can be installed by simply type

gem install couchmodel

Defining a model

To define a model, it's necessary to create a subclass of CouchModel::Base

class User < CouchModel::Base

  setup_database :url                     => "http://localhost:5984/test",
                 :setup_on_initialization => true,
                 :delete_if_exists        => false

  key_accessor :name
  key_accessor :email


The setup_database method defines a database for the model. The url option is required and specifies the url of the database in the scheme [host]:[port]/[database_name]. If the option setup_on_initialization is set to true, CouchModel will try to create the database when the model is initialized. If the option delete_if_exists is specified, the database will be deleted and re-created. If the option setup_on_initialization is not specified or false, the database setup be done manually by calling CouchModel::Configuration.setup_databases and CouchModel::Configuration.setup_designs.

The method key_accessor defined access methods to the given keys of the CouchDB document. It's also possible to use key_reader and key_writer here.

Design documents

Each defined model has a realted design document, that keeps all the views for that model. Via the command

CouchModel::Configuration.design_directory = "[directory]"

a directory is specfied that keeps all the design document. CouchModel will watch out for a file with the name [design directory]/[model_name].design and will use it as the related design document. If no such file exists, a design document will be created (but not saved to the file). The design ducument can be asscessed via

A design document should look like this

:id:        "test_design"
:language:  "javascript"
      function(document) {
      function(key, values, rereduce) {
      function(document) {
      function(key, values, rereduce) {

It will create the methods Model.view_name_1 and Model.view_name_2, which returns the result of the related view. It's also possible to pass some extra options like startkey or key to these methods.

CouchModel also creates by default a class view. This view simply selects all documents from the corresponding model and is assigned to the method Model.all.

Rails integration

The following steps has been tested with the first beta version of Rails 3 (activemodel-3.0.0.beta).

First of all, the couchmodel gem has to added to the dependencies. This can be done by adding

gem "couchmodel", :require => "couch_model"

to the Gemfile.

The configuration can be done by creating an initializer. Here is an example file (e.g. config/initializer/couch_model.rb).

CouchModel::Configuration.design_directory = File.join(Rails.root, "app", "models", "designs")

  :test        => { :url => "http://localhost:5984/test",        :setup_on_initialization => true, :delete_if_exists => true  }
  :development => { :url => "http://localhost:5984/development", :setup_on_initialization => true, :delete_if_exists => false },
  :production  => { :url => "http://localhost:5984/production",  :setup_on_initialization => true, :delete_if_exists => false }
}[Rails.env.to_sym] unless defined?(DATABASE)

This example uses an sub-directory of app/models to search for the design documents. It also defined a constant named DATABASE that is initialized with the right database setup for the each environment. This constant can then be used to define the models.

class User < CouchModel::Base

  setup_database DATABASE




CouchModel is still under development and needs to be tested. Any contribution is welcome!

Something went wrong with that request. Please try again.