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) {
    :keys: [ "key_one", "key_two" ]

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.

The view can be defined by write down a map and a reduce function or provide the keys array. If the keys array is given, CouchModel will generate a map function that emits the given array of document keys. The reduce function will be set to null.

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.


CouchModel provides support for simple association definition. Currently, the method belongs_to and has_many are implmented.

class User < CouchModel::Base


  belongs_to :session, :class_name => "UserSession"

  has_many :memberships,
           :class_name => "Membership",
           :view_name  => :by_user_id_and_created_at
           :query      => proc { |created_at| { :startkey => [, (create_at || nil) ], :endkey => [, (created_at || { }) ] } }


In this example, the belongs_to adds a key_accessor named session_id to the user and also generates getters and setters for the session object itself (session and session=).

The has_many acts as a wrapper for the specified view. The previously defined view by_user_id_and_created_at emits membership-documents by thier user_id and the created_at date. The given query option specifes a method that returns a query hash for the specifed view. The arguments for this method can be passed membership association method.


The returned CouchModel::Collection can be treated as an (read-only) array.

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.