cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/record/schema.rb

@@ -1,33 +1,96 @@
 module Cequel
-
   module Record
-
+    #
+    # `Cequel::Record` implementations define their own schema in their class
+    # definitions. As well as defining attributes on record instances, the
+    # column definitions in {Properties} allow a `Cequel::Record` to have a
+    # precise internal represntation of its representation as a CQL3 table
+    # schema. Further, it is able to check this representation against the
+    # actual table defined in Cassandra (if any), and create or modify the
+    # schema in Cassandra to match what's defined in code.
+    #
+    # All the interesting stuff is in the {ClassMethods}.
+    #
+    # @since 1.0.0
+    #
     module Schema
-
       extend ActiveSupport::Concern
       extend Forwardable
 
       included do
-        class_attribute :table_name, :instance_writer => false
+        class_attribute :table_name, instance_writer: false
         self.table_name = name.tableize.to_sym unless name.nil?
       end
 
+      #
+      # Methods available on {Record} class singletons to introspect and modify
+      # the schema defined in the database
+      #
       module ClassMethods
+        #
+        # @!attr table_name
+        #   @return [Symbol] name of the CQL table that backs this record class
+        #
+
         extend Forwardable
 
-        def_delegators :table_schema, :columns, :key_columns, :key_column_names,
-          :partition_key_columns, :clustering_columns, :compact_storage?
+        #
+        # @!attribute [r] columns
+        #   (see Cequel::Schema::Table#columns)
+        #
+        # @!attribute [r] key_columns
+        #   (see Cequel::Schema::Table#key_columns)
+        #
+        # @!attribute [r] key_column_names
+        #   (see Cequel::Schema::Table#key_column_names)
+        #
+        # @!attribute [r] partition_key_columns
+        #   (see Cequel::Schema::Table#partition_key_columns)
+        #
+        # @!attribute [r] clustering_columns
+        #   (see Cequel::Schema::Table#clustering_columns)
+        #
+        # @!method compact_storage?
+        #   (see Cequel::Schema::Table#compact_storage?)
+        #
+        def_delegators :table_schema, :columns, :key_columns,
+                       :key_column_names, :partition_key_columns,
+                       :clustering_columns, :compact_storage?
+        #
+        # @!method reflect_on_column(name)
+        #   (see Cequel::Schema::Table#column)
+        #
         def_delegator :table_schema, :column, :reflect_on_column
 
+        #
+        # Read the current schema assigned to this record's table from
+        # Cassandra, and make any necessary modifications (including creating
+        # the table for the first time) so that it matches the schema defined
+        # in the record definition
+        #
+        # @raise (see Schema::TableSynchronizer.apply)
+        # @return [void]
+        #
         def synchronize_schema
-          Cequel::Schema::TableSynchronizer.
-            apply(connection, read_schema, table_schema)
+          Cequel::Schema::TableSynchronizer
+            .apply(connection, read_schema, table_schema)
         end
 
+        #
+        # Read the current state of this record's table in Cassandra from the
+        # database.
+        #
+        # @return [Schema::Table] the current schema assigned to this record's
+        #   table in the database
+        #
         def read_schema
           connection.schema.read_table(table_name)
         end
 
+        #
+        # @return [Schema::Table] the schema as defined by the columns
+        #   specified in the class definition
+        #
         def table_schema
           @table_schema ||= Cequel::Schema::Table.new(table_name)
         end
@@ -36,7 +99,11 @@ module Cequel
 
         def key(name, type, options = {})
           super
-          table_schema.add_key(name, type)
+          if options[:partition]
+            table_schema.add_partition_key(name, type)
+          else
+            table_schema.add_key(name, type)
+          end
         end
 
         def column(name, type, options = {})
@@ -66,15 +133,12 @@ module Cequel
         def compact_storage
           table_schema.compact_storage = true
         end
-
       end
 
       protected
+
       def_delegator 'self.class', :table_schema
       protected :table_schema
-
     end
-
   end
-
 end

data/lib/cequel/record/scoped.rb

@@ -1,24 +1,31 @@
 module Cequel
-
   module Record
-
+    #
+    # All of the instance methods of {RecordSet} are also available as class
+    # methods on {Record} implementations.
+    #
+    # @since 0.1.0
+    #
     module Scoped
-
       extend ActiveSupport::Concern
 
+      #
+      # Scoping-related methods for {Record} classes
+      #
       module ClassMethods
-
         extend Forwardable
 
         def_delegators :current_scope,
-          *(RecordSet.public_instance_methods(false) +
-            BulkWrites.public_instance_methods -
-            Object.instance_methods)
+                       *(RecordSet.public_instance_methods(false) +
+                         BulkWrites.public_instance_methods -
+                         Object.instance_methods)
 
+        # @private
         def current_scope
           delegating_scope || RecordSet.new(self)
         end
 
+        # @private
         def with_scope(record_set)
           previous_scope = delegating_scope
           self.delegating_scope = record_set
@@ -40,16 +47,14 @@ module Cequel
         def delegating_scope_key
           @delegating_scope_key ||= :"#{name}::delegating_scope"
         end
-
       end
 
+      private
+
       def initialize_new_record(*)
         super
         @attributes.merge!(self.class.current_scope.scoped_key_attributes)
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/secondary_indexes.rb

@@ -1,9 +1,48 @@
 module Cequel
-
   module Record
-
+    #
+    # Data columns may be given secondary indexes. This allows you to query the
+    # table for records where the indexed column contains a single value.
+    # Secondary indexes are not nearly as flexible as primary keys: you cannot
+    # query for multiple values or for ranges of values. You also cannot
+    # combine a secondary index restriction with a primary key restriction in
+    # the same query, nor can you combine more than one secondary index
+    # restrictions in the same query.
+    #
+    # If a column is given a secondary index, magic finder methods `find_by_*`,
+    # `find_all_by_*`, and `with_*` are added to the class singleton. See below
+    # for an example.
+    #
+    # Secondary indexes are fairly expensive for Cassandra and should only be
+    # defined where needed.
+    #
+    # @example Defining a secondary index
+    #   class Post
+    #     belongs_to :blog
+    #     key :id, :timeuuid, auto: true
+    #     column :title, :text
+    #     column :body, :text
+    #     column :author_id, :uuid, index: true # this column has a secondary
+    #                                           # index
+    #   end
+    #
+    # @example Using a secondary index
+    #   # return the first record with the author_id
+    #   Post.find_by_author_id(id)
+    #
+    #   # return an Array of all records with the author_id
+    #   Post.find_all_by_author_id(id)
+    #
+    #   # return a RecordSet scoped to the author_id
+    #   Post.with_author_id(id)
+    #
+    #   # same as with_author_id
+    #   Post.where(:author_id, id)
+    #
+    # @since 1.0.0
+    #
     module SecondaryIndexes
-
+      # @private
       def column(name, type, options = {})
         super
         name = name.to_sym
@@ -23,9 +62,6 @@ module Cequel
           RUBY
         end
       end
-
     end
-
   end
-
 end

data/lib/cequel/record/tasks.rb

@@ -13,7 +13,8 @@ namespace :cequel do
     end
   end
 
-  desc "Synchronize all models defined in `app/models' with Cassandra database schema"
+  desc "Synchronize all models defined in `app/models' with Cassandra " \
+       "database schema"
   task :migrate => :environment do
     watch_stack = ActiveSupport::Dependencies::WatchStack.new
 

data/lib/cequel/record/validations.rb

@@ -1,9 +1,25 @@
 module Cequel
-
   module Record
-
+    #
+    # {Record} classes can define validations that are run before saving a
+    # record instance.
+    #
+    # @example Validations
+    #   class User
+    #     include Cequel::Record
+    #
+    #     key :login, :text
+    #     column :email, :text
+    #
+    #     validates :email, presence: true, format: RFC822::EMAIL
+    #   end
+    #
+    # @see http://api.rubyonrails.org/classes/ActiveModel/Validations.html
+    #   ActiveModel::Validations
+    #
+    # @since 0.1.0
+    #
     module Validations
-
       extend ActiveSupport::Concern
 
       included do
@@ -12,39 +28,63 @@ module Cequel
         alias_method_chain :valid?, :callbacks
       end
 
+      #
+      # Validation-related methods exposed on Record class singletons
+      #
       module ClassMethods
-
+        #
+        # Attempt to create a new record, or raise an exception otherwise
+        #
+        # @param (see Persistence::ClassMethods#create)
+        # @yieldparam (see Persistence::ClassMethods#create)
+        # @return (see Persistence::ClassMethods#create)
+        # @raise (see Validations#save!)
+        #
         def create!(attributes = {}, &block)
           new(attributes, &block).save!
         end
-
       end
 
+      # @private
       def save(options = {})
         validate = options.fetch(:validate, true)
         options.delete(:validate)
         (!validate || valid?) && super
       end
 
-      def save!(options = {})
+      #
+      # Attempt to save the record, or raise an exception if there is a
+      # validation error
+      #
+      # @param (see Persistence#save)
+      # @return [Record] self
+      # @raise [RecordInvalid] if there are validation errors
+      #
+      def save!(attributes = {})
         tap do
-          unless save(options)
-            raise RecordInvalid, errors.full_messages.join("; ")
+          unless save(attributes)
+            fail RecordInvalid, errors.full_messages.join("; ")
           end
         end
       end
 
+      #
+      # Set the given attributes and attempt to save, raising an exception if
+      # there is a validation error
+      #
+      # @param (see Persistence#update_attributes)
+      # @return (see #save!)
+      # @raise (see #save!)
       def update_attributes!(attributes)
         self.attributes = attributes
         save!
       end
 
+      private
+
       def valid_with_callbacks?
         run_callbacks(:validation) { valid_without_callbacks? }
       end
-
     end
-
   end
-
 end

data/lib/cequel/schema.rb

@@ -1,6 +1,7 @@
 require 'cequel/schema/column'
 require 'cequel/schema/create_table_dsl'
 require 'cequel/schema/keyspace'
+require 'cequel/schema/migration_validator'
 require 'cequel/schema/table'
 require 'cequel/schema/table_property'
 require 'cequel/schema/table_reader'
@@ -10,6 +11,14 @@ require 'cequel/schema/table_writer'
 require 'cequel/schema/update_table_dsl'
 
 module Cequel
+  #
+  # The Schema module provides full read/write access to keyspace and table
+  # schemas defined in Cassandra.
+  #
+  # @see Schema::Keyspace
+  #
+  # @since 1.0.0
+  #
   module Schema
   end
 end

data/lib/cequel/schema/column.rb

@@ -1,155 +1,294 @@
 module Cequel
-
   module Schema
-
+    #
+    # Represents a column definition in a table schema.
+    #
+    # @abstract
+    #
     class Column
-
-      attr_reader :name, :type
-
+      # @return [Symbol] the name of the column
+      attr_reader :name
+      # @return [Type] the type of the column
+      attr_reader :type
+
+      #
+      # @param name [Symbol] the name of the column
+      # @param type [Type] the type of the column
+      #
       def initialize(name, type)
         @name, @type = name, type
       end
 
+      #
+      # @return [Boolean] true if this is a key column
+      #
+      # @see
+      #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/ddl/../../cassandra/glossary/gloss_glossary.html
+      #   The CQL3 glossary
+      #
       def key?
         partition_key? || clustering_column?
       end
 
+      #
+      # @return [Boolean] true if this is a partition key column
+      #
+      # @see
+      #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/ddl/../../cassandra/glossary/gloss_glossary.html
+      #   The CQL3 glossary
+      #
       def partition_key?
         false
       end
 
-      def type?(type_in)
-        type.is_a?(type_in)
-      end
-
+      #
+      # @return [Boolean] true if this is a clustering column
+      #
+      # @see
+      #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/ddl/../../cassandra/glossary/gloss_glossary.html
+      #   The CQL3 glossary
+      #
       def clustering_column?
         false
       end
 
+      #
+      # @return [Boolean] true if this is a data column
+      #
+      # @see
+      #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/ddl/../../cassandra/glossary/gloss_glossary.html
+      #   The CQL3 glossary
+      #
       def data_column?
         !key?
       end
 
-      def to_cql
-        "#{@name} #{@type}"
+      #
+      # @return [Boolean] true if this is a collection column
+      #
+      def collection_column?
+        false
       end
 
+      #
+      # @param type_in [Symbol,Type] type to check against
+      # @return [Boolean] true if this column has the type given by `type_in`
+      #
+      def type?(type_in)
+        type == Type[type_in]
+      end
+
+      #
+      # @param value the value to cast
+      # @return the value cast to the appropriate type for this column
+      #
+      # @api private
+      #
       def cast(value)
         @type.cast(value)
       end
 
+      #
+      # @return [String] a CQL fragment representing this column in a table
+      #   definition
+      #
+      # @api private
+      #
+      def to_cql
+        "#{@name} #{@type}"
+      end
+
+      #
+      # @param other [Column] a column object
+      # @return [Boolean] true if this column has the same CQL representation
+      #   as `other` column
+      #
       def ==(other)
         to_cql == other.to_cql
       end
 
+      #
+      # @return [String] the column's name
+      #
       def to_s
         name
       end
 
+      #
+      # @return [String] human-readable representation of this column
+      #
       def inspect
         %Q(#<#{self.class.name}: #{to_cql}>)
       end
-
     end
 
+    #
+    # A partition key column
+    #
     class PartitionKey < Column
-
+      #
+      # (see Column#partition_key?)
+      #
       def partition_key?
         true
       end
-
     end
 
+    #
+    # A clustering column
+    #
     class ClusteringColumn < Column
-
+      #
+      # @return [:asc,:desc] whether rows are ordered by ascending or
+      #   descending values in this column
+      #
       attr_reader :clustering_order
 
+      #
+      # @param (see Column#initialize)
+      # @param clustering_order [:asc,:desc] ascending or descending order for
+      #   this column
+      #
       def initialize(name, type, clustering_order = nil)
         super(name, type)
         @clustering_order = (clustering_order || :asc).to_sym
       end
 
-      def clustering_order_cql
-        "#{@name} #{@clustering_order}"
-      end
-
+      #
+      # (see Column#clustering_column?)
+      #
       def clustering_column?
         true
       end
 
+      # @private
+      def clustering_order_cql
+        "#{@name} #{@clustering_order}"
+      end
     end
 
+    #
+    # A scalar data column
+    #
     class DataColumn < Column
-
+      #
+      # @return [Symbol] name of the secondary index applied to this column, if
+      #   any
+      #
       attr_reader :index_name
 
+      #
+      # @param (see Column#initialize)
+      # @param index_name [Symbol] name this column's secondary index
+      #
       def initialize(name, type, index_name = nil)
         super(name, type)
         @index_name = index_name
       end
 
+      #
+      # @return [Boolean] true if this column has a secondary index
+      #
       def indexed?
         !!@index_name
       end
-
     end
 
+    #
+    # A collection column (list, set, or map)
+    #
+    # @abstract
+    #
     class CollectionColumn < Column
+      # (see Column#collection_column?)
+      def collection_column?
+        true
+      end
 
+      # (see DataColumn#indexed?)
       def indexed?
         false
       end
-
     end
 
+    #
+    # A List column
+    #
+    # @see http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_using/use_collections_c.html#task_ds_lqp_krj_zj CQL documentation for the list type
+    #
     class List < CollectionColumn
-
+      # (see Column#to_cql)
       def to_cql
         "#{@name} LIST <#{@type}>"
       end
 
+      #
+      # @return [Array] array with elements cast to correct type for column
+      #
       def cast(value)
         value.map { |element| @type.cast(element) }
       end
-
     end
 
+    #
+    # A Set column
+    #
+    # @see
+    #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_using/use_collections_c.html#task_ds_agt_3kj_zj
+    #   CQL documentation for set columns
+    #
     class Set < CollectionColumn
-
+      # (see Column#to_cql)
       def to_cql
         "#{@name} SET <#{@type}>"
       end
 
+      #
+      # @param (see Column#cast)
+      # @return [::Set] set with elements cast to correct type for column
+      #
       def cast(value)
-        value.each_with_object(::Set[]) do |element, set|
-          set << @type.cast(element)
-        end
+        value.to_set { |element| @type.cast(element) }
       end
-
     end
 
+    #
+    # A Map column
+    #
+    # @see
+    #   http://www.datastax.com/documentation/cql/3.0/webhelp/index.html#cql/cql_using/use_collections_c.html#task_ds_cvq_kcl_zj
+    #   CQL documentation for map columns
+    #
     class Map < CollectionColumn
-
+      # @return [Type] the type of keys in this map
       attr_reader :key_type
       alias_method :value_type, :type
 
+      #
+      # @param name [Symbol] name of this column
+      # @param key_type [Type] type of the keys in the map
+      # @param value_type [Type] type of the values in the map
+      #
       def initialize(name, key_type, value_type)
         super(name, value_type)
         @key_type = key_type
       end
 
+      # (see Column#to_cql)
       def to_cql
         "#{@name} MAP <#{@key_type}, #{@type}>"
       end
 
+      #
+      # @param (see Column#cast)
+      # @return [Hash] hash with keys and values cast to correct type for
+      #   column
+      #
       def cast(value)
         value.each_with_object({}) do |(key, element), hash|
           hash[@key_type.cast(key)] = @type.cast(element)
         end
       end
-
     end
-
   end
-
 end