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

Basic usage and Rails configuration

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:

curl 7.47.0 (x86_64-pc-linux-gnu) libcurl/7.47.0 GnuTLS/3.4.10 zlib/1.2.8 libidn/1.32 librtmp/2.3
Protocols: dict file ftp ftps gopher http https imap imaps ldap ldaps pop3 pop3s rtmp rtsp smb smbs smtp smtps telnet tftp
Features: AsynchDNS IDN IPv6 Largefile GSS-API Kerberos SPNEGO NTLM NTLM_WB SSL libz TLS-SRP UnixSockets

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:

curl -X GET http://127.0.0.1:5984/_all_dbs

The response should look like:

["_replicator","_users"]

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

curl -X PUT http://127.0.0.1:5984/demo_database

CouchDB will reply with:

{"ok":true}

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

curl -X GET http://127.0.0.1:5984/_all_dbs
["demo_database"]

Let’s create a second database:

curl -X PUT http://127.0.0.1:5984/demo_database_to_delete

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

curl -X GET http://127.0.0.1:5984/_all_dbs
["demo_database", "demo_database_to_delete"]

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

curl -X DELETE http://127.0.0.1:5984/demo_database_to_delete

CouchDB will reply with:

{"ok":true}

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

curl -X GET http://127.0.0.1:5984/_all_dbs
["demo_database"]

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

curl -X PUT http://127.0.0.1:5984/demo_database/6e1295ed6c29495e54cc05947f18c8af -d '{"title":"There is Nothing Left to Lose","artist":"Foo Fighters"}'

and CouchDB should respond something similar to this:

{"ok":true,"id":"6e1295ed6c29495e54cc05947f18c8af","rev":"1-2902191555"}

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:

curl -X GET http://127.0.0.1:5984/demo_database/6e1295ed6c29495e54cc05947f18c8af

CouchDB replies:

{"_id":"6e1295ed6c29495e54cc05947f18c8af","_rev":"1-2902191555","title":"There is Nothing Left to Lose","artist":"Foo Fighters"}

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.

Install

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.

Configuration

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:

development:
  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'
end
# The database object would be provided as:
Project.database     #=> "https://test:user@sample.cloudant.com:443/project_sample_test"

Generators

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

  timestamps!

  design do
    view :by_title
    view :by_artist_and_year
  end

end

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.save

@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
end
# 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

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.

Conclussion

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

• https://www.linkedin.com/in/albertoaragonalvarez/
• alberto@alturasoluciones.com
• https://twitter.com/aragonalvarez85