What is CouchDB ?

Apache CouchDB is an open source Non Relational Database focused on ease of use and scalability. CouchDB was released on 2005 and became an Apache Foundation project in 2008.

This NoSQL database is implemented in concurrency-oriented language Erlang, it uses JSON to store data and, Javascript as its query language and HTTP requests in the API.

As the official documentation says: If there’s one word to describe CouchDB, it is relax. It is the byline to CouchDB’s official logo and when you start CouchDB, you see:

Self-sufficient data

An invoice contains all the information describing a single transaction: the seller, the buyer, the date and a list of objects or services that have been assigned. As shown in Figure 1, Self-Sufficient Documents, there is no abstract reference in this document that points to another piece of paper that contains the name and address of the seller. Accountants appreciate the simplicity of having everything in one place. And, if the choice is given to them, the developers too.

And yet, using references is exactly the way we model data in relational databases! Each invoice is stored in a table as a record that references other records in other tables: one for vendor information, one for each item, and even more for item detail, not to mention the information of the manufacturer, et cetera desunt.

There is no question of undermining the relational model which is widely adapted and extremely useful for many reasons. However, this illustrates the problem of data models that do not correspond to the way data is processed in the real world.

Take the case of the address book to illustrate a different modeling of data that is closer to the real world: a stack of business cards. Just like the example of invoices, a business card contains all the important information on the same piece of cardboard. We call this "self-sufficient" data and it's an important concept for understanding databases such as CouchDB.

Most business cards display the same information: someone's identity, an affiliation, and some contact information. Despite the differences in presentation, the information conveyed is the same and we quickly identify the piece of cardboard as a business card. In this sense, we can say of a business card that it is a document of the real world.

Jan's business card could include a phone number, but no fax number, while Chris's card shows both. Jan does not have to make this lack of information explicit by writing something ridiculous like "Fax: none" on his card. He prefers not to register it, which means he does not have one.

We can see that real-world documents of the same type, such as business cards, have similar semantics (the type of written information), but differ greatly in syntax, that is, in the way in which they are structured. Man is used to easily manage this kind of divergence.

While a traditional relational database requires you to model your data a priori, CouchDB's concept of skeletonless documents frees you from it by providing you with a formidable way to aggregate your data later, just as you would in the world real. We will detail how to design applications with this underlying storage paradigm.


If you wish to install the gem globally on your system type the following in your commandline:

sudo gem install couchrest_model

In case you are using Bundler add the following line to your project’s Gemfile:

gem couchrest_model and type bundle install on your terminal.


To properly configured the connection with your database add config/couchdb.yml file to your Rails root directory and setup your CouchDB database in a Rails-like way:

protocol: 'http'
host: localhost
port: 5984
prefix: demo
suffix: database
username: user
password: password

Note that the name of the database is either just the prefix and suffix combined or the prefix plus any text you specify using use_database method in your models with the suffix on the end.

The example config above for example would use a database called demo_database. Here’s an example using the use_database call:

class Project < CouchRest::Model::Base
use_database 'sample'
# The database object would be provided as:
Project.database #=> "https://test:user@sample.cloudant.com:443/project_sample_test"


Before using Couchrest Model we need to tell Rails to configure the newly installed gem with the settings we just provided:

$ rails generate couchrest_model:config

Know we can generate a model and start using Couchrest:

rails generate model album --orm=couchrest_model

General usage

Let’s define a model by creating app/models/album.rb:

require 'couchrest_model'

class Album < CouchRest::Model::Base

property :title, String
property :artist, String
property :year, Integer, :default => 1900


design do
view :by_title
view :by_artist_and_year


First we are requiring couchrest_model so it is possible to define our class model with inheritance from CouchRest::Model::Base.

After that we are defining the properties of the model with the corresponding data type for each one. With timestamps! we are telling the model to create autogenerated fields for created_at and updated_at.

Finally we are indicating that the model will have two views in CouchDB to query documents by title and by artist and year.

Let’s see some examples:

@album = Album.new(:title => 'Master of Puppets', :artist => 'Metallica', :year => 1986)

@album.new? # true

@album['title'] # "Master of Puppets"

# Fetching by views, loading all results into memory
albums = Album.by_title.all
album.first.title # "Master of Puppets"

# Streaming views, for efficient memory usage
Album.by_name.all do |cat|
puts album.title
# Fetching views that fulfill multiple conditions
album = Album.by_artist_and_year.key(['Metallica', 1986]).first
album.title #"Master of Puppets"
# Be careful with this
album.destroy # Delete the album from the CouchDB database

thanks Alberto for writing this create post !