No commit activity in last 3 years
No release in over 3 years
Opinionated management and usage of CouchDB from your Ruby apps.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

Cambric¶ ↑

Mildly opinionated management and usage of CouchDB from your Ruby apps.

Cambric supports applications that wish to use multiple CouchDB databases/hosts, in a manner that wont muck up your application code. Moreover, it encourages you to use one design document per database used by the application.

BTW, there’s nothing specific to Rails in how this works. (^_-)

Usage¶ ↑

1) Configure the Cambric instances:

Cambric.configure do |config|
  config.design_doc_name = 'twitter-clone'
  config.environment = ENV['RAILS_ENV']

  config.databases = {
    :users => {
      :development => 'http://127.0.0.1:5984/users-development',
      :test => 'http://127.0.0.1:5984/users-test',
      :production => 'http://prod.server:5984/users'
    },
    :tweets => {
      :development => 'http://127.0.0.1:5984/tweets-development',
      :test => 'http://127.0.0.1:5984/tweets-test',
      :production => 'http://prod.server:5984/tweets'
    }
  }
end

2) Use one of the following methods:

Cambric.prepare_database  # Creates databases for the configured environment
                          # and pushes up their design docs.

Cambric.prepare_database! # Or, the bang method forcibly recreates your
                          # databases for the configured environment.

3) Interact with CouchRest::Database instances:

tweet_db = Cambric[:tweets]

# Just like normal...
tweet_db.save_doc :author => 'marbles',
                  :message => 'Is this pork or beef, @Randy?',
                  :followers => ['randy','zdzolton','trevorturk'],
                  :created_at => Time.now

# Except, you do NOT need to re-specify the design doc name when
# calling CouchRest::Database#view —since you're only using one!
tweet_db.view 'by_follower_and_created_at', :limit => 1

# Also, we can auto-cast doc from map-only views for you!
tweet_db.get_docs_from_view :by_follower_and_created_at, :cast_as => 'type'
# Or:
tweet_db.get_docs_from_view :by_follower_and_created_at, :cast_as => Tweet

4) Write unit tests for your JavaScript map-reduce functions:

class CambricViewTest < ActiveSupport::TestCase
  include Cambric::TestHelpers

  test "should map a user to be keyed by who he follows" do
    kv_pairs = execute_map :users,                                               # Database name
                           :followers,                                           # View name
                           '_id' => 'poddle', 'following' => ['jack', 'russel']  # Document attributes

    assert_equal 2, kv_pairs.size
    assert_equal 'jack',   kv_pairs[0]['key']
    assert_equal 'poddle', kv_pairs[0]['value']
    assert_equal 'russel', kv_pairs[1]['key']
    assert_equal 'poddle', kv_pairs[1]['value']
  end

  test "should reduce to a count of followers for a user" do
    count = execute_reduce :users,                         # Database name
                           :followers,                     # View name
                           :values => ['poddle', 'larry']  # :keys don't matter for this reduce
    assert_equal 2, count
  end

  test "should re-reduce counts of followers for a user" do
    count = execute_reduce :users,                # Database name
                           :followers,            # View name
                           :values => [2, 5, 1], 
                           :rereduce => true      # defaults to false
    assert_equal 8, count
  end

end

5) Push view/design doc changes to CouchDB:

Cambric.push_design_docs

# Alternatively, you can just call this, since it wont create
# your database, if they already exist:
Cambric.prepare_database

# Now for the real trick! This invocation will block until
# your changed design docs have primed their views:
Cambric.prime_view_changes_in_temp

Installation¶ ↑

  • Install couchapp:

    (Assuming you have Python) $ sudo easy_install -U couchapp

  • Install gems:

    $ sudo gem install rest-client couchrest-couchrest zdzolton-cambric

  • Configure Rails:

    • create a config/initializers/cambric.rb file as follows:

      Cambric.configure do |config|
        config.design_doc_name = 'YOUR_APP_NAME'
        config.environment = RAILS_ENV
      
        config.databases = {
          :YOUR_DB_NAME => {
            :development => "http://localhost:5984/YOUR_DB_NAME-development",
            :test => "http://localhost:5984/YOUR_DB_NAME-test"
          },
          :YOUR_OTHER_DB => {
            :development => "http://localhost:5984/YOUR_OTHER_DB-development",
            :test => "http://localhost:5984/YOUR_OTHER_DB-test"
          }
        }
      end
      
      ActionController::Dispatcher.to_prepare(:cambric) do
        case RAILS_ENV
        when 'test'
          Cambric.prepare_databases!
        when 'production'
          # Let's not automagically do anything!
        else
          Cambric.prepare_databases
        end
      end
      
    • create a couchdb directory within your project:

      $ cd /your/app/root
      $ mkdir -p ./couchdb/your_db/views/some_view_name

Copyright © 2009 Zachary Zolton. See LICENSE for details.