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 gems:

  $ sudo gem install 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

Copyright © 2009 Zachary Zolton. See LICENSE for details.