Couched

A simple ruby API for basic, low-level access to CouchDB.

Installation

Couched is distributed as a gem. Install it:

  $ gem install couched

Then require it in your project:

require 'couched'

If your project uses bundler, simply add the following to your Gemfile and run bundle install:

gem "couched"

Setting up a connection to CouchDB

You can setup a connection to CouchDB by simply creating a new Couched instance:

client = Couched.new

When called without any arguments, Couched will attempt to connect to a CouchDB server running at http://localhost:5984.

To override this default, simply pass a url to the new method:

client = Couched.new "http://1.2.3.4:5678"

Authentication

Couched currently only supports http basic-auth. You can either add it to the URL when you create a Couched, or you can set it up after create using the username and password fields:

authenticated_client = Couched.new "http://me:pass@localhost:5984"

or...

authenticated_client = Couched.new
authenticated_client.username = "me"
authenticated_client.password = "pass"

Accessing / Creating / Deleting databases

Once you have a client, you can then gain access to an existing database via the database method:

client = Couched.new
article_database = client.database "articles"

You can create a database via the database! method. If the database does not yet exist, it will be created, and a database object will be returned. If the databaes already exists, then a database object will simply be returned.

article_database = Couched.new.database! "articles"

Creating / Updating / Deleting Design Documents

To create or update a design document, use the design! method on a database instance:

db = Couched.new.database! "articles"

# create a design document "\_design/articles" with a "by\_title" view:
db.design!(
  "articles",
  "views" => {
    "by_title" => {
      "map" => "function(doc){ emit(doc.title, null); }",
      "reduce" => "_count"
    }
  }
)

K/V document access

A database object will act like a collection of documents, letting you easily add documents to the database via the post method, and remove documents from the database via the delete method. You can update documents via the put method. And lastly, you can retrieve documents via the get method.

Creating a document

Suppose we'd like to place the following JSON representation of an article into our "articles" database:

{
  "title": "couched: Simple CouchDB API, plug-n-play HTTP adapters",
  "author": "moonmaster9000",
  "content": "couched is a new low-level ruby API for working with CouchDB"
}

Autogenerated ID

If we don't care about the id of the document we'd like to create, then we can add this document to our database via the post method:

db = Couched.new.database! "articles"

doc = db.post({
  "title"   => "couched: Simple CouchDB API, plug-n-play HTTP adapters",
  "author"  => "moonmaster9000",
  "content" => "couched is a new low-level ruby API for working with CouchDB"
})

This posted the document to CouchDB, returning a new hash object representing what CouchDB stored in the database. In addition to the properties you supplied, it will also include an "_id" and "_rev" property:

puts doc["_id"]     #==> 890432ijrewuioreu9084209
puts doc["_rev"]    #==> 1-8904328903jklrewjlrjdsl8r9032840
puts doc["title"]   #==> "couched: Simple CouchDB API, plug-n-play HTTP adapters"
puts doc["author"]  #==> "moonmaster9000"
puts doc["content"] #==> "couched is a new low-level ruby API for working with CouchDB"

Specified ID

If you would rather specify the id of your document, you can do so by either adding it to your hash, or by accessing it by key on your database:

doc = db.post({
  "_id"     => "couched-simple-couchdb-api",
  "title"   => "couched: Simple CouchDB API, plug-n-play HTTP adapters",
  "author"  => "moonmaster9000",
  "content" => "couched is a new low-level ruby API for working with CouchDB"
})

or...

db["couched-simple-couchdb-api"] = {
  "title"   => "couched: Simple CouchDB API, plug-n-play HTTP adapters",
  "author"  => "moonmaster9000",
  "content" => "couched is a new low-level ruby API for working with CouchDB"
}

or...

doc = db.put(
  "couched-simple-couchdb-api", 
  "title"   => "couched: Simple CouchDB API, plug-n-play HTTP adapters",
  "author"  => "moonmaster9000",
  "content" => "couched is a new low-level ruby API for working with CouchDB"
)

Either way, we'd end up with the following document:

puts doc.inspect
  #==>
    { 
      "_id"     => "couched-simple-couchdb-api",
      "_rev"    => "1-894032890483920rewioruewior89043820",
      "title"   => "couched: Simple CouchDB API, plug-n-play HTTP adapters",
      "author"  => "moonmaster9000",
      "content" => "couched is a new low-level ruby API for working with CouchDB"
    }

Updating a document

You can update a document by either the put method or the []= method.

Continuing with our article example, let's imagine that we'd like to update the "author" property. First, let's retrieve our article:

doc = db.get "couched-simple-couchdb-api"
# or...
doc = db["couched-simple-couchdb-api"]

Next, let's imagine that we want to update our article by changing the "author" property.

Querying

You can query views defined in a design document using the design and view methods on a database instance:

# query the "by\_title" view in the \_design/articles design document
db.design("articles").view("by_title").query

You can pass options to the query via a hash:

db.design("articles").view("by_title").query :startkey => "z", :endkey => "a", :descending => "true"

You'll receieve the JSON response as a hash:

db.design("articles").view("by_title").query :startkey => "z", :endkey => "a", :descending => "true"
#==> 
  {
    "rows" => [
      { "key" => "Zebra Escapes From the Zoo!", "value" => null, "_id" => "893208190328190382109312" },
      #....
    ]
  }

Show

List