cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/schema/table_property.rb

@@ -1,36 +1,75 @@
 module Cequel
-
   module Schema
-
+    #
+    # Encapsulates a CQL3 storage property defined on a table
+    #
     class TableProperty
+      # @return [Symbol] name of the property
+      attr_reader :name
+      # @return value of the property
+      attr_reader :value
 
-      attr_reader :name, :value
+      #
+      # Initialize an instance of the appropriate TableProperty implementation.
+      #
+      # @param (see #initialize)
+      # @api private
+      #
+      def self.build(name, value)
+        clazz =
+          case name.to_sym
+          when :compaction then CompactionProperty
+          when :compression then CompressionProperty
+          else TableProperty
+          end
+        clazz.new(name, value)
+      end
 
+      #
+      # @param name [Symbol] name of the property
+      # @param value value of the property
+      #
       def initialize(name, value)
         @name = name
-        set_normalized_value(value)
+        self.normalized_value = value
       end
+      class << self; protected :new; end
 
+      #
+      # @return [String] CQL fragment defining this property in a `CREATE
+      #   TABLE` statement
+      #
       def to_cql
-        if Hash === @value
-          map_pairs = @value.each_pair.
-            map { |key, value| "#{quote(key.to_s)} : #{quote(value)}" }.
-            join(', ')
-          value_cql = "{ #{map_pairs} }"
-        else
-          value_cql = quote(@value)
-        end
         "#{@name} = #{value_cql}"
       end
 
+      protected
+
+      def normalized_value=(value)
+        @value = value
+      end
+
       private
 
+      def value_cql
+        quote(@value)
+      end
+
       def quote(value)
         CassandraCQL::Statement.quote(value)
       end
+    end
+
+    #
+    # A table property whose value is itself a map of keys and values
+    #
+    # @abstract Inheriting classes must implement
+    #   `#normalize_map_property(key, value)`
+    #
+    class MapProperty < TableProperty
+      protected
 
-      def set_normalized_value(map)
-        return @value = map unless Hash === map
+      def normalized_value=(map)
         @value = {}
         map.each_pair do |key, value|
           key = key.to_sym
@@ -38,30 +77,49 @@ module Cequel
         end
       end
 
+      private
+
+      def value_cql
+        map_pairs = @value.each_pair
+          .map { |key, value| "#{quote(key.to_s)} : #{quote(value)}" }
+          .join(', ')
+        "{ #{map_pairs} }"
+      end
+    end
+
+    #
+    # A property comprising key-value pairs of compaction settings
+    #
+    class CompactionProperty < MapProperty
+      private
+
       def normalize_map_property(key, value)
-        case @name
-        when :compaction
-          case key
-          when :class
-            value.sub(/^org\.apache\.cassandra\.db\.compaction\./, '')
-          when :bucket_high, :bucket_low, :tombstone_threshold then value.to_f
-          when :max_threshold, :min_threshold, :min_sstable_size,
-            :sstable_size_in_mb, :tombstone_compaction_interval then value.to_i
-          else value.to_s
-          end
-        when :compression
-          case key
-          when :sstable_compression
-            value.sub(/^org\.apache\.cassandra\.io\.compress\./, '')
-          when :chunk_length_kb then value.to_i
-          when :crc_check_chance then value.to_f
-          else value.to_s
-          end
+        case key
+        when :class
+          value.sub(/^org\.apache\.cassandra\.db\.compaction\./, '')
+        when :bucket_high, :bucket_low, :tombstone_threshold then value.to_f
+        when :max_threshold, :min_threshold, :min_sstable_size,
+          :sstable_size_in_mb, :tombstone_compaction_interval then value.to_i
+        else value.to_s
         end
       end
-
     end
 
-  end
+    #
+    # A property comprising key-value pairs of compression settings
+    #
+    class CompressionProperty < MapProperty
+      private
 
+      def normalize_map_property(key, value)
+        case key
+        when :sstable_compression
+          value.sub(/^org\.apache\.cassandra\.io\.compress\./, '')
+        when :chunk_length_kb then value.to_i
+        when :crc_check_chance then value.to_f
+        else value.to_s
+        end
+      end
+    end
+  end
 end

data/lib/cequel/schema/table_reader.rb

@@ -1,9 +1,11 @@
 module Cequel
-
   module Schema
-
+    #
+    # A TableReader will query Cassandra's internal representation of a table's
+    # schema, and build a {Table} instance exposing an object representation of
+    # that schema
+    #
     class TableReader
-
       COMPOSITE_TYPE_PATTERN =
         /^org\.apache\.cassandra\.db\.marshal\.CompositeType\((.+)\)$/
       REVERSED_TYPE_PATTERN =
@@ -11,22 +13,40 @@ module Cequel
       COLLECTION_TYPE_PATTERN =
         /^org\.apache\.cassandra\.db\.marshal\.(List|Set|Map)Type\((.+)\)$/
 
-      STORAGE_PROPERTIES = %w[bloom_filter_fp_chance caching comment compaction
-        compression dclocal_read_repair_chance gc_grace_seconds
-        read_repair_chance replicate_on_write]
-
+      # @return [Table] object representation of the table defined in the
+      #   database
       attr_reader :table
 
+      #
+      # Read the schema defined in the database for a given table and return a
+      # {Table} instance
+      #
+      # @param (see #initialize)
+      # @return (see #read)
+      #
       def self.read(keyspace, table_name)
         new(keyspace, table_name).read
       end
 
+      #
+      # @param keyspace [Metal::Keyspace] keyspace to read the table from
+      # @param table_name [Symbol] name of the table to read
+      # @private
+      #
       def initialize(keyspace, table_name)
         @keyspace, @table_name = keyspace, table_name
         @table = Table.new(table_name.to_sym)
       end
       private_class_method(:new)
 
+      #
+      # Read table schema from the database
+      #
+      # @return [Table] object representation of table in the database, or
+      #   `nil` if no table by given name exists
+      #
+      # @api private
+      #
       def read
         if table_data.present?
           read_partition_keys
@@ -38,10 +58,19 @@ module Cequel
       end
 
       protected
+
       attr_reader :keyspace, :table_name, :table
 
       private
 
+      # XXX This gets a lot easier in Cassandra 2.0: all logical columns
+      # (including keys) are returned from the `schema_columns` query, so
+      # there's no need to jump through all these hoops to figure out what the
+      # key columns look like.
+      #
+      # However, this approach works for both 1.2 and 2.0, so better to keep it
+      # for now. It will be worth refactoring this code to take advantage of
+      # 2.0's better interface in a future version of Cequel that targets 2.0+.
       def read_partition_keys
         validator = table_data['key_validator']
         types = parse_composite_types(validator) || [validator]
@@ -51,6 +80,7 @@ module Cequel
         end
       end
 
+      # XXX See comment on {read_partition_keys}
       def read_clustering_columns
         column_aliases = JSON.parse(table_data['column_aliases'])
         comparators = parse_composite_types(table_data['comparator'])
@@ -100,16 +130,17 @@ module Cequel
       end
 
       def read_collection_column(name, collection_type, *internal_types)
-        types = internal_types.map { |internal| Type.lookup_internal(internal) }
+        types = internal_types
+          .map { |internal| Type.lookup_internal(internal) }
         table.__send__("add_#{collection_type}", name.to_sym, *types)
       end
 
       def read_properties
-        table_data.slice(*STORAGE_PROPERTIES).each do |name, value|
+        table_data.slice(*Table::STORAGE_PROPERTIES).each do |name, value|
           table.add_property(name, value)
         end
-        compaction = JSON.parse(table_data['compaction_strategy_options']).
-          symbolize_keys
+        compaction = JSON.parse(table_data['compaction_strategy_options'])
+          .symbolize_keys
         compaction[:class] = table_data['compaction_strategy_class']
         table.add_property(:compaction, compaction)
         compression = JSON.parse(table_data['compression_parameters'])
@@ -138,12 +169,11 @@ module Cequel
               SELECT * FROM system.schema_columns
               WHERE keyspace_name = ? AND columnfamily_name = ?
             CQL
-            column_query.map(&:to_hash)
+            column_query.map(&:to_hash).select do |column|
+              !column.key?('type') || column['type'] == 'regular'
+            end
           end
       end
-
     end
-
   end
-
 end

data/lib/cequel/schema/table_synchronizer.rb

@@ -1,9 +1,30 @@
 module Cequel
-
   module Schema
-
+    #
+    # Synchronize a table schema in the database with a desired table schema
+    #
+    # @see .apply
+    # @see Keyspace#synchronize_table
+    #
     class TableSynchronizer
-
+      # @return [Table] table as it is currently defined
+      # @api private
+      attr_reader :existing
+      # @return [Table] table schema as it is desired
+      # @api private
+      attr_reader :updated
+      #
+      # Takes an existing table schema read from the database, and a desired
+      # schema for that table. Modifies the table schema in the database to
+      # match the desired schema, or creates the table as specified if it does
+      # not yet exist
+      #
+      # @param keyspace [Metal::Keyspace] keyspace that contains table
+      # @param existing [Table] table schema as it is currently defined
+      # @param updated [Table] table schema as it is desired
+      # @return [void]
+      # @raise (see #apply)
+      #
       def self.apply(keyspace, existing, updated)
         if existing
           TableUpdater.apply(keyspace, existing.name) do |updater|
@@ -14,28 +35,92 @@ module Cequel
         end
       end
 
+      #
+      # @param updater [TableUpdater] table updater to hold schema
+      #   modifications
+      # @param existing [Table] table schema as it is currently defined
+      # @param updated [Table] table schema as it is desired
+      # @return [void]
+      # @private
+      #
       def initialize(updater, existing, updated)
         @updater, @existing, @updated = updater, existing, updated
       end
       private_class_method :new
 
+      #
+      # Apply the changes needed to synchronize the schema in the database with
+      # the desired schema
+      #
+      # @return [void]
+      # @raise (see MigrationValidator#validate!)
+      #
+      # @api private
+      #
       def apply
+        validate!
         update_keys
         update_columns
         update_properties
       end
 
+      #
+      # Iterate over pairs of (old_key, new_key)
+      #
+      # @yieldparam old_key [Column] key in existing schema
+      # @yieldparam new_key [Column] corresponding key in updated schema
+      # @return [void]
+      #
+      # @api private
+      #
+      def each_key_pair(&block)
+        existing.key_columns.zip(updated.key_columns, &block)
+      end
+
+      #
+      # Iterate over pairs of (old_column, new_column)
+      #
+      # @yieldparam old_column [Column] column in existing schema
+      # @yieldparam new_column [Column] corresponding column in updated schema
+      # @return [void]
+      #
+      # @api private
+      #
+      def each_data_column_pair(&block)
+        if existing.compact_storage? && existing.clustering_columns.any?
+          yield existing.data_columns.first, updated.data_columns.first
+        else
+          old_columns = existing.data_columns.index_by { |col| col.name }
+          new_columns = updated.data_columns.index_by { |col| col.name }
+          all_column_names = (old_columns.keys + new_columns.keys).tap(&:uniq!)
+          all_column_names.each do |name|
+            yield old_columns[name], new_columns[name]
+          end
+        end
+      end
+
+      #
+      # Iterate over pairs of (old_clustering_column, new_clustering_column)
+      #
+      # @yieldparam old_clustering_column [Column] key in existing schema
+      # @yieldparam new_clustering_column [Column] corresponding key in updated
+      #   schema
+      # @return [void]
+      #
+      # @api private
+      #
+      def each_clustering_column_pair(&block)
+        existing.clustering_columns.zip(updated.clustering_columns, &block)
+      end
+
       protected
-      attr_reader :updater, :existing, :updated
+
+      attr_reader :updater
 
       private
 
       def update_keys
         each_key_pair do |old_key, new_key|
-          if old_key.type != new_key.type
-            raise InvalidSchemaMigration,
-              "Can't change type of key column #{old_key.name} from #{old_key.type} to #{new_key.type}"
-          end
           if old_key.name != new_key.name
             updater.rename_column(old_key.name || :column1, new_key.name)
           end
@@ -43,24 +128,19 @@ module Cequel
       end
 
       def update_columns
-        each_column_pair do |old_column, new_column|
+        each_data_column_pair do |old_column, new_column|
           if old_column.nil?
             add_column(new_column)
           elsif new_column
-            if old_column.class != new_column.class
-              raise InvalidSchemaMigration,
-                "Can't change #{old_column.name} from #{old_column.class.name.demodulize} to #{new_column.class.name.demodulize}"
-            end
             update_column(old_column, new_column)
+            update_index(old_column, new_column)
           end
         end
       end
 
       def add_column(column)
         updater.add_data_column(column)
-        if column.indexed?
-          updater.create_index(column.name, column.index_name)
-        end
+        updater.create_index(column.name, column.index_name) if column.indexed?
       end
 
       def update_column(old_column, new_column)
@@ -70,6 +150,9 @@ module Cequel
         if old_column.type != new_column.type
           updater.change_column(new_column.name, new_column.type)
         end
+      end
+
+      def update_index(old_column, new_column)
         if !old_column.indexed? && new_column.indexed?
           updater.create_index(new_column.name, new_column.index_name)
         elsif old_column.indexed? && !new_column.indexed?
@@ -88,34 +171,9 @@ module Cequel
         updater.change_properties(changes) if changes.any?
       end
 
-      def each_key_pair(&block)
-        if existing.partition_key_columns.length != updated.partition_key_columns.length
-          raise InvalidSchemaMigration,
-            "Existing partition keys #{existing.partition_key_columns.map { |key| key.name }.join(',')} differ from specified partition keys #{updated.partition_key_columns.map { |key| key.name }.join(',')}"
-        end
-        if existing.clustering_columns.length != updated.clustering_columns.length
-          raise InvalidSchemaMigration,
-            "Existing clustering keys #{existing.clustering_columns.map { |key| key.name }.join(',')} differ from specified clustering keys #{updated.clustering_columns.map { |key| key.name }.join(',')}"
-        end
-        existing.partition_key_columns.zip(updated.partition_key_columns, &block)
-        existing.clustering_columns.zip(updated.clustering_columns, &block)
-      end
-
-      def each_column_pair(&block)
-        if existing.compact_storage? && existing.clustering_columns.any?
-          yield existing.data_columns.first, updated.data_columns.first
-        else
-          old_columns = existing.data_columns.index_by { |col| col.name }
-          new_columns = updated.data_columns.index_by { |col| col.name }
-          all_column_names = (old_columns.keys + new_columns.keys).tap(&:uniq!)
-          all_column_names.each do |name|
-            yield old_columns[name], new_columns[name]
-          end
-        end
+      def validate!
+        MigrationValidator.validate!(self)
       end
-
     end
-
   end
-
 end