cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/schema/table_updater.rb

@@ -1,69 +1,163 @@
 module Cequel
-
   module Schema
-
+    #
+    # Encapsulates a series of schema modification statements that can be
+    # applied to an existing table
+    #
     class TableUpdater
-
-      def self.apply(keyspace, table_name)
-        new(keyspace, table_name).
-          tap { |updater| yield updater if block_given? }.
-          apply
+      #
+      # Construct a table updater and apply the schema modifications to the
+      # given table.
+      #
+      # @param (see #initialize)
+      # @yieldparam updater [TableUpdater] instance of updater whose
+      #   modifications will be applied to the named table
+      # @return [void]
+      #
+      def self.apply(keyspace, table_name, &block)
+        new(keyspace, table_name).tap(&block).apply
       end
 
+      #
+      # @param keyspace [Metal::Keyspace] keyspace containing the table
+      # @param table_name [Symbol] name of the table to modify
+      # @private
+      #
       def initialize(keyspace, table_name)
         @keyspace, @table_name = keyspace, table_name
         @statements = []
       end
       private_class_method :new
 
+      #
+      # Apply the schema modifications to the table schema in the database
+      #
+      # @return [void]
+      #
+      # @api private
+      #
       def apply
         statements.each { |statement| keyspace.execute(statement) }
       end
 
+      #
+      # Add a column to the table
+      #
+      # @param name [Symbol] the name of the column
+      # @param type [Symbol,Type] the type of the column
+      # @return [void]
+      #
       def add_column(name, type)
-        add_data_column(Column.new(name, type))
+        add_data_column(Column.new(name, type(type)))
       end
 
+      #
+      # Add a list to the table
+      #
+      # @param name [Symbol] the name of the list
+      # @param type [Symbol,Type] the type of the list elements
+      # @return [void]
+      #
       def add_list(name, type)
-        add_data_column(List.new(name, type))
+        add_data_column(List.new(name, type(type)))
       end
 
+      #
+      # Add a set to the table
+      #
+      # @param name [Symbol] the name of the set
+      # @param type [Symbol,Type] the type of the set elements
+      # @return [void]
+      #
       def add_set(name, type)
-        add_data_column(Set.new(name, type))
+        add_data_column(Set.new(name, type(type)))
       end
 
+      #
+      # Add a map to the table
+      #
+      # @param name [Symbol] the name of the map
+      # @param key_type [Symbol,Type] the type of the map's keys
+      # @param value_type [Symbol,Type] the type of the map's values
+      # @return [void]
+      #
       def add_map(name, key_type, value_type)
-        add_data_column(Map.new(name, key_type, value_type))
+        add_data_column(Map.new(name, type(key_type), type(value_type)))
       end
 
+      #
+      # Change an existing column's type
+      #
+      # @param name [Symbol] the name of the column
+      # @param type [Symbol,Type] the new type of the column
+      # @return [void]
+      #
+      # @note Changing the type of a CQL column does not modify the data
+      #   currently stored in the column. Thus, client-side handling is needed
+      #   to convert old values to the new type at read time. Cequel does not
+      #   currently support this functionality, although it may in the future.
+      #   Altering column types is not recommended.
+      #
       def change_column(name, type)
-        alter_table("ALTER #{name} TYPE #{type.cql_name}")
+        alter_table("ALTER #{name} TYPE #{type(type).cql_name}")
       end
 
+      #
+      # Rename a column
+      #
+      # @param old_name [Symbol] the current name of the column
+      # @param new_name [Symbol] the new name of the column
+      # @return [void]
+      #
       def rename_column(old_name, new_name)
         alter_table(%(RENAME "#{old_name}" TO "#{new_name}"))
       end
 
+      #
+      # Change one or more table storage properties
+      #
+      # @param options [Hash] map of property names to new values
+      # @return [void]
+      #
+      # @see Table#add_property
+      #
       def change_properties(options)
-        properties = options.
-          map { |name, value| TableProperty.new(name, value).to_cql }
+        properties = options
+          .map { |name, value| TableProperty.build(name, value).to_cql }
         alter_table("WITH #{properties.join(' AND ')}")
       end
 
-      def create_index(column, index_name)
-        index_name ||= "#{table_name}_#{column}_idx"
-        statements << "CREATE INDEX #{index_name} ON #{table_name} (#{column})"
+      #
+      # Create a secondary index
+      #
+      # @param column_name [Symbol] name of the column to add an index on
+      # @param index_name [Symbol] name of the index; will be inferred from
+      #   convention if nil
+      # @return [void]
+      #
+      def create_index(column_name, index_name = nil)
+        index_name ||= "#{table_name}_#{column_name}_idx"
+        statements <<
+          "CREATE INDEX #{index_name} ON #{table_name} (#{column_name})"
       end
 
+      #
+      # Remove a secondary index
+      #
+      # @param index_name [Symbol] the name of the index to remove
+      # @return [void]
+      #
       def drop_index(index_name)
         statements << "DROP INDEX #{index_name}"
       end
 
+      # @!visibility protected
       def add_data_column(column)
         add_column_statement(column)
       end
 
       protected
+
       attr_reader :keyspace, :table_name, :statements
 
       private
@@ -76,8 +170,9 @@ module Cequel
         alter_table("ADD #{column.to_cql}")
       end
 
+      def type(type)
+        ::Cequel::Type[type]
+      end
     end
-
   end
-
 end

data/lib/cequel/schema/table_writer.rb

@@ -1,25 +1,44 @@
 module Cequel
-
   module Schema
-
-
+    #
+    # Creates a new table schema in the database
+    #
     class TableWriter
-
+      #
+      # Creates a new table schema in the database given an object
+      # representation of the schema to create
+      #
+      # @param (see #initialize)
+      # @return (see #apply)
+      #
       def self.apply(keyspace, table)
         new(keyspace, table).apply
       end
 
+      #
+      # @param keyspace [Keyspace] keyspace in which to create the table
+      # @param table [Table] object representation of table schema
+      # @private
+      #
       def initialize(keyspace, table)
         @keyspace, @table = keyspace, table
       end
       private_class_method :new
 
+      #
+      # Create the table in the keyspace
+      #
+      # @return [void]
+      #
+      # @api private
+      #
       def apply
         keyspace.execute(create_statement)
         index_statements.each { |statement| keyspace.execute(statement) }
       end
 
       protected
+
       attr_reader :keyspace, :table
 
       private
@@ -36,7 +55,8 @@ module Cequel
           table.data_columns.each do |column|
             if column.indexed?
               statements <<
-                "CREATE INDEX #{column.index_name} ON #{table.name} (#{column.name})"
+                "CREATE INDEX #{column.index_name} " \
+                "ON #{table.name} (#{column.name})"
             end
           end
         end
@@ -51,8 +71,8 @@ module Cequel
       end
 
       def keys_cql
-        partition_cql = table.partition_key_columns.
-          map { |key| key.name }.join(', ')
+        partition_cql = table.partition_key_columns
+          .map { |key| key.name }.join(', ')
         if table.clustering_columns.any?
           nonpartition_cql =
             table.clustering_columns.map { |key| key.name }.join(', ')
@@ -63,19 +83,17 @@ module Cequel
       end
 
       def properties_cql
-        properties_fragments = table.properties.
-          map { |_, property| property.to_cql }
+        properties_fragments = table.properties
+          .map { |_, property| property.to_cql }
         properties_fragments << 'COMPACT STORAGE' if table.compact_storage?
         if table.clustering_columns.any?
           clustering_fragment =
             table.clustering_columns.map(&:clustering_order_cql).join(',')
-          properties_fragments << "CLUSTERING ORDER BY (#{clustering_fragment})"
+          properties_fragments <<
+            "CLUSTERING ORDER BY (#{clustering_fragment})"
         end
         properties_fragments.join(' AND ') if properties_fragments.any?
       end
-
     end
-
   end
-
 end

data/lib/cequel/schema/update_table_dsl.rb

@@ -1,60 +1,91 @@
 module Cequel
-
   module Schema
-
+    #
+    # DSL for describing a series of schema modification statements
+    #
     class UpdateTableDSL < BasicObject
-
+      extend ::Forwardable
+      #
+      # Describe a series of schema modifications and build a {TableUpdater}
+      # to encapsulate them
+      #
+      # @param (see #initialize)
+      # @yield a block evaluated in the context of an {UpdateTableDSL} instance
+      # @return [void]
+      #
+      # @api private
+      # @see Keyspace#update_table
+      #
       def self.apply(updater, &block)
         dsl = new(updater)
         dsl.instance_eval(&block)
       end
 
+      #
+      # @param updater [TableUpdater]
+      #
+      # @api private
+      #
       def initialize(updater)
         @updater = updater
       end
 
-      def add_column(name, type)
-        @updater.add_column(name, ::Cequel::Type[type])
-      end
-
-      def add_list(name, type)
-        @updater.add_list(name, ::Cequel::Type[type])
-      end
-
-      def add_set(name, type)
-        @updater.add_set(name, ::Cequel::Type[type])
-      end
-
-      def add_map(name, key_type, value_type)
-        @updater.add_map(name, ::Cequel::Type[key_type],
-                         ::Cequel::Type[value_type])
-      end
-
-      def change_column(name, type)
-        @updater.change_column(name, ::Cequel::Type[type])
-      end
-
-      def rename_column(old_name, new_name)
-        @updater.rename_column(old_name, new_name)
-      end
-
-      def change_properties(options)
-        @updater.change_properties(options)
-      end
+      #
+      # @!method add_column(name, type)
+      #   (see Cequel::Schema::TableUpdater#add_column)
+      #
+      def_delegator :@updater, :add_column
+
+      #
+      # @!method add_list(name, type)
+      #   (see Cequel::Schema::TableUpdater#add_list)
+      #
+      def_delegator :@updater, :add_list
+
+      #
+      # @!method add_set(name, type)
+      #   (see Cequel::Schema::TableUpdater#add_set)
+      #
+      def_delegator :@updater, :add_set
+
+      #
+      # @!method add_map(name, key_type, value_type)
+      #   (see Cequel::Schema::TableUpdater#add_map)
+      #
+      def_delegator :@updater, :add_map
+
+      #
+      # @!method change_column(name, type)
+      #   (see Cequel::Schema::TableUpdater#change_column)
+      #
+      def_delegator :@updater, :change_column
+
+      #
+      # @!method rename_column(old_name, new_name)
+      #   (see Cequel::Schema::TableUpdater#rename_column)
+      #
+      def_delegator :@updater, :rename_column
+
+      #
+      # @!method change_properties(options)
+      #   (see Cequel::Schema::TableUpdater#change_properties)
+      #
+      def_delegator :@updater, :change_properties
       alias_method :change_options, :change_properties
 
-      def create_index(column_name, index_name = nil)
-        @updater.create_index(column_name, index_name)
-      end
+      #
+      # @!method create_index(column_name, index_name = nil)
+      #   (see Cequel::Schema::TableUpdater#create_index
+      #
+      def_delegator :@updater, :create_index
       alias_method :add_index, :create_index
 
-      def drop_index(index_name)
-        @updater.drop_index(index_name)
-      end
+      #
+      # @!method drop_index(index_name)
+      #   (see Cequel::Schema::TableUpdater#drop_index)
+      #
+      def_delegator :@updater, :drop_index
       alias_method :remove_index, :drop_index
-
     end
-
   end
-
 end

data/lib/cequel/type.rb

@@ -1,71 +1,172 @@
 require 'singleton'
 
 module Cequel
-
+  #
+  # The Type module encapsulates information about the CQL3 type system. Each
+  # type has a `cql_name`, which is the name of the type as defined in CQL, and
+  # an `internal_name`, which is the name of the type in the lower-level
+  # interface that is exposed when introspecting table information in the
+  # database.
+  #
+  # As well as knowing their respective names, types also know how to cast Ruby
+  # objects to the correct canonical class corresponding to the type. These
+  # implicit types are used by the underlying `cassandra-cql` library to
+  # determine how to represent values when passing them to Cassandra.
+  #
+  # @since 1.0.0
+  #
   module Type
-
+    # Raised if an unknown type is looked up
     UnknownType = Class.new(ArgumentError)
 
     BY_CQL_NAME = {}
     BY_INTERNAL_NAME = {}
 
+    #
+    # Register a type for lookup
+    #
+    # @param type [Type] a new type
+    # @return [void]
+    #
     def self.register(type)
       BY_CQL_NAME[type.cql_name] = type
       type.cql_aliases.each { |aliaz| BY_CQL_NAME[aliaz] = type }
-      BY_INTERNAL_NAME[type.internal_name] = type
+      type.internal_names.each do |internal_name|
+        BY_INTERNAL_NAME[internal_name] = type
+      end
     end
 
+    #
+    # Return a type corresponding to the given input
+    #
+    # @param cql_name [Symbol,Base] CQL name of a type, or a type
+    # @return [Base] type with the given CQL name
+    #
     def self.[](cql_name)
       cql_name.is_a?(Base) ? cql_name : lookup_cql(cql_name)
     end
 
+    #
+    # Look up a type by CQL name
+    #
+    # @param cql_name [Symbol] CQL name of a type
+    # @return [Base] type with the given CQL name
+    # @raise [UnknownType] if no type by that name is registered
+    #
     def self.lookup_cql(cql_name)
       BY_CQL_NAME.fetch(cql_name.to_sym)
     rescue KeyError
       raise UnknownType, "Unrecognized CQL type #{cql_name.inspect}"
     end
 
+    #
+    # Look up a type by internal name
+    #
+    # @param internal_name [String] internal name of a type
+    # @return [Base] type with the given internal name
+    # @raise [UnknownType] if no type by that name is registered
+    #
     def self.lookup_internal(internal_name)
       BY_INTERNAL_NAME.fetch(internal_name)
     rescue KeyError
       raise UnknownType, "Unrecognized internal type #{internal_name.inspect}"
     end
 
+    #
+    # The base class for all type objects. Types are singletons.
+    #
+    # @abstract Subclasses should implement {#cast}, and may implement
+    #   {#internal_names} if it cannot be inferred from the class name. The
+    #   name of the type class should be the camel-cased CQL name of the type
+    #
     class Base
       include Singleton
 
+      #
+      # @return the name of the type used in CQL. This is also the name that is
+      #   used in all of Cequel's public interfaces
+      #
       def cql_name
         self.class.name.demodulize.underscore.to_sym
       end
 
+      #
+      # @return [Array<Symbol>] other names used in CQL for this type
+      #
       def cql_aliases
         []
       end
 
+      #
+      # @return [Array<String>] full class name of this type used in
+      #   Cassandra's underlying representation
+      #
+      # @deprecated use {internal_names}
+      #
       def internal_name
-        "org.apache.cassandra.db.marshal.#{self.class.name.demodulize}Type"
+        internal_names.first
       end
 
+      #
+      # @return [Array<String>] full class name(s) of this type used in
+      #   Cassandra's underlying representation (allows for multiple values for
+      #   types that have different names between different versions)
+      #
+      def internal_names
+        ["org.apache.cassandra.db.marshal.#{self.class.name.demodulize}Type"]
+      end
+
+      #
+      # @param value the value to cast
+      # @return the value cast to the correct Ruby class for this type
+      #
       def cast(value)
         value
       end
 
+      #
+      # CQL only allows changing column types when the old type's binary
+      # representation is compatible with the new type.
+      #
+      # @return [Array<Type>] new types that columns of this type may be
+      #   altered to
+      #
+      def compatible_types
+        [Type[:blob]]
+      end
+
+      #
+      # A string representation of this type
+      #
       def to_s
         cql_name.to_s
       end
-
     end
 
+    #
+    # Abstract superclass for types that represent character data
+    #
+    # @abstract Subclasses must implement `#encoding`, which returns the name
+    #   of the Ruby encoding corresponding to the character encoding used for
+    #   values of this type
+    #
     class String < Base
-
       def cast(value)
         str = String(value)
         str.encoding.name == encoding ? str : str.dup.force_encoding(encoding)
       end
-
     end
 
+    #
+    # `ascii` columns store 7-bit ASCII character data
+    #
+    # @see TK CQL3 documentation for ascii type
+    #
     class Ascii < String
+      def compatible_types
+        super + [Type[:text]]
+      end
+
       private
 
       def encoding
@@ -74,14 +175,19 @@ module Cequel
     end
     register Ascii.instance
 
+    #
+    # `blob` columns store arbitrary bytes of data, represented as 8-bit ASCII
+    # strings of hex digits
+    #
+    # @see TK CQL3 documentation for blob type
+    #
     class Blob < String
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.BytesType'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.BytesType']
       end
 
       def cast(value)
-        value = value.to_s(16) if Integer === value
+        value = value.to_s(16) if value.is_a?(Integer)
         super
       end
 
@@ -90,10 +196,14 @@ module Cequel
       def encoding
         'ASCII-8BIT'
       end
-
     end
     register Blob.instance
 
+    #
+    # `boolean` types store boolean values
+    #
+    # @see TK CQL3 documentation for boolean type
+    #
     class Boolean < Base
       def cast(value)
         !!value
@@ -101,26 +211,47 @@ module Cequel
     end
     register Boolean.instance
 
+    #
+    # Counter columns are a special type of column in Cassandra that can be
+    # incremented and decremented atomically. Counter columns cannot comingle
+    # with regular data columns in the same table. Unlike other columns,
+    # counter columns cannot be updated without Cassandra internally reading
+    # the existing state of the column
+    #
+    # @see TK CQL3 documentation for counter columns
+    #
     class Counter < Base
+      def internal_names
+        ['org.apache.cassandra.db.marshal.CounterColumnType']
+      end
 
-      def internal_name
-        'org.apache.cassandra.db.marshal.CounterColumnType'
+      def compatible_types
+        []
       end
 
       def cast(value)
         Integer(value)
       end
-
     end
     register Counter.instance
 
+    #
+    # `decimal` columns store decimal numeric values
+    #
+    # @see TK CQL3 documentation for decimal columns
+    #
     class Decimal < Base
       def cast(value)
-        BigDecimal === value ? value : BigDecimal.new(value, 0)
+        value.is_a?(BigDecimal) ? value : BigDecimal.new(value, 0)
       end
     end
     register Decimal.instance
 
+    #
+    # `double` columns store 64-bit floating-point numeric values
+    #
+    # @see TK CQL3 documentation for double columns
+    #
     class Double < Base
       def cast(value)
         Float(value)
@@ -128,44 +259,64 @@ module Cequel
     end
     register Double.instance
 
+    #
+    # TK
+    #
+    # @see TK CQL3 documentation for inet columns
+    #
     class Inet < Base
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.InetAddressType'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.InetAddressType']
       end
-
     end
     register Inet.instance
 
+    #
+    # `int` columns store 32-bit integer values
+    #
+    # @see TK CQL3 documentation for int columns
+    #
     class Int < Base
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.Int32Type'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.Int32Type']
       end
 
       def cast(value)
         Integer(value)
       end
-
     end
     register Int.instance
 
+    #
+    # `float` columns store 32-bit floating-point numeric values
+    #
+    # @see TK CQL3 documentation for float columns
+    #
     class Float < Double; end
     register Float.instance
 
-    class Long < Int
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.LongType'
+    #
+    # `bigint` columns store 64-bit integer values
+    #
+    # @see TK CQL3 documentation for bigint columns
+    #
+    class Bigint < Int
+      def internal_names
+        ['org.apache.cassandra.db.marshal.LongType']
       end
-
     end
-    register Long.instance
-
+    register Bigint.instance
+
+    #
+    # `text` columns store UTF-8 character data. They are also known as
+    # `varchar` columns; the names can be used interchangeably. Text columns do
+    # not have a length limit
+    #
+    # @see TK CQL3 documentation for text columns
+    #
     class Text < String
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.UTF8Type'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.UTF8Type']
       end
 
       def cql_aliases
@@ -177,31 +328,38 @@ module Cequel
       def encoding
         'UTF-8'
       end
-
     end
     register Text.instance
 
+    #
+    # `timestamp` columns store timestamps. Timestamps do not include time zone
+    # data, and all input times are cast to UTC before being stored.
+    #
     class Timestamp < Base
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.DateType'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.DateType',
+         'org.apache.cassandra.db.marshal.TimestampType']
       end
 
       def cast(value)
-        if ::String === value then Time.parse(value)
+        if value.is_a?(::String) then Time.parse(value)
         elsif value.respond_to?(:to_time) then value.to_time
-        elsif Numeric === value then Time.at(value)
+        elsif value.is_a?(Numeric) then Time.at(value)
         else Time.parse(value.to_s)
         end.utc
       end
-
     end
     register Timestamp.instance
 
+    #
+    # `uuid` columns store type 1 and type 4 UUIDs. Cequel uses the
+    # `CassandraCQL::UUID` type to represent UUIDs in Ruby, since this is what
+    # the underlying `cassandra-cql` library expects. Other UUID formats are
+    # supported as inputs.
+    #
     class Uuid < Base
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.UUIDType'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.UUIDType']
       end
 
       def cast(value)
@@ -211,28 +369,31 @@ module Cequel
         else CassandraCQL::UUID.new(value)
         end
       end
-
     end
     register Uuid.instance
 
+    #
+    # `timeuuid` columns are a special type of UUID column that support
+    # time-based queries. For instance, a `timeuuid` clustering column can be
+    # filtered by ranges of times into which the UUIDs must fall. This
+    # functionality presumes the use of type 1 UUIDs, which encode the
+    # timestamp of their creation.
+    #
     class Timeuuid < Uuid
-
-      def internal_name
-        'org.apache.cassandra.db.marshal.TimeUUIDType'
+      def internal_names
+        ['org.apache.cassandra.db.marshal.TimeUUIDType']
       end
-
     end
     register Timeuuid.instance
 
+    #
+    # `varint` columns store arbitrary-length integer data
+    #
     class Varint < Int
-
       def internal_name
         'org.apache.cassandra.db.marshal.IntegerType'
       end
-
     end
     register Varint.instance
-
   end
-
 end