IMPORTANT: If you are reading this on the main ActiveColumn page on github, please go to the actual README page so that links bring you to the right place.

ActiveColumn

ActiveColumn is a framework for working with data in Cassandra. It currently includes two features:

• Database migrations
• "Time line" model data management

Data migrations are very similar to those in ActiveRecord, and are documented in Migrate.

Time line data management is loosely based on concepts in ActiveRecord, but is adapted to saving data in which rows in Cassandra grow indefinitely over time, such as in the oft-used Twitter example for Cassandra. This usage is documented in:

• Create - how to create data
• Query - how to find data

Installation

Add ActiveColumn to your Gemfile:

gem 'active_column'

Install with bundler:

bundle install

Usage

Configuration

ActiveColumn requires Cassandra 0.7 or above, as well as the cassandra gem, version 0.9 or above. You must also be sure to use the Cassandra 0.7 support in the gem, which can be done by adding Cassandra to your Gemfile like this:

gem 'cassandra', '>= 0.9', :require => 'cassandra/0.7'

Data migrations in ActiveColumn are used within a Rails project, and are driven off of a configuration file, config/cassandra.yml. It should look something like this:

config/cassandra.yml

test:
  servers: "127.0.0.1:9160"
  keyspace: "myapp_test"
  thrift:
    timeout: 3
    retries: 2

development:
  servers: "127.0.0.1:9160"
  keyspace: "myapp_development"
  thrift:
    timeout: 3
    retries: 2

You can use embedded ruby code in the YAML file to determine host/machine specific settings.

  production:
    servers: "<%=get_from_file('abc.conf')%>:9160"
    keyspace: "<%=get_from_file('abc.conf')%>"
    disable_node_auto_discovery: true
    thrift:
      timeout: 3
      retries: 2

Node Auto Discovery

You can set disable_node_auto_discovery to off by setting disable_node_auto_discovery flag in your cassandra.yml

In order to get time line modeling support, you must provide ActiveColumn with an instance of a Cassandra object. Since you have your cassandra.yml from above, you can do this very simply like this:

config/initializers/cassandra.rb

config = YAML.load_file(Rails.root.join("config", "cassandra.yml"))[Rails.env]
$cassandra = Cassandra.new(config['keyspace'],
                           config['servers'],
                           config['thrift'])

ActiveColumn.connection = $cassandra

As you can see, I create a global $cassandra variable, which I use in my tests to validate data directly in Cassandra.

Examples

Add column family

  create_column_family :impressions do |cf|
    cf.comment = 'impressions for something'
    cf.comparator_type = :utf8 
    cf.key_validation_class = :utf8 
  end

Drop column family

  drop_column_family :impressions

Rename column family

  rename_column_family :impressions, :showings

Update column family

  update_column_family :impressions do |cf|
    cf.comment = "blah"
    cf.gc_grace_seconds = 3600
  end

One other thing to note is that you obviously must have Cassandra installed and running! Please take a look at the mama_cass gem for a quick way to get up and running with Cassandra for development and testing.