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 curl. To be sure that the curl command is installed on our system we must type the following command in our terminal:

curl --version

and the response should be something like:

The use of curl 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 demo_database 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, -X PUT 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 /demo_database/6e1295ed6c29495e54cc05947f18c8af specifies the location of a document inside our demo_database. The strange combination of numbers and characters is an UUID that identifies this document in an unique way in your database. Finally, the -d flag tells curl to use the following string as the body for the PUT request. The string is a simple JSON structure including title and artist 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:

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:

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:


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 app/models/album.rb:

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:

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.

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.

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.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store