Saturday, August 15, 2015

Ruby on Rails on Couch part 1

I use Ruby on Rails everyday for work, and in the past two years have worked on over 9 rails projects.  Recently, our shop has been turning to CouchDB as our database solution because of the excellent features it provides, so today I'm going to explore the basics of CouchDB's RESTful API. If you'd like to follow along with me, you can instal CouchDB here.

CouchDB is a document based database that stores your data as a JSON document.  This format makes it immediately useful for use in any rails app, as it is quite flexible, compact, and fast.  Most ruby developers will be very familiar with this method.

 JSON.parse response  

This method easily converts the JSON into a hash, which is quite easy to work with in Ruby on Rails. Anyway, before we interact with bring any more ruby into the discussion, lets explore the basic CouchDB API through HTTP methods GET, POST, PUT, and DELETE.  If you have installed CouchDB along with me, you can try this out in your terminal.

 $ curl http://127.0.0.1:5984  
 {"couchdb":"Welcome","uuid":"6f2ab581sb4705y52bd470b1e1242z1v","version":"1.6.1","vendor":{"version":"1.6.1","name":"The Apache Software Foundation"}}  

Voilà! Isn't that neat? Lets try creating a database.

 $ curl -X PUT http://127.0.0.1:5984/fubar  
 {"ok":true}  

Excellent! But how can we gather any info about our db? With another GET request of course.

$ curl http://127.0.0.1:5984/fubar  
 {"db_name":"fubar",  
 "doc_count":0,  
 "doc_del_count":0,  
 "update_seq":0,  
 "purge_seq":0,  
 "compact_running":false,  
 "disk_size":79,  
 "data_size":0,  
 "instance_start_time":"1439347017504450",  
 "disk_format_version":6,  
 "committed_update_seq":0}  

We can even add a record to our database!

$ curl -H 'Content-Type: application/json' -X POST http://127.0.0.1:5984/fubar -d '{"Foo": "Bar"}'  
 {"ok":true,  
 "id":"c33480e7b087402adcf32824d90011e8",  
 "rev":"1-9f991710ef01160088e7f4546a8c0b81"}  

This response gives us some important information.  The "id" is as you can probably guess, the identifier of our JSON document.  The "rev" stands for revision, which CouchDB uses to handle any conflicts.  This allows CouchDB give us eventual consistency.  Lets try reading from our document to see if we actually did anything.

 $ curl http://127.0.0.1:5984/fubar/c33480e7b087402adcf32824d90011e8  
 {"_id":"c33480e7b087402adcf32824d90011e8","_rev":"1-9f991710ef01160088e7f4546a8c0b81","Foo":"Bar"}  

Look at that. Our data is right there! How great is that. It's really simple.  That is what is so beautiful about couch.  At it's core, it's dead simple to use.  You can do everything you need through HTTP. Lets take a look at the database info again.

$ curl http://127.0.0.1:5984/fubar 
{"db_name":"fubar",  
 "doc_count":1,  
 "doc_del_count":0,  
 "update_seq":1,  
 "purge_seq":0,  
 "compact_running":false,  
 "disk_size":4185,  
 "data_size":275,  
 "instance_start_time":"1439347017504450",
 "disk_format_version":6,  
 "committed_update_seq":1}  

Here, you can see the changes to the doc_count, update_seq, disk_size, data_size, and committed_update_seq.  Most of these are self explanatory, although I want to touch on three of the fields.  The update_seq represents the number of updates to the database, and its relative comitted_update_seq represented the number of committed updates. The purge_seq represents the number of purges to the database.  A normal delete operation in CouchDB will not delete the document, only mark it with a flag _deleted=true.  A purge on the other hand will permanently remove references to the document to the database. CouchDB warns that this should only be done as a last resort.  They also warn that in a clustered environment that makes use of the replication features, that a purge should be used on all replicated data.  For now, lets just take a look at the DELETE method.

 $ curl -X DELETE 'http://127.0.0.1:5984/fubar/c33480e7b087402adcf32824d90011e8?rev=1-9f991710ef01160088e7f4546a8c0b81'  
 {"ok":true,  
 "id":"c33480e7b087402adcf32824d90011e8",  
 "rev":"2-5c826aa8dbebbe7df9fc34702ae3dd3e"}  

Bam! That should about cover it.  We can delete the document by using its id and rev in the request.

Well, I think I'm going to conclude here.  My plan for the next few post is to explore the different ruby gems that interact with couch, evaluating the pro's and cons of each.

Cheers!




No comments:

Post a Comment