active_column 0.0.2 → 0.1

data/.gitignore

@@ -1,4 +1,5 @@
 pkg/*
+.yardoc/*
 *.gem
 .bundle
 .idea

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected - docs/*.md

data/Gemfile.lock

@@ -1,38 +1,141 @@
 PATH
   remote: .
   specs:
-    active_column (0.0.1)
-      simple_uuid
+    active_column (0.0.3)
+      activesupport
+      cassandra (>= 0.9)
+      rake
 
 GEM
   remote: http://rubygems.org/
   specs:
-    cassandra (0.8.2)
+    ParseTree (3.0.6)
+      RubyInline (>= 3.7.0)
+      sexp_processor (>= 3.0.0)
+    RubyInline (3.8.6)
+      ZenTest (~> 4.3)
+    ZenTest (4.4.2)
+    abstract (1.0.0)
+    actionmailer (3.0.3)
+      actionpack (= 3.0.3)
+      mail (~> 2.2.9)
+    actionpack (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      erubis (~> 2.6.6)
+      i18n (~> 0.4)
+      rack (~> 1.2.1)
+      rack-mount (~> 0.6.13)
+      rack-test (~> 0.5.6)
+      tzinfo (~> 0.3.23)
+    activemodel (3.0.3)
+      activesupport (= 3.0.3)
+      builder (~> 2.1.2)
+      i18n (~> 0.4)
+    activerecord (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+      arel (~> 2.0.2)
+      tzinfo (~> 0.3.23)
+    activeresource (3.0.3)
+      activemodel (= 3.0.3)
+      activesupport (= 3.0.3)
+    activesupport (3.0.3)
+    arel (2.0.6)
+    bluecloth (2.0.9)
+    builder (2.1.2)
+    cassandra (0.9.0)
       json
       rake
       simple_uuid (>= 0.1.0)
-      thrift_client (>= 0.4.0)
+      thrift_client (>= 0.6.0)
     diff-lcs (1.1.2)
+    erubis (2.6.6)
+      abstract (>= 1.0.0)
+    file-tail (1.0.5)
+      spruz (>= 0.1.0)
+    i18n (0.5.0)
     json (1.4.6)
+    mail (2.2.12)
+      activesupport (>= 2.3.6)
+      i18n (>= 0.4.0)
+      mime-types (~> 1.16)
+      treetop (~> 1.4.8)
+    mime-types (1.16)
+    polyglot (0.3.1)
+    predicated (0.2.2)
+    rack (1.2.1)
+    rack-mount (0.6.13)
+      rack (>= 1.0.0)
+    rack-test (0.5.6)
+      rack (>= 1.0)
+    rails (3.0.3)
+      actionmailer (= 3.0.3)
+      actionpack (= 3.0.3)
+      activerecord (= 3.0.3)
+      activeresource (= 3.0.3)
+      activesupport (= 3.0.3)
+      bundler (~> 1.0)
+      railties (= 3.0.3)
+    railties (3.0.3)
+      actionpack (= 3.0.3)
+      activesupport (= 3.0.3)
+      rake (>= 0.8.7)
+      thor (~> 0.14.4)
     rake (0.8.7)
-    rspec (2.2.0)
-      rspec-core (~> 2.2)
-      rspec-expectations (~> 2.2)
-      rspec-mocks (~> 2.2)
-    rspec-core (2.2.1)
-    rspec-expectations (2.2.0)
+    rspec (2.3.0)
+      rspec-core (~> 2.3.0)
+      rspec-expectations (~> 2.3.0)
+      rspec-mocks (~> 2.3.0)
+    rspec-core (2.3.1)
+    rspec-expectations (2.3.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.2.0)
+    rspec-mocks (2.3.0)
+    rspec-rails (2.3.1)
+      actionpack (~> 3.0)
+      activesupport (~> 3.0)
+      railties (~> 3.0)
+      rspec (~> 2.3.0)
+    ruby2ruby (1.2.5)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    ruby_parser (2.0.5)
+      sexp_processor (~> 3.0)
+    sexp_processor (3.0.5)
     simple_uuid (0.1.1)
-    thrift (0.2.0.4)
-    thrift_client (0.5.0)
-      thrift (~> 0.2.0)
+    sourcify (0.4.0)
+      ruby2ruby (>= 1.2.5)
+      sexp_processor (>= 3.0.5)
+    spruz (0.2.2)
+    thor (0.14.6)
+    thrift (0.5.0)
+    thrift_client (0.6.0)
+      thrift (~> 0.5.0)
+    treetop (1.4.9)
+      polyglot (>= 0.3.1)
+    tzinfo (0.3.23)
+    wrong (0.5.0)
+      ParseTree (~> 3.0)
+      diff-lcs (~> 1.1.2)
+      file-tail (~> 1.0)
+      predicated (>= 0.2.2)
+      ruby2ruby (~> 1.2)
+      ruby_parser (~> 2.0.4)
+      sexp_processor (~> 3.0)
+      sourcify (>= 0.3.0)
+    yard (0.6.4)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   active_column!
-  cassandra
-  rspec
-  simple_uuid
+  activesupport
+  bluecloth
+  cassandra (>= 0.9)
+  rails (>= 3.0)
+  rake
+  rspec-rails
+  wrong
+  yard

data/README.md

@@ -1,8 +1,21 @@
+**IMPORTANT**: If you are reading this on the main ActiveColumn page on github, please go to
+[the actual README page](./active_column/blob/master/README.md) so that links bring you to the right place.
+
 # ActiveColumn
 
-ActiveColumn is a framework for saving and retrieving data from Cassandra in a "time line" model.  It 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.
+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](./docs/Migrate.md).
+
+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](./docs/Create.md) - how to create data
+- [Query](./docs/Query.md) - how to find data
 
 ## Installation
 
@@ -20,20 +33,15 @@ bundle install
 
 ### Configuration
 
-ActiveColumn requires the [cassandra gem](https://github.com/fauna/cassandra).  You must provide ActiveColumn with an
-instance of a Cassandra object.  You can do this very simply like this:
-
-<pre>
-ActiveColumn.connection = Cassandra.new('my_keyspace', '127.0.0.1:9160')
-</pre>
+ActiveColumn requires Cassandra 0.7 or above, as we as the [cassandra gem](https://github.com/fauna/cassandra),
+version 0.9 or above.
 
-However, in a real app this is not flexible enough, so I often create a cassandra.yml file and configure Cassandra in an
-initializer.
+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
+_config/cassandra.yml_
 <pre>
 test:
-  home: ":"
   servers: "127.0.0.1:9160"
   keyspace: "myapp_test"
   thrift:
@@ -41,7 +49,6 @@ test:
     retries: 2
 
 development:
-  home: ":"
   servers: "127.0.0.1:9160"
   keyspace: "myapp_development"
   thrift:
@@ -49,7 +56,11 @@ development:
     retries: 2
 </pre>
 
-config/initializers/cassandra.rb
+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_
 <pre>
 config = YAML.load_file(Rails.root.join("config", "cassandra.yml"))[Rails.env]
 $cassandra = Cassandra.new(config['keyspace'],
@@ -63,131 +74,4 @@ As you can see, I create a global $cassandra variable, which I use in my tests t
 
 One other thing to note is that you obviously must have Cassandra installed and running!  Please take a look at the
 [mama_cass gem](https://github.com/carbonfive/mama_cass) for a quick way to get up and running with Cassandra for
-development and testing.
-
-### Saving data
-
-To make a model in to an ActiveColumn model, just extend ActiveColumn::Base, and provide two pieces of information:
-
-- Column Family
-- Function(s) to generate keys for your rows of data
-
-The most basic form of using ActiveColumn looks like this:
-<pre>
-class Tweet &lt; ActiveColumn::Base
-  column_family :tweets
-  key :user_id
-end
-</pre>
-
-Then in your app you can create and save a tweet like this:
-<pre>
-tweet = Tweet.new( :user_id => 'mwynholds', :message => "I'm going for a bike ride" )
-tweet.save
-</pre>
-
-When you run #save, ActiveColumn saves a new column in the "tweets" column family in the row with key "mwynholds".  The
-content of the row is the Tweet instance JSON-encoded.
-
-*Key Generator Functions*
-
-This is great, but quite often you want to save the content in multiple rows for the sake of speedy lookups.  This is
-basically de-normalizing data, and is extremely common in Cassandra data.  ActiveColumn lets you do this quite easily
-by telling it the name of a function to use to generate the keys during a save.  It works like this:
-
-<pre>
-class Tweet &lt; ActiveColumn::Base
-  column_family :tweets
-  key :user_id, :values => :generate_user_keys
-
-  def generate_user_keys
-    [ attributes[:user_id], 'all']
-  end
-end
-</pre>
-
-The code to save the tweet is the same as the previous example, but now it saves the tweet in both the "mwynholds" row
-and the "all" row.  This way, you can pull out the last 20 of all tweets quite easily (assuming you needed to do this
-in your app).
-
-*Compound Keys*
-
-In some cases you may want to have your rows keyed by multiple values.  ActiveColumn supports compound keys,
-and looks like this:
-
-<pre>
-class TweetDM &lt; ActiveColumn::Base
-  column_family :tweet_dms
-  key :user_id,      :values => :generate_user_keys
-  key :recipient_id, :values => :recipient_ids
-
-  def generate_user_keys
-    [ attributes[:user_id], 'all ]
-  end
-end
-</pre>
-
-Now, when you create a new TweetDM, it might look like this:
-
-<pre>
-dm = TweetDM.new( :user_id => 'mwynholds', :recipient_ids => [ 'fsinatra', 'dmartin' ], :message => "Let's go to Vegas" )
-</pre>
-
-This tweet direct message will saved to four different rows in the "tweet_dms" column family, under these keys:
-
-- mwynholds:fsinatra
-- mwynholds:dmartin
-- all:fsinatra
-- all:dmartin
-
-Now my app can pretty easily figure find all DMs I sent to Old Blue Eyes, or to Dino, and it can also easily find all
-DMs sent from *anyone* to Frank or Dino.
-
-One thing to note about the TweetDM class above is that the "keys" configuration at the top looks a little uglier than
-before.  If you have a compound key and any of the keys have custom key generators, you need to pass in an array of
-single-element hashes.  This is in place to support Ruby 1.8, which does not have ordered hashes.  Making sure the keys
-are ordered is necessary to keep the compounds keys canonical (ie: deterministic).
-
-### Finding data
-
-Ok, congratulations - now you have a bunch of fantastic data in Cassandra.  How do you get it out?  ActiveColumn can
-help you here too.
-
-Here is how you look up data that have a simple key:
-
-<pre>
-tweets = Tweet.find( 'mwynholds', :reversed => true, :count => 3 )
-</pre>
-
-This code will find the last 10 tweets for the 'mwynholds' user in reverse order.  It comes back as a hash of arrays,
-and would looks like this if represented in JSON:
-
-<pre>
-{
-  'mwynholds': [ { 'user_id': 'mwynholds', 'message': 'I\'m going to bed now' },
-                 { 'user_id': 'mwynholds', 'message': 'It\'s lunch time' },
-                 { 'user_id': 'mwynholds', 'message': 'Just woke up' } ]
-}
-</pre>
-
-Here are some other examples and their return values:
-
-<pre>
-Tweet.find( [ 'mwynholds', 'all' ], :count => 2 )
-
-{
-  'mwynholds': [ { 'user_id': 'mwynholds', 'message': 'Good morning' },
-                 { 'user_id': 'mwynholds', 'message': 'Good afternoon' } ],
-  'all': [ { 'user_id': 'mwynholds', 'message': 'Good morning' },
-             'user_id': 'bmurray', 'message': 'Who ya gonna call!' } ]
-}
-</pre>
-
-<pre>
-Tweet.find( { 'user_id' => 'all', 'recipient_id' => [ 'fsinatra', 'dmartin' ] }, :reversed => true, :count => 1 )
-
-{
-  'all:fsinatra' => [ { 'user_id': 'mwynholds', 'recipient_ids' => [ 'fsinatra', 'dmartin' ], 'message' => 'Here we come Vegas!' } ],
-  'all:dmartin' => [ { 'user_id': 'fsinatra', 'recipient_ids' => [ 'dmartin' ], 'message' => 'Vegas was fun' } ]
-}
-</pre>
+development and testing.

data/active_column.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |s|
   s.authors     = ["Michael Wynholds"]
   s.email       = ["mike@wynholds.com"]
   s.homepage    = "https://github.com/carbonfive/active_column"
-  s.summary     = %q{Provides time line support for Cassandra}
-  s.description = %q{Provides time line support for Cassandra}
+  s.summary     = %q{Provides time line support and database migrations for Cassandra}
+  s.description = %q{Provides time line support and database migrations for Cassandra}
 
   s.rubyforge_project = "active_column"
 
@@ -18,9 +18,15 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+  s.has_rdoc      = true
 
-  s.add_dependency 'simple_uuid'
-  s.add_dependency 'cassandra'
-  
-  s.add_development_dependency 'rspec'
+  s.add_dependency 'cassandra', '>= 0.9'
+  s.add_dependency 'activesupport'
+  s.add_dependency 'rake'
+
+  s.add_development_dependency 'rails', '>= 3.0'
+  s.add_development_dependency 'rspec-rails'
+  s.add_development_dependency 'wrong'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'bluecloth'
 end

data/docs/Create.md

@@ -0,0 +1,101 @@
+### Saving data
+
+To make a model in to an ActiveColumn model, just extend ActiveColumn::Base, and provide two pieces of information:
+
+- Column Family (optional)
+- Function(s) to generate keys for your rows of data
+
+If you do not specify a column family, it will default to the "tabelized" class name, just like ActiveRecord.
+Example: Tweet --> tweets
+Example: TweetDM --> tweet_dms
+
+The most basic form of using ActiveColumn looks like this:
+<pre>
+class Tweet &lt; ActiveColumn::Base
+  key :user_id
+  attr_accessor :user_id, :message
+end
+</pre>
+
+Note that you can also use ActiveColumn as a mix-in, like this:
+<pre>
+class Tweet
+  include ActiveColumn
+
+  key :user_id
+  attr_accessor :user_id, :message
+end
+</pre>
+
+Then in your app you can create and save a tweet like this:
+<pre>
+tweet = Tweet.new( :user_id => 'mwynholds', :message => "I'm going for a bike ride" )
+tweet.save
+</pre>
+
+When you run #save, ActiveColumn saves a new column in the "tweets" column family in the row with key "mwynholds".  The
+content of the row is the Tweet instance JSON-encoded.
+
+*Key Generator Functions*
+
+This is great, but quite often you want to save the content in multiple rows for the sake of speedy lookups.  This is
+basically de-normalizing data, and is extremely common in Cassandra data.  ActiveColumn lets you do this quite easily
+by telling it the name of a function to use to generate the keys during a save.  It works like this:
+
+<pre>
+class Tweet
+  include ActiveColumn
+
+  key :user_id, :values => :generate_user_keys
+  attr_accessor :user_id, :message
+
+  def generate_user_keys
+    [ user_id, 'all']
+  end
+end
+</pre>
+
+The code to save the tweet is the same as the previous example, but now it saves the tweet in both the "mwynholds" row
+and the "all" row.  This way, you can pull out the last 20 of all tweets quite easily (assuming you needed to do this
+in your app).
+
+*Compound Keys*
+
+In some cases you may want to have your rows keyed by multiple values.  ActiveColumn supports compound keys,
+and looks like this:
+
+<pre>
+class TweetDM
+  include ActiveColumn
+
+  column_family :tweet_dms
+  key :user_id,      :values => :generate_user_keys
+  key :recipient_id, :values => :recipient_ids
+  attr_accessor :user_id, :recipient_ids, :message
+
+  def generate_user_keys
+    [ user_id, 'all ]
+  end
+end
+</pre>
+
+Now, when you create a new TweetDM, it might look like this:
+
+<pre>
+dm = TweetDM.new( :user_id => 'mwynholds', :recipient_ids => [ 'fsinatra', 'dmartin' ], :message => "Let's go to Vegas" )
+</pre>
+
+This tweet direct message will saved to four different rows in the "tweet_dms" column family, under these keys:
+
+- mwynholds:fsinatra
+- mwynholds:dmartin
+- all:fsinatra
+- all:dmartin
+
+Now my app can pretty easily figure find all DMs I sent to Old Blue Eyes, or to Dino, and it can also easily find all
+DMs sent from *anyone* to Frank or Dino.
+
+One thing to note about the TweetDM class above is that the "keys" configuration at the top looks a little uglier than
+before.  If you have a compound key and any of the keys have custom key generators, you need to pass in an array of
+single-element hashes.  This is in place to support Ruby 1.8, which does not have ordered hashes.  Making sure the keys
+are ordered is necessary to keep the compounds keys canonical (ie: deterministic).