datastax_rails 1.0.6 → 1.0.8

data/README.rdoc

@@ -67,5 +67,10 @@ attributes on any model.  DSR will only upload schema files if they have changed
 
 === Known issues
 
-Calling :find on a model with a bogus ID returns an empty model instead of RecordNotFound.  This is due to a bug
-in DSE that is supposedly fixed in the upcoming 2.2 release.
+Calling +find+ on a model with a bogus ID returns an empty model instead of RecordNotFound.  This is due to a bug
+in DSE that is supposedly fixed in the upcoming 2.2 release.
+
+=== More information
+
+The documentation for DatastaxRails::Base and DatastaxRails::SearchMethods will give you quite a few examples
+of things you can do.  You can find a copy of the latest documentation on line at http://rdoc.info/github/jasonmk/datastax_rails/master/frames.

data/Rakefile

@@ -16,6 +16,7 @@ RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title    = 'DatastaxRails'
   rdoc.options << '--line-numbers'
+  rdoc.options << '--main=README.rdoc'
   rdoc.rdoc_files.include('README.rdoc')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/config/schema.xml.erb

@@ -67,4 +67,5 @@
 <% @copy_fields.each do |field| %>
   <copyField source="<%= field[:source] %>" dest="<%= field[:dest]%>"/>
 <% end %>
+
 </schema>

data/lib/datastax_rails/base.rb

@@ -133,6 +133,32 @@ module DatastaxRails #:nodoc:
   #   user.name = "David"
   #   user.occupation = "Code Artist"
   #
+  # == Consistency
+  #
+  # Cassandra has a concept of consistency levels when it comes to saving records.  For a
+  # detailed discussion on Cassandra data consistency, see:
+  # http://www.datastax.com/docs/1.0/dml/data_consistency
+  #
+  # DatastaxRails allows you to specify the consistency when you save and retrieve objects.
+  #
+  #   user = User.new(:name => 'David')
+  #   user.save(:consistency => 'ALL')
+  #
+  #   User.create(params[:user], {:consistency => :local_quorum})
+  #
+  #   User.consistency(:local_quorum).where(:name => 'David')
+  #
+  # The default consistency level in DatastaxRails is QUORUM for writes and for retrieval
+  # by ID.  SOLR only supports a consistency level of ONE.  See the documentation for
+  # SearchMethods#consistency for a more detailed explanation.
+  #
+  # The overall default consistency for a given model can be overridden by adding a method
+  # to the model like so:
+  #
+  #   def default_consistency
+  #     :local_quorum
+  #   end
+  #
   # == Conditions
   #
   # Conditions are specified as a hash representing key/value pairs that will eventually be passed to SOLR or as
@@ -265,7 +291,6 @@ module DatastaxRails #:nodoc:
     include ActiveModel::MassAssignmentSecurity
     
     include Connection
-    include Consistency
     include Identity
     include FinderMethods
     include Batches
@@ -281,7 +306,6 @@ module DatastaxRails #:nodoc:
     include Timestamps
     include Serialization
     include Migrations
-    # include Mocking
     
     # Stores the default scope for the class
     class_attribute :default_scopes, :instance_writer => false
@@ -403,6 +427,10 @@ module DatastaxRails #:nodoc:
       self.class.attribute_names
     end
     
+    def valid_consistency?(level) #:nodoc:
+      self.class.validate_consistency(level.to_s.upcase)
+    end
+    
     private
       def populate_with_current_scope_attributes
         return unless self.class.scope_attributes?
@@ -486,6 +514,10 @@ module DatastaxRails #:nodoc:
         search.raw_results.map { |result| result.primary_key }
       end
       
+      def valid_consistency?(level) #:nodoc:
+        DatastaxRails::Cql::Consistency::VALID_CONSISTENCY_LEVELS.include?(level)
+      end
+      
       protected
       
         

data/lib/datastax_rails/callbacks.rb

@@ -17,7 +17,7 @@ module DatastaxRails
       define_model_callbacks :save, :create, :update, :destroy
     end
 
-    def destroy #:nodoc:
+    def destroy(*) #:nodoc:
       _run_destroy_callbacks { super }
     end
 

data/lib/datastax_rails/cql/base.rb

@@ -1,10 +1,19 @@
 module DatastaxRails
   module Cql
     class Base
-      def to_cql #:nodoc:
-        nil
+      # Base initialize that sets the default consistency.
+      def initialize(klass, *args)
+        @consistency = klass.respond_to?(:default_consistency) ? klass.default_consistency.to_s.upcase : DatastaxRails::Cql::Consistency::QUORUM
+      end
+
+      # Abstract.  Should be overridden by subclasses
+      def to_cql
+        raise NotImplementedError
       end
       
+      # Generates the CQL and calls Cassandra to execute it.
+      # If you are using this outside of Rails, then DatastaxRails::Base.connection must have
+      # already been set up (Rails does this for you).
       def execute
         cql = self.to_cql
         Rails.logger.debug(cql)

data/lib/datastax_rails/cql/consistency.rb

@@ -1,13 +1,14 @@
 module DatastaxRails
   module Cql
     module Consistency
+      ANY = 'ANY'
       ONE = 'ONE'
       QUORUM = 'QUORUM'
       LOCAL_QUORUM = 'LOCAL_QUORUM'
       EACH_QUORUM = 'EACH_QUORUM'
       ALL = 'ALL'
       
-      VALID_CONSISTENCY_LEVELS = [ONE, QUORUM, LOCAL_QUORUM, EACH_QUORUM, ALL]
+      VALID_CONSISTENCY_LEVELS = [ANY, ONE, QUORUM, LOCAL_QUORUM, EACH_QUORUM, ALL]
     end
   end
 end

data/lib/datastax_rails/cql/delete.rb

@@ -4,9 +4,9 @@ module DatastaxRails
       def initialize(klass, keys)
         @klass = klass
         @keys = keys
-        @consistency = DatastaxRails::Cql::Consistency::QUORUM
         @timestamp = nil
         @columns = []
+        super
       end
       
       def using(consistency)

data/lib/datastax_rails/cql/insert.rb

@@ -3,10 +3,10 @@ module DatastaxRails
     class Insert < Base
       def initialize(klass)
         @klass = klass
-        @consistency = DatastaxRails::Cql::Consistency::QUORUM
         @ttl = nil
         @timestamp = nil
         @columns = {}
+        super
       end
       
       def using(consistency)

data/lib/datastax_rails/cql/select.rb

@@ -4,9 +4,9 @@ module DatastaxRails#:nodoc:
       def initialize(klass, select)
         @klass = klass
         @select = select.join(",")
-        @consistency = DatastaxRails::Cql::Consistency::QUORUM
         @limit = nil
         @conditions = {}
+        super
       end
       
       def using(consistency)

data/lib/datastax_rails/cql/truncate.rb

@@ -3,6 +3,7 @@ module DatastaxRails
     class Truncate < Base
       def initialize(klass)
         @klass = klass
+        super
       end
       
       def to_cql

data/lib/datastax_rails/cql/update.rb

@@ -4,8 +4,8 @@ module DatastaxRails
       def initialize(klass, key)
         @klass = klass
         @key = key
-        @consistency = DatastaxRails::Cql::Consistency::QUORUM
         @columns = {}
+        super
       end
       
       def using(consistency)
@@ -34,6 +34,7 @@ module DatastaxRails
       end
       
       def to_cql
+        columns = @columns.dup
         values = []
         
         stmt = "update #{@klass.column_family} using consistency #{@consistency} "
@@ -46,19 +47,21 @@ module DatastaxRails
           stmt << "AND TIMESTAMP #{@timestamp}"
         end
         
-        stmt << "SET "
-        
-        first_entry = @columns.shift
-        
-        stmt << "#{first_entry.first.to_s} = ? "
-        values << first_entry.last
-        
-        @columns.each do |k,v|
-          stmt << ", #{k.to_s} = ? "
-          values << v
+        unless columns.empty?
+          stmt << "SET "
+          
+          first_entry = columns.shift
+          
+          stmt << "#{first_entry.first.to_s} = ?"
+          values << first_entry.last
+          
+          columns.each do |k,v|
+            stmt << ", #{k.to_s} = ?"
+            values << v
+          end
         end
         
-        stmt << "WHERE KEY IN (?)"
+        stmt << " WHERE KEY IN (?)"
         values << @key
         
         CassandraCQL::Statement.sanitize(stmt, values)

data/lib/datastax_rails/errors.rb

@@ -1,16 +1,16 @@
 module DatastaxRails
-  class DatastaxRailsError < StandardError
+  class DatastaxRailsError < StandardError #:nodoc:
   end
   
-  class AssociationTypeMismatch < DatastaxRailsError
+  class AssociationTypeMismatch < DatastaxRailsError #:nodoc:
   end
   
-  class RecordNotSaved < DatastaxRailsError
+  class RecordNotSaved < DatastaxRailsError #:nodoc:
   end
   
-  class DeleteRestrictionError < DatastaxRailsError
+  class DeleteRestrictionError < DatastaxRailsError #:nodoc:
   end
   
-  class RecordNotFound < DatastaxRailsError
+  class RecordNotFound < DatastaxRailsError #:nodoc:
   end
 end

data/lib/datastax_rails/persistence.rb

@@ -9,8 +9,21 @@ module DatastaxRails
     module ClassMethods
       # Removes one or more records with corresponding keys
       def remove(*keys)
+        options = {}
+        if keys.last.is_a?(Hash)
+          options = keys.pop
+        end
         ActiveSupport::Notifications.instrument("remove.datastax_rails", :column_family => column_family, :key => key) do
-          cql.delete(keys).using(thrift_write_consistency).execute
+          c = cql.delete(keys)
+          if(options[:consistency])
+            level = options[:consistency].to_s.upcase
+            if(valid_consistency?(level))
+              c.using(level)
+            else
+              raise ArgumentError, "'#{level}' is not a valid Cassandra consistency level"
+            end
+          end
+          c.execute
         end
       end
 
@@ -28,11 +41,20 @@ module DatastaxRails
         end
       end
       
-      def write(key, attributes, schema_version)
+      def write(key, attributes, options = {})
         key.tap do |key|
-          attributes = encode_attributes(attributes, schema_version)
+          attributes = encode_attributes(attributes, options[:schema_version])
           ActiveSupport::Notifications.instrument("insert.datastax_rails", :column_family => column_family, :key => key, :attributes => attributes) do
-            cql.update(key.to_s).columns(attributes).using(thrift_write_consistency).execute
+            c = cql.update(key.to_s).columns(attributes)
+            if(options[:consistency])
+              level = options[:consistency].to_s.upcase
+              if(valid_consistency?(level))
+                c.using(options[:consistency])
+              else
+                raise ArgumentError, "'#{level}' is not a valid Cassandra consistency level"
+              end
+            end
+            c.execute
           end
         end
       end
@@ -89,8 +111,8 @@ module DatastaxRails
       create_or_update(options) || raise(RecordNotSaved)
     end
 
-    def destroy
-      self.class.remove(key)
+    def destroy(options = {})
+      self.class.remove(key, options)
       @destroyed = true
       freeze
     end
@@ -134,7 +156,7 @@ module DatastaxRails
       
       def write(options) #:nodoc:
         changed_attributes = changed.inject({}) { |h, n| h[n] = read_attribute(n); h }
-        self.class.write(key, changed_attributes, schema_version)
+        self.class.write(key, changed_attributes, options.merge(:schema_version => schema_version))
       end
   end
 end

data/lib/datastax_rails/reflection.rb

@@ -1,8 +1,8 @@
 require 'active_support/core_ext/class/attribute'
 require 'active_support/core_ext/object/inclusion'
 
-# This is shamelessly ripped from Active Record 3.1
 module DatastaxRails
+  # This is shamelessly ripped from Active Record 3.1
   # = DatastaxRails Reflection
   module Reflection # :nodoc:
     extend ActiveSupport::Concern

data/lib/datastax_rails/relation/search_methods.rb

@@ -1,6 +1,31 @@
 module DatastaxRails
   module SearchMethods
     
+    # The default consistency level for DSR is QUORUM when searching by ID.
+    # For all searches using SOLR, the default consistency is ONE.  Use this
+    # to override it in either case.
+    # 
+    #   Model.consistency(:local_quorum).find("12345")
+    #
+    # Note that Solr searches (basically anything but find by id) don't allow you
+    # to specify the consistency level.  DSR sort of gets around this by taking the
+    # search results and then going to Cassandra to retrieve the objects by ID using
+    # the consistency you specified.  However, it is possible that you might not get
+    # all of the records you are expecting if the SOLR node you were talking to hasn't
+    # been updated yet with the results.  In practice, this should not happen for
+    # records that were created over your connection, but it is possible for other
+    # connections to create records that you can't see yet.
+    def consistency(level)
+      level = level.to_s.upcase
+      unless self.valid_consistency?(level)
+        raise ArgumentError, "'#{level}' is not a valid Cassandra consistency level"
+      end
+      
+      clone.tap do |r|
+        r.consistency_value = level
+      end
+    end 
+    
     # Normally special characters (other than wild cards) are escaped before the search
     # is submitted.  If you want to handle escaping yourself because you need to use
     # those special characters, then just include this in your chain.

data/lib/datastax_rails/relation.rb

@@ -36,7 +36,6 @@ module DatastaxRails
       @per_page_value = @klass.default_page_size
       @page_value = 1
       @use_solr_value = true
-      @consistency_value = "QUORUM"
       @extensions = []
       @create_with_value = {}
       @escape_value = true
@@ -241,6 +240,9 @@ module DatastaxRails
       limit(1).select(:id).to_a.total_entries
     end
     
+    # Escapes values that might otherwise mess up the URL or confuse SOLR.
+    # If you want to handle escaping yourself for a particular query then
+    # SearchMethods#dont_escape is what you're looking for.
     def solr_escape(str)
       if str.is_a?(String) && escape_value
         str.gsub(SOLR_CHAR_RX, '\\\\\1')
@@ -317,9 +319,17 @@ module DatastaxRails
       response = rsolr.paginate(@page_value, @per_page_value, 'select', :params => params)["response"]
       results = DatastaxRails::Collection.new
       results.total_entries = response['numFound'].to_i
-      response['docs'].each do |doc|
-        key = doc.delete('id')
-        results << @klass.instantiate(key,doc)
+      if @consistency_value
+        response['docs'].each do |doc|
+          id = doc['id']
+          obj = @klass.with_cassandra.consistency(@consistency_value).find_by_id(id)
+          results << obj if obj
+        end
+      else
+        response['docs'].each do |doc|
+          key = doc.delete('id')
+          results << @klass.instantiate(key,doc)
+        end
       end
       results
     end

data/lib/datastax_rails/version.rb

@@ -1,3 +1,4 @@
 module DatastaxRails
-  VERSION = "1.0.6"
+  # The current version of the gem
+  VERSION = "1.0.8"
 end

data/lib/datastax_rails.rb

@@ -1,6 +1,7 @@
 require 'active_support/all'
 require 'cassandra-cql/1.0'
 
+# Welcome to DatastaxRails.  DatastaxRails::Base is probably a good place to start.
 module DatastaxRails
   extend ActiveSupport::Autoload
   
@@ -11,12 +12,10 @@ module DatastaxRails
   autoload :Callbacks
   autoload :Collection
   autoload :Connection
-  autoload :Consistency
   autoload :Cql
   autoload :Cursor
   autoload :Identity
   autoload :Migrations
-  #autoload :Mocking
   autoload :Persistence
   autoload :Reflection
   autoload :Relation
@@ -69,8 +68,9 @@ module DatastaxRails
   end
 end
 
-# Fixup the thrift library
 require "thrift"
+# Thrift is how we communicate with Cassandra.  We need to do a little fixup
+# work to handle UTF-8 properly in Ruby 1.8.6.
 module Thrift
   class BinaryProtocol
     def write_string(str)
@@ -82,6 +82,5 @@ end
 
 require 'datastax_rails/railtie' if defined?(Rails)
 require 'datastax_rails/errors'
-# require 'solr_no_escape'
 
 ActiveSupport.run_load_hooks(:datastax_rails, DatastaxRails::Base)

data/spec/datastax_rails/base_spec.rb

@@ -12,4 +12,10 @@ describe DatastaxRails::Base do
     p.save!
     p.instance_variable_get(:@after_save_ran).should == "yup"
   end
+  
+  it "should raise RecordNotFound when finding a bogus ID" do
+    pending "Datastax Enterprise 2.2 should fix this" do
+      lambda { Person.find("xyzzy") }.should raise_exception(DatastaxRails::RecordNotFound)
+    end
+  end
 end

data/spec/datastax_rails/cql/select_spec.rb

@@ -4,9 +4,12 @@ describe DatastaxRails::Cql::Select do
   before(:each) do
     @model_class = mock("Model Class", :column_family => 'users')
   end
+  
   it "should generate valid CQL" do
     cql = DatastaxRails::Cql::Select.new(@model_class, ["*"])
     cql.using(DatastaxRails::Cql::Consistency::QUORUM).conditions(:key => '12345').limit(1)
     cql.to_cql.should == "SELECT * FROM users USING CONSISTENCY QUORUM WHERE key = '12345' LIMIT 1"
   end
+  
+  it_has_behavior "default_consistency"
 end

data/spec/datastax_rails/cql/update_spec.rb

@@ -0,0 +1,15 @@
+require 'spec_helper'
+
+describe DatastaxRails::Cql::Update do
+  before(:each) do
+    @model_class = mock("Model Class", :column_family => 'users')
+  end
+  
+  it "should generate valid CQL" do
+    cql = DatastaxRails::Cql::Update.new(@model_class, "12345")
+    cql.using(DatastaxRails::Cql::Consistency::QUORUM).columns(:name => 'John', :age => '23')
+    cql.to_cql.should == "update users using consistency QUORUM SET age = '23', name = 'John' WHERE KEY IN ('12345')"
+  end
+  
+  it_has_behavior "default_consistency"
+end

data/spec/datastax_rails/persistence_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+
+describe "DatastaxRails::Base" do
+  describe "persistence" do
+    describe "#create" do
+      it "should persist at the given consistency level" do
+        DatastaxRails::Base.connection.stub(:execute_cql_query)
+        DatastaxRails::Base.connection.should_receive(:execute_cql_query).with(/USING CONSISTENCY LOCAL_QUORUM/i).and_return(true)
+        Person.create({:name => 'Steven'},{:consistency => 'LOCAL_QUORUM'})
+      end
+    end
+    
+    describe "#save" do
+      it "should persist at the given consistency level" do
+        DatastaxRails::Base.connection.stub(:execute_cql_query)
+        DatastaxRails::Base.connection.should_receive(:execute_cql_query).with(/USING CONSISTENCY LOCAL_QUORUM/i).and_return(true)
+        p=Person.new(:name => 'Steven')
+        p.save(:consistency => 'LOCAL_QUORUM')
+      end
+    end
+    
+    describe "#remove" do
+      it "should remove at the given consistency level" do
+        p=Person.create(:name => 'Steven')
+        DatastaxRails::Base.connection.stub(:execute_cql_query)
+        DatastaxRails::Base.connection.should_receive(:execute_cql_query).with(/USING CONSISTENCY LOCAL_QUORUM/i).and_return(true)
+        p.destroy(:consistency => :local_quorum)
+      end
+    end
+  end
+end

data/spec/datastax_rails/relation/search_methods_spec.rb

@@ -5,6 +5,24 @@ describe DatastaxRails::Relation do
     @relation = DatastaxRails::Relation.new(Hobby, "hobbies")
   end
   
+  describe "#consistency" do
+    it "should throw an ArgumentError for invalid consistency levels" do
+      lambda { @relation.consistency(:foo) }.should raise_exception(ArgumentError)
+    end
+    
+    it "should not raise an exception for a valid consistency level" do
+      lambda { @relation.consistency(:local_quorum) }.should_not raise_exception
+    end
+    
+    it "should call cassandra to enforce consistency" do
+      h=Hobby.create(:name => 'swimming')
+      Hobby.commit_solr
+      Hobby.stub_chain(:with_cassandra,:consistency).and_return(@relation)
+      @relation.should_receive(:find_by_id).with(h.id)
+      @relation.consistency(:all).where(:name => 'swimming').all
+    end
+  end
+  
   describe "#limit" do
     it "should limit the page size" do
       "a".upto("l") do |letter|