cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/metal/logger.rb

@@ -0,0 +1,71 @@
+module Cequel
+  module Metal
+    #
+    # The Logger class encapsulates logging functionality for {Keyspace}.
+    #
+    # @api private
+    #
+    class Logger
+      extend Forwardable
+      # @return [::Logger] An instance of Logger from the standard library
+      attr_reader :out
+      # @return [Integer] The severity level for this logger
+      attr_reader :severity
+      # @return [Integer] Only log queries that take longer than threshold ms
+      attr_accessor :threshold
+
+      #
+      # @param out [::Logger] An instance of Logger from the standard library
+      # @param severity [Integer] The severity level for this logger
+      # @param threshold [Integer] Only log queries that take longer than
+      #   `threshold` ms
+      #
+      def initialize(out, severity, threshold = 0)
+        @out, @severity, @threshold = out, severity, threshold
+      end
+
+      #
+      # Log a CQL statement
+      #
+      # @param label [String] a logical label for this statement
+      # @param timing [Integer] how long this statement took in ms
+      # @param statement [String] the CQL statement to log
+      # @param bind_vars [Array] bind variables for the CQL statement
+      # @return [void]
+      #
+      def log(label, timing, statement, bind_vars)
+        if timing >= threshold
+          out.add(severity) do
+            sprintf(
+              '%s (%dms) %s',
+              label, timing, sanitize(statement, bind_vars)
+            )
+          end
+        end
+      end
+
+      private
+
+      def_delegator 'CassandraCQL::Statement', :sanitize
+    end
+
+    #
+    # Logger for queries that resulted in an exception
+    #
+    class ExceptionLogger < Logger
+      #
+      # Log a CQL statement that resulted in an exception
+      #
+      # @param label [String] a logical label for this statement
+      # @param statement [String] the CQL statement to log
+      # @param bind_vars [Array] bind variables for the CQL statement
+      # @return [void]
+      #
+      def log(label, statement, bind_vars)
+        out.add(severity) do
+          sprintf('%s (ERROR) %s', label, sanitize(statement, bind_vars))
+        end
+      end
+    end
+  end
+end

data/lib/cequel/metal/logging.rb

@@ -0,0 +1,47 @@
+module Cequel
+  module Metal
+    #
+    # Methods to handle logging for {Keyspace} instances
+    #
+    module Logging
+      def logger=(logger)
+        loggers << Logger.new(logger, ::Logger::DEBUG)
+        self.exception_logger = ExceptionLogger.new(logger, ::Logger::ERROR)
+      end
+
+      def slowlog=(slowlog)
+        warn "#slowlog= is deprecated and will be removed from a future " \
+             "version"
+        loggers << @slowlog = Logger.new(slowlog, ::Logger::WARN, 2000)
+      end
+
+      def slowlog_threshold=(threshold)
+        @slowlog.threshold = threshold
+      end
+
+      protected
+
+      attr_accessor :exception_logger
+
+      private
+
+      def log(label, statement, *bind_vars)
+        response = nil
+        begin
+          time = Benchmark.ms { response = yield }
+          loggers.each do |logger|
+            logger.log(label, time, statement, bind_vars)
+          end
+        rescue Exception => e
+          exception_logger.log(label, statement, bind_vars) if exception_logger
+          raise
+        end
+        response
+      end
+
+      def loggers
+        @loggers ||= []
+      end
+    end
+  end
+end

data/lib/cequel/metal/new_relic_instrumentation.rb

@@ -0,0 +1,26 @@
+begin
+  require 'new_relic/agent/method_tracer'
+rescue LoadError => e
+  fail LoadError, "Can't use NewRelic instrumentation without NewRelic gem"
+end
+
+module Cequel
+  module Metal
+    #
+    # Provides NewRelic instrumentation for CQL queries.
+    #
+    module NewRelicInstrumentation
+      extend ActiveSupport::Concern
+
+      included do
+        include NewRelic::Agent::MethodTracer
+
+        add_method_tracer :execute,
+                          'Database/Cassandra/#{args[0][/^[A-Z ]*[A-Z]/]' \
+                          '.sub(/ FROM$/, \'\')}'
+      end
+    end
+  end
+end
+
+Cequel::Metal::Keyspace.module_eval { include NewRelicInstrumentation }

data/lib/cequel/metal/row.rb

@@ -1,13 +1,25 @@
 module Cequel
-
   module Metal
-
-    class Row < ActiveSupport::HashWithIndifferentAccess
-
+    #
+    # A result row from a CQL query. Acts as a hash of column names to values,
+    # but also exposes TTLs and writetimes
+    #
+    # @since 1.0.0
+    #
+    class Row < DelegateClass(ActiveSupport::HashWithIndifferentAccess)
+      #
+      # Encapsulate a row from CassandraCQL
+      #
+      # @param result_row [CassandraCQL::Row] row from underlying driver
+      # @return [Row] encapsulated row
+      #
+      # @api private
+      #
       def self.from_result_row(result_row)
         if result_row
           new.tap do |row|
-            result_row.column_names.zip(result_row.column_values) do |name, value|
+            names, values = result_row.column_names, result_row.column_values
+            names.zip(values) do |name, value|
               if name =~ /^(ttl|writetime)\((.+)\)$/
                 if $1 == 'ttl' then row.set_ttl($2, value)
                 else row.set_writetime($2, value)
@@ -19,30 +31,44 @@ module Cequel
         end
       end
 
-      def initialize(*_)
-        super
+      #
+      # @api private
+      #
+      def initialize
+        super(ActiveSupport::HashWithIndifferentAccess.new)
         @ttls = ActiveSupport::HashWithIndifferentAccess.new
         @writetimes = ActiveSupport::HashWithIndifferentAccess.new
       end
 
+      #
+      # Get the TTL (time-to-live) of a column
+      #
+      # @param column [Symbol] column name
+      # @return [Integer] TTL of column in seconds
+      #
       def ttl(column)
         @ttls[column]
       end
 
+      #
+      # Get the writetime of a column
+      #
+      # @param column [Symbol] column name
+      # @return [Integer] writetime of column in nanoseconds since epoch
+      #
       def writetime(column)
         @writetimes[column]
       end
 
+      # @private
       def set_ttl(column, value)
         @ttls[column] = value
       end
 
+      # @private
       def set_writetime(column, value)
         @writetimes[column] = value
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/row_specification.rb

@@ -1,22 +1,38 @@
 module Cequel
-
   module Metal
-
     #
-    # @private
+    # Encapsulates a row specification (`WHERE` clause) constructed from a
+    # column ane one or more values to match
+    #
+    # @api private
     #
     class RowSpecification
-
+      #
+      # Build one or more row specifications
+      #
+      # @param column_values [Hash] map of column name to value or values
+      # @return [Array<RowSpecification>] collection of row specifications
+      #
       def self.build(column_values)
         column_values.map { |column, value| new(column, value) }
       end
 
-      attr_reader :column, :value
+      # @return [Symbol] column name
+      attr_reader :column
+      # @return [Object, Array] value or values to match
+      attr_reader :value
 
+      #
+      # @param column [Symbol] column name
+      # @param value [Object,Array] value or values to match
+      #
       def initialize(column, value)
         @column, @value = column, value
       end
 
+      #
+      # @return [String] row specification as CQL fragment
+      #
       def cql
         case @value
         when Array
@@ -29,9 +45,6 @@ module Cequel
           ["#{@column} = ?", @value]
         end
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/statement.rb

@@ -1,35 +1,59 @@
 module Cequel
-
   module Metal
-
+    #
+    # Builder for CQL statements. Contains a CQL string with bind substitutions
+    # and a collection of bind variables
+    #
+    # @api private
+    #
     class Statement
-      attr_reader :bind_vars, :length
+      # @return [Array] bind variables for CQL string
+      attr_reader :bind_vars
 
       def initialize
         @cql, @bind_vars = [], []
       end
 
+      #
+      # @return [String] CQL statement
+      #
       def cql
         @cql.join
       end
 
+      #
+      # Add a CQL fragment with optional bind variables to the beginning of
+      # the statement
+      #
+      # @param (see #append)
+      # @return [void]
+      #
       def prepend(cql, *bind_vars)
         @cql.unshift(cql)
         @bind_vars.unshift(*bind_vars)
       end
 
+      #
+      # Add a CQL fragment with optional bind variables to the end of the
+      # statement
+      #
+      # @param cql [String] CQL fragment
+      # @param bind_vars [Object] zero or more bind variables
+      # @return [void]
+      #
       def append(cql, *bind_vars)
         @cql << cql
         @bind_vars.concat(bind_vars)
         self
       end
 
+      #
+      # @return [Array] this statement as an array of arguments to
+      #   Keyspace#execute (CQL string followed by bind variables)
+      #
       def args
         [cql, *bind_vars]
       end
-
     end
-
   end
-
 end

data/lib/cequel/metal/updater.rb

@@ -1,9 +1,25 @@
 module Cequel
-
   module Metal
-
+    #
+    # Builder for `UPDATE` statement containing heterogeneous operations (set
+    # columns, atomically mutate collections)
+    #
+    # @see DataSet#update
+    # @see Deleter
+    # @see
+    #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_reference/update_r.html
+    #   CQL UPDATE documentation
+    # @since 1.0.0
+    #
     class Updater < Writer
-
+      #
+      # Directly set column values
+      #
+      # @param data [Hash] map of column names to values
+      # @return [void]
+      #
+      # @see DataSet#update
+      #
       def set(data)
         data.each_pair do |column, value|
           prepare_upsert_value(value) do |binding, *values|
@@ -13,36 +29,100 @@ module Cequel
         end
       end
 
+      #
+      # Prepend elements to a list column
+      #
+      # @param column [Symbol] column name
+      # @param elements [Array<Object>] elements to prepend
+      # @return [void]
+      #
+      # @see DataSet#list_prepend
+      #
       def list_prepend(column, elements)
         statements << "#{column} = [?] + #{column}"
         bind_vars << elements
       end
 
+      #
+      # Append elements to a list column
+      #
+      # @param column [Symbol] column name
+      # @param elements [Array] elements to append
+      # @return [void]
+      #
+      # @see DataSet#list_append
+      #
       def list_append(column, elements)
         statements << "#{column} = #{column} + [?]"
         bind_vars << elements
       end
 
+      #
+      # Remove all occurrences of an element from a list
+      #
+      # @param column [Symbol] column name
+      # @param value value to remove
+      # @return [void]
+      #
+      # @see DataSet#list_remove
+      #
       def list_remove(column, value)
         statements << "#{column} = #{column} - [?]"
         bind_vars << value
       end
 
+      #
+      # Replace a list item at a given position
+      #
+      # @param column [Symbol] column name
+      # @param index [Integer] index at which to replace value
+      # @param value new value for position
+      # @return [void]
+      #
+      # @see DataSet#list_replace
+      #
       def list_replace(column, index, value)
         statements << "#{column}[#{index}] = ?"
         bind_vars << value
       end
 
+      #
+      # Add elements to a set
+      #
+      # @param column [Symbol] column name
+      # @param values [Set] elements to add to set
+      # @return [void]
+      #
+      # @see DataSet#set_add
+      #
       def set_add(column, values)
         statements << "#{column} = #{column} + {?}"
         bind_vars << values
       end
 
-      def set_remove(column, value)
+      #
+      # Remove elements from a set
+      #
+      # @param column [Symbol] column name
+      # @param values [Set] elements to remove from set
+      # @return [void]
+      #
+      # @see DataSet#set_remove
+      #
+      def set_remove(column, values)
         statements << "#{column} = #{column} - {?}"
-        bind_vars << ::Kernel.Array(value)
+        bind_vars << ::Kernel.Array(values)
       end
 
+      #
+      # Add or update elements in a map
+      #
+      # @param column [Symbol] column name
+      # @param updates [Hash] map of keys to values to update in map
+      # @return [void]
+      #
+      # @see DataSet#map_update
+      #
       def map_update(column, updates)
         binding_pairs = ::Array.new(updates.length) { '?:?' }.join(',')
         statements << "#{column} = #{column} + {#{binding_pairs}}"
@@ -52,14 +132,11 @@ module Cequel
       private
 
       def write_to_statement(statement)
-        statement.append("UPDATE #{table_name}").
-          append(generate_upsert_options).
-          append(" SET ").
-          append(statements.join(', '), *bind_vars)
+        statement.append("UPDATE #{table_name}")
+          .append(generate_upsert_options)
+          .append(" SET ")
+          .append(statements.join(', '), *bind_vars)
       end
-
     end
-
   end
-
 end