cassandra 0.11.0 → 0.11.1

data/CHANGELOG

@@ -1,3 +1,13 @@
+v0.11.1
+- Add counter support for Cassandra 0.8. (Thanks Swrve team!)
+- Add additional rake tasks to start and stop cassandra in the background.
+- Fix issue with non-utf8 column names not being encoded/decoded properly.
+- Add way to specify a default read/write consistency.
+- Consolidate 0.7 and 0.8 functions, and move 0.6 specific functions into lib/cassandra/0.6/
+- Use 0.8-rc1 as 0.8 install target.
+- Updated get_index_slices API to allow passing an array of hashes instead of IndexClause instance. (Maintains backward compatibility.)
+- Fix permissions issue.
+
 v0.11.0
 - Remove direct thrift dependency. Allow thrift_client to require it.
 - Add functions for each and each_key to iterate through key ranges.

data/Manifest

@@ -1,5 +1,9 @@
-bin/cassandra_helper
 CHANGELOG
+LICENSE
+Manifest
+README.md
+Rakefile
+bin/cassandra_helper
 conf/0.6/cassandra.in.sh
 conf/0.6/log4j.properties
 conf/0.6/schema.json
@@ -14,38 +18,33 @@ conf/0.8/cassandra.yaml
 conf/0.8/log4j-server.properties
 conf/0.8/schema.json
 conf/0.8/schema.txt
+lib/cassandra.rb
+lib/cassandra/0.6.rb
 lib/cassandra/0.6/cassandra.rb
 lib/cassandra/0.6/columns.rb
 lib/cassandra/0.6/protocol.rb
-lib/cassandra/0.6.rb
+lib/cassandra/0.7.rb
 lib/cassandra/0.7/cassandra.rb
-lib/cassandra/0.7/column_family.rb
 lib/cassandra/0.7/columns.rb
-lib/cassandra/0.7/keyspace.rb
 lib/cassandra/0.7/protocol.rb
-lib/cassandra/0.7.rb
+lib/cassandra/0.8.rb
 lib/cassandra/0.8/cassandra.rb
-lib/cassandra/0.8/column_family.rb
 lib/cassandra/0.8/columns.rb
-lib/cassandra/0.8/keyspace.rb
 lib/cassandra/0.8/protocol.rb
-lib/cassandra/0.8.rb
 lib/cassandra/array.rb
 lib/cassandra/cassandra.rb
+lib/cassandra/column_family.rb
 lib/cassandra/columns.rb
 lib/cassandra/comparable.rb
 lib/cassandra/constants.rb
 lib/cassandra/debug.rb
 lib/cassandra/helpers.rb
+lib/cassandra/keyspace.rb
 lib/cassandra/long.rb
 lib/cassandra/mock.rb
 lib/cassandra/ordered_hash.rb
+lib/cassandra/protocol.rb
 lib/cassandra/time.rb
-lib/cassandra.rb
-LICENSE
-Manifest
-Rakefile
-README.rdoc
 test/cassandra_client_test.rb
 test/cassandra_mock_test.rb
 test/cassandra_test.rb

data/README.md

@@ -0,0 +1,344 @@
+# cassandra 
+A Ruby client for the Cassandra distributed database.
+
+* [Getting Started](#getting-started)
+* [License](#license)
+* [Cassandra Version](#cassandra-version)
+* [Read/Write API Method Reference](#read-write-api-method-reference)
+
+## Getting Started
+
+Here is a quick sample of the general use (more details in Read/Write
+API below):
+
+    require 'cassandra'
+    client = Cassandra.new('Twitter', '127.0.0.1:9160')
+    client.insert(:Users, "5", {'screen_name' => "buttonscat"})
+
+## License
+
+Copyright 2009, 2010 Twitter, Inc. See included LICENSE file. Portions copyright 2004-2009 David Heinemeier Hansson, and used with permission.
+
+## Cassandra Version
+
+The Cassandra project is under very active development, and as such
+there are a few different versions that you may need to use this gem
+with.  We have set up an easy sure fire mechanism for selecting the
+specific version that you are connecting to while requiring the gem.
+
+#### Require Method
+The default version is the currently stable release of cassandra.  (0.7
+at this time, but 0.8 is looming in the near future.)
+
+To use the default version simply use a normal require:
+    require 'cassandra'
+
+To use a specific version (0.7 in this example) you would use a 
+slightly differently formatted require:
+    require 'cassandra/0.7'
+
+#### Environment Variable Method
+These mechanisms work well when you are using the cassandra gem in your
+own projects or irb, but if you would rather not hard code your app to a
+specific version you can always specify an environment variable with the
+version you are using:
+    export CASSANDRA_VERSION=0.7
+
+Then you would use the default require as listed above:
+    require 'cassandra'
+
+## Read/Write API Method Reference
+
+### insert
+
+* column\_family - The column\_family that you are inserting into.
+* key - The row key to insert.
+* hash - The columns or super columns to insert.
+* options - Valid options are:
+  * :timestamp - Uses the current time if none specified.
+  * :consistency - Uses the default write consistency if none specified.
+  * :ttl - If specified this is the number of seconds after the insert that this value will be available.
+
+This is the main method used to insert rows into cassandra. If the
+column\_family that you are inserting into is a SuperColumnFamily then
+the hash passed in should be a nested hash, otherwise it should be a
+flat hash.
+
+This method can also be called while in batch mode. If in batch mode
+then we queue up the mutations (an insert in this case) and pass them to
+cassandra in a single batch at the end of the block.
+
+Example:
+
+    @client.insert(:Statuses, key, {'body' => 'v', 'user' => 'v'})
+
+    columns = {@uuids[1] => 'v1', @uuids[2] => 'v2'}
+    @client.insert(:StatusRelationships, key, {'user_timelines' => columns})
+
+
+### remove
+
+* column\_family - The column\_family that you are inserting into.
+* key - The row key to insert.
+* columns - Either a single super_column or a list of columns.
+* sub_columns - The list of sub\_columns to select.
+* options - Valid options are:
+  * :timestamp - Uses the current time if none specified.
+  * :consistency - Uses the default write consistency if none specified.
+
+This method is used to delete (actually marking them as deleted with a
+tombstone) columns or super columns.
+
+Example:
+    @client.insert(:Statuses, key, {'body' => 'v', 'subject' => 'v'})
+
+    @client.remove(:Statuses, key, 'body')    # removes the 'body' column
+    @client.remove(:Statuses, key)            # removes the row
+
+### count\_columns
+
+Count the columns for the provided parameters.
+
+* column\_family - The column\_family that you are inserting into.
+* key - The row key to insert.
+* columns - Either a single super_column or a list of columns.
+* sub_columns - The list of sub\_columns to select.
+* options - Valid options are:
+  * :consistency - Uses the default read consistency if none specified.
+
+Example:
+    @client.insert(:Statuses, key, {'body' => 'v1', 'user' => 'v2'})
+    @client.count_columns(:Statuses, key)     # returns 2
+
+### get
+
+Return a hash (actually, a Cassandra::OrderedHash) or a single value
+representing the element at the column_family:key:[column]:[sub_column]
+path you request. 
+
+* column\_family - The column\_family that you are inserting into.
+* key - The row key to insert.
+* columns - Either a single super\_column or a list of columns.
+* sub\_columns - The list of sub\_columns to select.
+* options - Valid options are:
+  * :count    - The number of columns requested to be returned.
+  * :start    - The starting value for selecting a range of columns.
+  * :finish   - The final value for selecting a range of columns.
+  * :reversed - If set to true the results will be returned in
+                reverse order.
+  * :consistency - Uses the default read consistency if none specified.
+
+Example:
+    @client.insert(:Users, key, {'body' => 'v', 'user' => 'v'})
+    @client.get(:Users, key))           # returns {'body' => 'v', 'user' => 'v'}
+
+### multi\_get
+
+Multi-key version of Cassandra#get.
+
+This method allows you to select multiple rows with a single query.
+If a key that is passed in doesn't exist an empty hash will be
+returned.
+
+Supports the same parameters as Cassandra#get.
+
+* column_family - The column_family that you are inserting into.
+* key - An array of keys to.
+* columns - Either a single super_column or a list of columns.
+* sub_columns - The list of sub\_columns to select.
+* options - Valid options are:
+  * :count    - The number of columns requested to be returned.
+  * :start    - The starting value for selecting a range of columns.
+  * :finish   - The final value for selecting a range of columns.
+  * :reversed - If set to true the results will be returned in reverse order.
+  * :consistency - Uses the default read consistency if none specified.
+
+Example:
+
+    @client.insert(:Users, '1', {'body' => 'v1', 'user' => 'v1'})
+    @client.insert(:Users, '2', {'body' => 'v2', 'user' => 'v2'})
+
+    expected = OrderedHash[
+                  '1', {'body' => 'v1', 'user' => 'v1'}, 
+                  '2', {'body' => 'v2', 'user' => 'v2'}, 
+                  'bogus', {}
+              ]
+    result = @client.multi_get(:Users, ['1', '2', 'bogus'])
+
+### exists?
+
+Return true if the column\_family:key:[column]:[sub\_column] path you
+request exists.
+
+If passed in only a row key it will query for any columns (limiting
+to 1) for that row key. If a column is passed in it will query for
+that specific column/super column.
+
+This method will return true or false.
+
+* column\_family - The column\_family that you are inserting into.
+* key - The row key to insert.
+* columns - Either a single super\_column or a list of columns.
+* sub\_columns - The list of sub\_columns to select.
+* options - Valid options are:
+  * :consistency - Uses the default read consistency if none specified.
+
+Example:
+
+    @client.insert(:Statuses, 'key', {'body' => 'v'})
+    @client.exists?(:Statuses, 'key')                   # returns true
+    @client.exists?(:Statuses, 'bogus')                 # returns false
+    @client.exists?(:Statuses, 'key', 'body')           # returns true
+    @client.exists?(:Statuses, 'key', 'bogus')          # returns false
+
+### get\_range
+Return an Cassandra::OrderedHash containing the columns specified for the given
+range of keys in the column\_family you request.
+
+This method is just a convenience wrapper around Cassandra#get_range_single
+and Cassandra#get\_range\_batch. If :key\_size, :batch\_size, or a block
+is passed in Cassandra#get\_range\_batch will be called. Otherwise
+Cassandra#get\_range\_single will be used.
+
+The start\_key and finish\_key parameters are only useful for iterating of all records
+as is done in the Cassandra#each and Cassandra#each\_key methods if you are using the 
+RandomPartitioner.
+
+If the table is partitioned with OrderPreservingPartitioner you may
+use the start\_key and finish\_key params to select all records with
+the same prefix value.
+
+If a block is passed in we will yield the row key and columns for
+each record returned.
+
+Please note that Cassandra returns a row for each row that has existed in the
+system since gc\_grace\_seconds. This is because deleted row keys are marked as 
+deleted, but left in the system until the cluster has had resonable time to replicate the deletion.
+This function attempts to suppress deleted rows (actually any row returned without
+columns is suppressed).
+
+* column\_family - The column\_family that you are inserting into.
+* key - The row key to insert.
+* columns - Either a single super\_column or a list of columns.
+* sub\_columns - The list of sub\_columns to select.
+* options - Valid options are:
+  * :start\_key    - The starting value for selecting a range of keys (only useful with OPP).
+  * :finish\_key   - The final value for selecting a range of keys (only useful with OPP).
+  * :key\_count    - The total number of keys to return from the query. (see note regarding deleted records)
+  * :batch\_size   - The maximum number of keys to return per query. If specified will loop until :key\_count is obtained or all records have been returned.
+  * :count        - The number of columns requested to be returned.
+  * :start        - The starting value for selecting a range of columns.
+  * :finish       - The final value for selecting a range of columns.
+  * :reversed     - If set to true the results will be returned in reverse order.
+  * :consistency  - Uses the default read consistency if none specified.
+
+Example:
+
+    10.times do |i|
+      @client.insert(:Statuses, i.to_s, {'body' => '1'})
+    end
+
+    @client.get_range_keys(:Statuses, :key_count => 4)
+
+    # returns:
+    #{
+    #  '0' => {'body' => '1'},
+    #  '1' => {'body' => '1'},
+    #  '2' => {'body' => '1'},
+    #  '3' => {'body' => '1'}
+    #}
+
+### count\_range
+
+Return an Array containing all of the keys within a given range.
+
+This method just calls Cassandra#get\_range and returns the
+row keys for the records returned.
+
+See [Cassandra#get\_range](#get-range) for options.
+
+### get\_range\_keys
+
+Return an Array containing all of the keys within a given range.
+
+This method just calls Cassandra#get\_range and returns the
+row keys for the records returned.
+
+See [Cassandra#get\_range](#get-range) for options.
+
+### each\_key
+Iterate through each key within the given range parameters. This function can be
+used to iterate over each key in the given column family.
+
+This method just calls Cassandra#get\_range and yields each row key.
+
+See [Cassandra#get\_range](#get-range) for options.
+
+Example:
+    10.times do |i|
+      @client.insert(:Statuses, k + i.to_s, {"body-#{i.to_s}" => 'v'})
+    end
+
+    @client.each_key(:Statuses) do |key|
+      print key
+    end
+
+    # returns 0123456789
+
+### each
+Iterate through each row within the given column\_family.
+
+This method just calls Cassandra#get\_range and yields the key and
+columns.
+
+See [Cassandra#get\_range](#get-range) for options.
+
+### get\_index\_slices
+This method is used to query a secondary index with a set of
+provided search parameters
+
+Please note that you can either specify a
+CassandraThrift::IndexClause or an array of hashes with the
+format as below.
+
+* column\_family     - The Column Family this operation will be run on.
+* index\_clause      - This can either be a CassandraThrift::IndexClause or an array of hashes with the following keys:
+  * :column\_name - Column to be compared
+  * :value       - Value to compare against
+  * :comparison  - Type of comparison to do.
+* options
+  * :key\_count    - Set maximum number of rows to return. (Only works if CassandraThrift::IndexClause is not passed in.)
+  * :key\_start    - Set starting row key for search. (Only works if CassandraThrift::IndexClause is not passed in.)
+  * :consistency
+
+Example:
+    @client.create_index('Twitter', 'Statuses', 'x', 'LongType')
+
+    @client.insert(:Statuses, 'row1', { 'x' => [0,10].pack("NN")  })
+
+    (2..10).to_a.each do |i|
+      @twitter.insert(:Statuses, 'row' + i.to_s, { 'x' => [0,20].pack("NN"), 'non_indexed' => [i].pack('N*') })
+    end
+
+    @client.insert(:Statuses, 'row11', { 'x' => [0,30].pack("NN")  })
+
+    expressions = [{:column_name => 'x', :value => [0,20].pack("NN"), :comparison => "=="}]
+
+    # verify multiples will be returned
+    @client.get_indexed_slices(:Statuses, expressions).length       # returns 9
+
+    # verify that GT and LT queries perform properly
+    expressions   =  [
+                      { :column_name => 'x',
+                        :value => [0,20].pack("NN"),  
+                        :comparison => "=="},
+                      { :column_name => 'non_indexed', 
+                        :value => [5].pack("N*"),
+                        :comparison => ">"}
+                    ]
+
+    @client.get_indexed_slices(:Statuses, expressions).length       # returns 5
+
+## Reporting Problems
+
+The Github issue tracker is [here](http://github.com/fauna/cassandra/issues). If you have problems with this library or Cassandra itself, please use the [cassandra-user mailing list](http://mail-archives.apache.org/mod_mbox/incubator-cassandra-user/).

data/Rakefile

@@ -10,19 +10,21 @@ unless ENV['FROM_BIN_CASSANDRA_HELPER']
     p.summary = "A Ruby client for the Cassandra distributed database."
     p.rubygems_version = ">= 0.8"
     p.dependencies = ['thrift_client >=0.6.0', 'json', 'rake', 'simple_uuid >=0.1.0']
-    p.ignore_pattern = /^(data|vendor\/cassandra|cassandra|vendor\/thrift)/
+    p.ignore_pattern = /^(data|vendor\/cassandra|cassandra|vendor\/thrift|.*\.rbc)/
     p.rdoc_pattern = /^(lib|bin|tasks|ext)|^README|^CHANGELOG|^TODO|^LICENSE|^COPYING$/
+    p.retain_gemspec = true
   end
 end
 
 CassandraBinaries = {
   '0.6' => 'http://www.apache.org/dist/cassandra/0.6.13/apache-cassandra-0.6.13-bin.tar.gz',
   '0.7' => 'http://www.apache.org/dist/cassandra/0.7.5/apache-cassandra-0.7.5-bin.tar.gz',
-  '0.8' => 'http://www.apache.org/dist/cassandra/0.8.0/apache-cassandra-0.8.0-beta1-bin.tar.gz'
+  '0.8' => 'http://www.apache.org/dist/cassandra/0.8.0/apache-cassandra-0.8.0-rc1-bin.tar.gz'
 }
 
 CASSANDRA_HOME = ENV['CASSANDRA_HOME'] || "#{ENV['HOME']}/cassandra"
 CASSANDRA_VERSION = ENV['CASSANDRA_VERSION'] || '0.7'
+CASSANDRA_PIDFILE = ENV['CASSANDRA_PIDFILE'] || "#{CASSANDRA_HOME}/cassandra.pid"
 
 def setup_cassandra_version(version = CASSANDRA_VERSION)
   FileUtils.mkdir_p CASSANDRA_HOME
@@ -57,14 +59,50 @@ def setup_environment
   env
 end
 
-desc "Start Cassandra"
-task :cassandra => :java do
-  setup_cassandra_version
+def running?(pid_file = nil)
+  pid_file ||= CASSANDRA_PIDFILE
 
-  env = setup_environment
+  if File.exists?(pid_file)
+    pid = File.new(pid_file).read.to_i
+    begin
+      Process.kill(0, pid)
+      return true
+    rescue
+      File.delete(pid_file)
+    end
+  end
 
-  Dir.chdir(File.join(CASSANDRA_HOME, "cassandra-#{CASSANDRA_VERSION}")) do
-    sh("env #{env} bin/cassandra -f")
+  false
+end
+
+namespace :cassandra do
+  desc "Start Cassandra"
+  task :start, :daemonize, :needs => :java do |t, args|
+    args.with_defaults(:daemonize => true)
+
+    setup_cassandra_version
+
+    env = setup_environment
+
+    Dir.chdir(File.join(CASSANDRA_HOME, "cassandra-#{CASSANDRA_VERSION}")) do
+      sh("env #{env} bin/cassandra #{'-f' unless args.daemonize} -p #{CASSANDRA_PIDFILE}")
+    end
+  end
+
+  desc "Stop Cassandra"
+  task :stop => :java do
+    setup_cassandra_version
+    env = setup_environment
+    sh("kill $(cat #{CASSANDRA_PIDFILE})")
+  end
+end
+
+desc "Start Cassandra"
+task :cassandra => :java do
+  begin
+    Rake::Task["cassandra:start"].invoke(false)
+  rescue RuntimeError => e
+    raise e unless e.message =~ /Command failed with status \(130\)/ # handle keyboard interupt errors
   end
 end
 
@@ -120,3 +158,9 @@ task :thrift do
     rm -rf gen-rb &&
     thrift -gen rb #{CASSANDRA_HOME}/interface/cassandra.thrift")
 end
+
+task :fix_perms do
+  chmod_R 0755, './'
+end
+
+task :pkg => [:fix_perms]