How to use CouchDB as Cache Database in your app (2/3)

Basic usage and Rails configuration

Altura Soluciones
Feb 2, 2018 · 5 min read

Go to part 1: What is CouchDB.

Go to part 3: Redirect to CouchDB records and making backups

Getting Started and basic usage

After installing and checking that our CouchDB installation is up and running we are going to explain the basic usage of the http query requests and how to configure a Rails application to use CouchDB database.

To start querying our database we need a command line http client. On this tutorial we will use . To be sure that the command is installed on our system we must type the following command in our terminal:

and the response should be something like:

The use of is out of the scope of this post. For a complete documentation you could visit Curl Documentation Page.

First let’s get a list of all existing databases:

The response should look like:

These are the default databases created by the CouchDB installation process. Let’s create our first database:

CouchDB will reply with:

Retrieving the list of databases again shows some useful results this time:

Let’s create a second database:

If we get the list of all databases again we will get something like this:

To round things off, let’s delete the second database:

CouchDB will reply with:

The list of databases is now the same as it was before:

Let’s create a new document in our with the following command:

and CouchDB should respond something similar to this:

where the first part is an acknowledgment that the document was saved.

Although the curl command seems difficult is simple when you break it down in sections. First, tells curl to make a HTTP PUT request followed by the URL that specifies your CouchDB IP address and port. The resource part of the URL specifies the location of a document inside our . The strange combination of numbers and characters is an UUID that identifies this document in an unique way in your database. Finally, the flag tells curl to use the following string as the body for the PUT request. The string is a simple JSON structure including and attributes with their respective values.

Let’s check if CouchDB really saved our document:

CouchDB replies:

As you can see there is a pattern on this queries. Everything in CouchDB has an address, an URI, and you use the different HTTP methods to operate on these URIs.

This are simple examples of the http queries that you can use on CouchDB. If you want to get a detailed list of all possible queries you can check the CouchDB API documentation. If your prefer to use a web interface to interact with your CouchDB database I recommend you use Fauxton that is installed by default on your server.

Configuring Rails to use CouchDB

Know let’s configure our Rails application to use a CouchDB database. First we need to install the appropriate gem. On this example will be using Couchrest Model.


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

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

and type on your terminal.


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

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

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


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

Know we can generate a model and start using Couchrest:

General usage

Let’s define a model by creating :

First we are requiring so it is possible to define our class model with inheritance from .

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

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:

As you can see the use of Couchrest Model gem is pretty straight forward. To know more please visit the Github page or the Official Documentation page.


In this post we saw the basic usage of curl to make http queries to a CouchDB database. We installed the Couchrest Model gem on our Rails project so we can define models and query them using Ruby language in our controllers. On the next part we will see an example of how we redirect the user request to get from our CouchDB Cache Database instead of our main database. Also we will discuss how to backup our databases using bash scripts or replication.

Author: Eng. Alberto Aragón Alvarez


IT consulting.


IT consulting. #Agile and #Lean remote software development team specialized in #web, #mobile, #reactjs and #rubyonrails from #Ecuador.

Altura Soluciones

Written by

IT consulting. Agile and Lean remote software development team specialized in Web, Mobile, React.js and Ruby on Rails from Ecuador.


IT consulting. #Agile and #Lean remote software development team specialized in #web, #mobile, #reactjs and #rubyonrails from #Ecuador.