© Copyright Quoin Inc/ 2016

CouchDB And Its Usage In Primero

What is CouchDB?● NoSQL Database● No hard schema like a traditional SQL database● Data is implemented in JSON files● Interactions made via an HTTP API● The database runs on port 5984● Map/Reduce indexes and queries are written in JavaScript● Built-in node-to-node replication allows data to be synced between registered

database nodes● All records are automatically versioned● http://couchdb.apache.org/

Futon● Built-in web based interface● Tool used by developers to query / inspect the data● Can access locally at http://localhost:5984/_utils/● We set up port forwarding to be able to connect to CouchDB instances

running on our test servers.

Why CouchDB?● Flexibility

○ Changes can be made via JSON files without the need to change the application code or DB schema

○ We have “Forms” which are uploaded as JSON and translate to Web forms in the application.

○ Users have an interface in the Primero application that allows them to edit these forms, add/edit fields on the forms, or create custom forms.

○ We have JSON config files that can be uploaded to configure instances for different locations needs.

○ Those JSON config files contain the forms and other data settings

○ Some properties are hard coded in the model but most are just part of these configurable forms

○ The properties defined on the forms act like the properties defined directly within the model○ All of these properties are stored in CouchDB

Why CouchDB?● Replication

○ We have the ability to transfer data from one Primero instance to another.○ An example use of this is for sharing data between Agencies or Locations.

Implementation● Rails gem ‘CouchRest Model’ https://github.com/couchrest/couchrest_model● CouchRest helps us to define models that relate to the CouchDB tables● class Location < CouchRest::Model::Base● CouchRest is built on rails ActiveRecord, so many of the methods in

ActiveRecord are available to use● http://www.couchrest.info/

Configuration - yaml

Basic Queries● The basic ActiveRecord query methods are available● Example for model Location

○ Location.all○ Location.first○ Location.last○ Location.count○ Location.get○ Location.find

Basic Queries

2.1.5-railsexpress :001 > Location.first

=> #<Location name: "Sierra Leone::Western Area::Western Area Urban (Freetown)::West III", description: nil, disabled: false, placename: "West III", location_code: "SLE040208", type: "chiefdom", hierarchy: ["Sierra Leone", "Western Area", "Western Area Urban (Freetown)"], hierarchical_name: nil, admin_level: nil, _id: "2702e0868980528ca6011dd7171a509c", _rev: "1-b376271b8c27b09f0748635967d0f7f6", couchrest-type: "Location">

2.1.5-railsexpress :002 >

Views “Views are the method of aggregating and reporting on the documents in a database, and are built on-demand to aggregate, join and report on database documents. Views are built dynamically and don’t affect the underlying document; you can have as many different view representations of the same data as you like. Incremental updates to documents do not require full re-indexing of views.”

https://cwiki.apache.org/confluence/display/COUCHDB/Introduction

Views ● In a view, you are only setting up the index keys that you will use later in the

code to fetch your data● It is a different mindset than a traditional SQL query● The majority of our querying work is done via views● Implemented in the model within a “design” block

Views - basic example

Basic View Query

2.1.5-railsexpress :001 > Location.by_placename(key: 'Barri').all

=> [#<Location name: "Sierra Leone::Southern::Pujehun::Barri", description: nil, disabled: false, placename: "Barri", location_code: "Bar", type: "chiefdom", hierarchy: ["Sierra Leone", "Southern", "Pujehun"], hierarchical_name: nil, admin_level: 3, _id: "2702e0868980528ca6011dd7171b790d", _rev: "2-c1d5861d5c25ed30a88abbe8d21ca2c7", couchrest-type: "Location">]

2.1.5-railsexpress :002 >

Basic View Query2.1.5-railsexpress :002 > Location.by_placename(keys: ['Barri', 'Guinea']).all

=> [#<Location name: "Sierra Leone::Southern::Pujehun::Barri", description: nil, disabled: false, placename: "Barri", location_code: "Bar", type: "chiefdom", hierarchy: ["Sierra Leone", "Southern", "Pujehun"], hierarchical_name: nil, admin_level: 3, _id: "2702e0868980528ca6011dd7171b790d", _rev: "2-c1d5861d5c25ed30a88abbe8d21ca2c7", couchrest-type: "Location">, #<Location name: "Guinea", description: nil, disabled: false, placename: "Guinea", location_code: nil, type: "country", hierarchy: [], hierarchical_name: nil, admin_level: 0, _id: "de880371e27be1943da49b539f33ff33", _rev: "2-c0b00e76fa091558630366bc31e16c7e", couchrest-type: "Location">]

2.1.5-railsexpress :003 >

Views - basic example

Basic View Query2.1.5-railsexpress :003 > Location.by_admin_level_and_name(key: [3, 'Sierra Leone::Southern::Pujehun::Barri']).all

=> [#<Location name: "Sierra Leone::Southern::Pujehun::Barri", description: nil, disabled: false, placename: "Barri", location_code: "Bar", type: "chiefdom", hierarchy: ["Sierra Leone", "Southern", "Pujehun"], hierarchical_name: nil, admin_level: 3, _id: "2702e0868980528ca6011dd7171b790d", _rev: "2-c1d5861d5c25ed30a88abbe8d21ca2c7", couchrest-type: "Location">]

2.1.5-railsexpress :004 >

Basic View Query2.1.5-railsexpress :004 > Location.by_admin_level_and_name(key: [4, 'Sierra Leone::Southern::Pujehun::Barri']).all

=> []

2.1.5-railsexpress :005 >

Basic View Query2.1.5-railsexpress :005 > Location.by_admin_level_and_name(keys: [[3, 'Sierra Leone::Southern::Pujehun::Barri'], [4, 'Sierra Leone::Southern::Pujehun::Barri']]).all

=> [#<Location name: "Sierra Leone::Southern::Pujehun::Barri", description: nil, disabled: false, placename: "Barri", location_code: "Bar", type: "chiefdom", hierarchy: ["Sierra Leone", "Southern", "Pujehun"], hierarchical_name: nil, admin_level: 3, _id: "2702e0868980528ca6011dd7171b790d", _rev: "2-c1d5861d5c25ed30a88abbe8d21ca2c7", couchrest-type: "Location">]

2.1.5-railsexpress :006 >

Basic View Query2.1.5-railsexpress :006 > Location.by_ancestor(key: 'Bombali').all

=> [#<Location name: "Sierra Leone::Northern::Bombali::Tambakha", description: nil, disabled: false, placename: "Tambakha", location_code: "Tam", type: "chiefdom", hierarchy: ["Sierra Leone", "Northern", "Bombali"], hierarchical_name: nil, admin_level: 3, _id: "2702e0868980528ca6011dd7171e3ece", _rev: "2-7b65039920ad5ed8cefa2ead7366603c", couchrest-type: "Location">, #<Location name: "Sierra Leone::Northern::Bombali::Sella Limba", description: nil, disabled: false, placename: "Sella Limba", location_code: "SeL", type: "chiefdom", hierarchy: ["Sierra Leone", "Northern", "Bombali"], hierarchical_name: nil, admin_level: 3, _id: "2702e0868980528ca6011dd7171e463b", _rev: "2-b602b394c885acc8030abce911a106af", couchrest-type: "Location">, #<Location name: "Sierra Leone::Northern::Bombali::Sanda Tenraren", ...

Basic View Query2.1.5-railsexpress :007 > Location.by_ancestor(key: 'Bombali').all.count

=> 13

2.1.5-railsexpress :008 >

Views - find a range