cequel 1.0.0.rc1 → 1.0.0.rc2

data/lib/cequel/schema/create_table_dsl.rb

@@ -1,56 +1,87 @@
 module Cequel
-
   module Schema
-
+    #
+    # Implements a DSL that can be used to define a table schema
+    #
+    # @see Keyspace#create_table
+    #
     class CreateTableDSL < BasicObject
-
+      extend ::Forwardable
+      #
+      # Evaluate `block` in the context of this DSL, and apply directives to
+      # `table`
+      #
+      # @param table [Table] a table
+      # @yield block evaluated in the context of the create table DSL
+      # @return [void]
+      #
+      # @api private
+      #
       def self.apply(table, &block)
         dsl = new(table)
         dsl.instance_eval(&block)
       end
 
+      #
+      # @param table [Table] table to apply directives to
+      #
+      # @api private
+      #
       def initialize(table)
         @table = table
       end
 
-      def partition_key(name, type)
-        @table.add_partition_key(name, type)
-      end
+      #
+      # @!method partition_key(name, type)
+      #   (see Cequel::Schema::Table#add_partition_key)
+      #
+      def_delegator :@table, :add_partition_key, :partition_key
 
-      def key(name, type, clustering_order = nil)
-        @table.add_key(name, type, clustering_order)
-      end
+      #
+      # @!method key(name, type, clustering_order = nil)
+      #   (see Cequel::Schema::Table#add_key)
+      #
+      def_delegator :@table, :add_key, :key
 
-      def column(name, type, options = {})
-        column = @table.add_data_column(name, type, options[:index])
-      end
+      #
+      # @!method column(name, type, options = {})
+      #   (see Cequel::Schema::Table#add_data_column)
+      #
+      def_delegator :@table, :add_data_column, :column
 
-      def list(name, type)
-        @table.add_list(name, type)
-      end
+      #
+      # @!method list(name, type)
+      #   (see Cequel::Schema::Table#add_list)
+      #
+      def_delegator :@table, :add_list, :list
 
-      def set(name, type)
-        @table.add_set(name, type)
-      end
+      #
+      # @!method set(name, type)
+      #   (see Cequel::Schema::Table#add_set)
+      #
+      def_delegator :@table, :add_set, :set
 
-      def map(name, key_type, value_type)
-        @table.add_map(
-          name,
-          key_type,
-          value_type
-        )
-      end
+      #
+      # @!method map(name, key_type, value_type)
+      #   (see Cequel::Schema::Table#add_map)
+      #
+      def_delegator :@table, :add_map, :map
 
-      def with(name, value)
-        @table.add_property(name, value)
-      end
+      #
+      # @!method with(name, value)
+      #   (see Cequel::Schema::Table#add_property)
+      #
+      def_delegator :@table, :add_property, :with
 
+      #
+      # Direct that this table use "compact storage". This is primarily useful
+      # for backwards compatibility with legacy CQL2 table schemas.
+      #
+      # @return [void]
+      #
       def compact_storage
         @table.compact_storage = true
       end
-
     end
-
   end
-
 end

data/lib/cequel/schema/keyspace.rb

@@ -1,20 +1,44 @@
 module Cequel
-
   module Schema
-
+    #
+    # Provides read/write access to the schema for a keyspace and the tables it
+    # contains
+    #
+    # @deprecated These methods will be exposed directly on
+    #   {Cequel::Metal::Keyspace} in a future version of Cequel
+    #
     class Keyspace
-
+      #
+      # @param keyspace [Keyspace] the keyspace whose schema this object
+      #   manipulates
+      #
+      # @api private
+      #
       def initialize(keyspace)
         @keyspace = keyspace
       end
 
+      #
+      # Create this keyspace in the database
+      #
+      # @param options [Options] persistence options for this keyspace.
+      # @option options [String] :class ("SimpleStrategy") the replication
+      #   strategy to use for this keyspace
+      # @option options [Integer] :replication_factor (1) the number of
+      #   replicas that should exist for each piece of data
+      # @return [void]
+      #
+      # @see TK CQL3 CREATE KEYSPACE documentation
+      #
       def create!(options = {})
         bare_connection =
           Metal::Keyspace.new(keyspace.configuration.except(:keyspace))
 
         options = options.symbolize_keys
         options[:class] ||= 'SimpleStrategy'
-        options[:replication_factor] ||= 1 if options[:class] == 'SimpleStrategy'
+        if options[:class] == 'SimpleStrategy'
+          options[:replication_factor] ||= 1
+        end
         options_strs = options.map do |name, value|
           "'#{name}': #{CassandraCQL::Statement.quote(value)}"
         end
@@ -25,34 +49,111 @@ module Cequel
         CQL
       end
 
+      #
+      # Drop this keyspace from the database
+      #
+      # @return [void]
+      #
+      # @see TK CQL3 DROP KEYSPACE documentation
+      #
       def drop!
         keyspace.execute("DROP KEYSPACE #{keyspace.name}")
       end
 
+      #
+      # @param name [Symbol] name of the table to read
+      # @return [Table] object representation of the table schema as it
+      #   currently exists in the database
+      #
       def read_table(name)
         TableReader.read(keyspace, name)
       end
 
+      #
+      # Create a table in the keyspace
+      #
+      # @param name [Symbol] name of the new table to create
+      # @yield block evaluated in the context of a {CreateTableDSL}
+      # @return [void]
+      #
+      # @example
+      #   schema.create_table :posts do
+      #     partition_key :blog_subdomain, :text
+      #     key :id, :timeuuid
+      #
+      #     column :title, :text
+      #     column :body, :text
+      #     column :author_id, :uuid, :index => true
+      #
+      #     with :caching, :all
+      #   end
+      #
+      # @see CreateTableDSL
+      #
       def create_table(name, &block)
         table = Table.new(name)
         CreateTableDSL.apply(table, &block)
         TableWriter.apply(keyspace, table)
       end
 
+      #
+      # Make changes to an existing table in the keyspace
+      #
+      # @param name [Symbol] the name of the table to alter
+      # @yield block evaluated in the context of an {UpdateTableDSL}
+      # @return [void]
+      #
+      # @example
+      #   schema.alter_table :posts do
+      #     add_set :categories, :text
+      #     rename_column :author_id, :author_uuid
+      #     create_index :title
+      #   end
+      #
+      # @see UpdateTableDSL
+      #
       def alter_table(name, &block)
         updater = TableUpdater.apply(keyspace, name) do |updater|
           UpdateTableDSL.apply(updater, &block)
         end
       end
 
+      #
+      # Remove all data from this table. Truncating a table can be much slower
+      # than simply iterating over its keys and issuing `DELETE` statements,
+      # particularly if the table does not have many rows. Truncating is
+      # equivalent to dropping a table and then recreating it
+      #
+      # @param name [Symbol] name of the table to truncate.
+      # @return [void]
+      #
       def truncate_table(name)
         keyspace.execute("TRUNCATE #{name}")
       end
 
+      #
+      # Drop this table from the keyspace
+      #
+      # @param name [Symbol] name of the table to drop
+      # @return [void]
+      #
       def drop_table(name)
         keyspace.execute("DROP TABLE #{name}")
       end
 
+      #
+      # Create or update a table to match a given schema structure. The desired
+      # schema structure is defined by the directives given in the block; this
+      # is then compared to the existing table in the database (if it is
+      # defined at all), and then the table is created or altered accordingly.
+      #
+      # @param name [Symbol] name of the table to synchronize
+      # @yield (see #create_table)
+      # @return [void]
+      # @raise (see TableSynchronizer#apply)
+      #
+      # @see #create_table Example of DSL usage
+      #
       def sync_table(name, &block)
         existing = read_table(name)
         updated = Table.new(name)
@@ -62,10 +163,8 @@ module Cequel
       alias_method :synchronize_table, :sync_table
 
       protected
-      attr_reader :keyspace
 
+      attr_reader :keyspace
     end
-
   end
-
 end

data/lib/cequel/schema/migration_validator.rb

@@ -0,0 +1,128 @@
+module Cequel
+  module Schema
+    #
+    # This is a utility class to test that it is possible to perform a given
+    # table schema migration
+    #
+    # @api private
+    #
+    class MigrationValidator
+      extend Forwardable
+      #
+      # Check for various impossible schema changes and raise if any are found
+      #
+      # @param (see #initialize)
+      # @return [void]
+      # @raise (see #validate)
+      #
+      def self.validate!(synchronizer)
+        new(synchronizer).validate!
+      end
+
+      #
+      # @param synchronizer [TableSynchronizer] the synchronizer to validate
+      #
+      def initialize(synchronizer)
+        @synchronizer = synchronizer
+      end
+
+      #
+      # Check for various impossible schema changes and raise if any are found
+      #
+      # @raise [InvalidSchemaMigration] if it is impossible to modify existing
+      #   table to match desired schema
+      #
+      def validate!
+        assert_keys_match!
+        assert_data_columns_match!
+      end
+
+      private
+
+      attr_reader :synchronizer
+      def_delegators :synchronizer, :each_key_pair,
+                     :each_clustering_column_pair, :each_data_column_pair,
+                     :existing, :updated
+
+      def assert_keys_match!
+        assert_partition_keys_match!
+        assert_clustering_columns_match!
+        assert_same_key_types!
+        assert_same_clustering_order!
+      end
+
+      def assert_same_key_types!
+        each_key_pair do |old_key, new_key|
+          if old_key.type != new_key.type
+            fail InvalidSchemaMigration,
+                 "Can't change type of key column #{old_key.name} from " \
+                 "#{old_key.type} to #{new_key.type}"
+          end
+        end
+      end
+
+      def assert_same_clustering_order!
+        each_clustering_column_pair do |old_key, new_key|
+          if old_key.clustering_order != new_key.clustering_order
+            fail InvalidSchemaMigration,
+                 "Can't change the clustering order of #{old_key.name} from " \
+                 "#{old_key.clustering_order} to #{new_key.clustering_order}"
+          end
+        end
+      end
+
+      def assert_partition_keys_match!
+        if existing.partition_key_column_count !=
+            updated.partition_key_column_count
+
+          fail InvalidSchemaMigration,
+               "Existing partition keys " \
+               "#{existing.partition_key_column_names.join(',')} " \
+               "differ from specified partition keys " \
+               "#{updated.partition_key_column_names.join(',')}"
+        end
+      end
+
+      def assert_clustering_columns_match!
+        if existing.clustering_column_count != updated.clustering_column_count
+          fail InvalidSchemaMigration,
+               "Existing clustering columns " \
+               "#{existing.clustering_column_names.join(',')} " \
+               "differ from specified clustering keys " \
+               "#{updated.clustering_column_names.join(',')}"
+        end
+      end
+
+      def assert_data_columns_match!
+        each_data_column_pair do |old_column, new_column|
+          if old_column && new_column
+            assert_valid_type_transition!(old_column, new_column)
+            assert_same_column_structure!(old_column, new_column)
+          end
+        end
+      end
+
+      def assert_valid_type_transition!(old_column, new_column)
+        if old_column.type != new_column.type
+          valid_new_types = old_column.type.compatible_types
+          unless valid_new_types.include?(new_column.type)
+            fail InvalidSchemaMigration,
+                 "Can't change #{old_column.name} from " \
+                 "#{old_column.type} to #{new_column.type}. " \
+                 "#{old_column.type} columns may only be altered to " \
+                 "#{valid_new_types.to_sentence}."
+          end
+        end
+      end
+
+      def assert_same_column_structure!(old_column, new_column)
+        if old_column.class != new_column.class
+          fail InvalidSchemaMigration,
+               "Can't change #{old_column.name} from " \
+               "#{old_column.class.name.demodulize} to " \
+               "#{new_column.class.name.demodulize}"
+        end
+      end
+    end
+  end
+end

data/lib/cequel/schema/table.rb

@@ -1,19 +1,42 @@
 require 'stringio'
 
 module Cequel
-
   module Schema
-
+    #
+    # An object representation of a CQL3 table schema.
+    #
+    # @see Keyspace#read_table
+    #
     class Table
+      STORAGE_PROPERTIES = %w[
+        bloom_filter_fp_chance caching comment compaction compression
+        dclocal_read_repair_chance gc_grace_seconds read_repair_chance
+        replicate_on_write
+      ]
 
-      attr_reader :name,
-                  :columns,
-                  :partition_key_columns,
-                  :clustering_columns,
-                  :data_columns,
-                  :properties
+      # @return [Symbol] the name of the table
+      attr_reader :name
+      # @return [Array<Column>] all columns defined on the table
+      attr_reader :columns
+      # @return [Array<PartitionKey>] partition key columns defined on the
+      #   table
+      attr_reader :partition_key_columns
+      # @return [Array<ClusteringColumn>] clustering columns defined on the
+      #   table
+      attr_reader :clustering_columns
+      # @return [Array<DataColumn,CollectionColumn>] data columns and
+      #   collection columns defined on the table
+      attr_reader :data_columns
+      # @return [Hash] storage properties defined on the table
+      attr_reader :properties
+      # @return [Boolean] `true` if this table is configured with compact
+      #   storage
       attr_writer :compact_storage
 
+      #
+      # @param name [Symbol] the name of the table
+      # @api private
+      #
       def initialize(name)
         @name = name
         @partition_key_columns, @clustering_columns, @data_columns = [], [], []
@@ -21,11 +44,24 @@ module Cequel
         @properties = ActiveSupport::HashWithIndifferentAccess.new
       end
 
+      #
+      # Define a key column. If this is the first key column defined, it will
+      # be a partition key; otherwise, it will be a clustering column.
+      #
+      # @param name [Symbol] the name of the column
+      # @param type [Symbol,Type] the type for the column
+      # @param clustering_order [:asc,:desc] whether rows should be in
+      #   ascending or descending order by this column. Only meaningful for
+      #   clustering columns.
+      # @return [void]
+      #
+      # @see #add_partition_key
+      #
       def add_key(name, type, clustering_order = nil)
         if @partition_key_columns.empty?
           unless clustering_order.nil?
-            raise ArgumentError,
-              "Can't set clustering order for partition key #{name}"
+            fail ArgumentError,
+                 "Can't set clustering order for partition key #{name}"
           end
           add_partition_key(name, type)
         else
@@ -33,82 +69,212 @@ module Cequel
         end
       end
 
+      #
+      # Define a partition key for the table
+      #
+      # @param name [Symbol] the name of the column
+      # @param type [Symbol,Type] the type for the column
+      # @return [void]
+      #
       def add_partition_key(name, type)
         PartitionKey.new(name, type(type)).tap do |column|
           @partition_key_columns << add_column(column)
         end
       end
 
+      #
+      # Define a clustering column for the table
+      #
+      # @param (see #add_key)
+      # @return [void]
+      #
       def add_clustering_column(name, type, clustering_order = nil)
-        ClusteringColumn.new(name, type(type), clustering_order).tap do |column|
-          @clustering_columns << add_column(column)
-        end
+        ClusteringColumn.new(name, type(type), clustering_order)
+          .tap { |column| @clustering_columns << add_column(column) }
       end
 
-      def add_data_column(name, type, index_name)
+      #
+      # Define a data column on the table
+      #
+      # @param name [Symbol] name of the column
+      # @param type [Type] type for the column
+      # @param options [Options] options for the column
+      # @option options [Boolean,Symbol] :index (nil) name of a secondary index
+      #   to apply to the column, or `true` to infer an index name by
+      #   convention
+      # @return [void]
+      #
+      def add_data_column(name, type, options = {})
+        options = {index: options} unless options.is_a?(Hash)
+        index_name = options[:index]
         index_name = :"#{@name}_#{name}_idx" if index_name == true
-        DataColumn.new(name, type(type), index_name).
-          tap { |column| @data_columns << add_column(column) }
+        DataColumn.new(name, type(type), index_name)
+          .tap { |column| @data_columns << add_column(column) }
       end
 
+      #
+      # Define a list column on the table
+      #
+      # @param name [Symbol] name of the list
+      # @param type [Symbol,Type] type of the list's elements
+      # @return [void]
+      #
+      # @see List
+      #
       def add_list(name, type)
         List.new(name, type(type)).tap do |column|
           @data_columns << add_column(column)
         end
       end
 
+      #
+      # Define a set column on the table
+      #
+      # @param name [Symbol] name of the set
+      # @param type [Symbol,Type] type of the set's elements
+      # @return [void]
+      #
+      # @see Set
+      #
       def add_set(name, type)
         Set.new(name, type(type)).tap do |column|
           @data_columns << add_column(column)
         end
       end
 
+      #
+      # Define a map column on the table
+      #
+      # @param name [Symbol] name of the set
+      # @param key_type [Symbol,Type] type of the map's keys
+      # @param value_type [Symbol,Type] type of the map's values
+      # @return [void]
+      #
+      # @see Map
+      #
       def add_map(name, key_type, value_type)
         Map.new(name, type(key_type), type(value_type)).tap do |column|
           @data_columns << add_column(column)
         end
       end
 
+      #
+      # Define a storage property for the table
+      #
+      # @param name [Symbol] name of the property
+      # @param value value for the property
+      # @return [void]
+      #
+      # @see STORAGE_PROPERTIES List of storage property names
+      # @see TK list of CQL3 table storage properties
+      #
       def add_property(name, value)
-        TableProperty.new(name, value).tap do |property|
+        TableProperty.build(name, value).tap do |property|
           @properties[name] = property
         end
       end
 
+      #
+      # @param name [Symbol] name of column to look up
+      # @return [Column] column defined on table with given name
+      #
       def column(name)
         columns_by_name[name.to_sym]
       end
 
+      #
+      # @return [Array<Column>] all key columns (partition + clustering)
+      #
       def key_columns
         @partition_key_columns + @clustering_columns
       end
 
+      #
+      # @return [Array<Symbol>] names of all key columns (partition +
+      #   clustering)
+      #
       def key_column_names
         key_columns.map { |key| key.name }
       end
 
+      #
+      # @return [Integer] total number of key columns
+      #
+      def key_column_count
+        key_columns.length
+      end
+
+      #
+      # @return [Array<Symbol>] names of partition key columns
+      #
+      def partition_key_column_names
+        partition_key_columns.map { |key| key.name }
+      end
+
+      #
+      # @return [Integer] number of partition key columns
+      #
+      def partition_key_column_count
+        partition_key_columns.length
+      end
+
+      #
+      # @return [Array<Symbol>] names of clustering columns
+      #
+      def clustering_column_names
+        clustering_columns.map { |key| key.name }
+      end
+
+      #
+      # @return [Integer] number of clustering columns
+      #
+      def clustering_column_count
+        clustering_columns.length
+      end
+
+      #
+      # @param name [Symbol] name of partition key column to look up
+      # @return [PartitionKey] partition key column with given name
+      #
       def partition_key(name)
         @partition_key_columns.find { |column| column.name == name }
       end
 
+      #
+      # @param name [Symbol] name of clustering column to look up
+      # @return [ClusteringColumn] clustering column with given name
+      #
       def clustering_column(name)
         @clustering_columns.find { |column| column.name == name }
       end
 
+      #
+      # @param name [Symbol] name of data column to look up
+      # @return [DataColumn,CollectionColumn] data column or collection column
+      #   with given name
+      #
       def data_column(name)
         name = name.to_sym
         @data_columns.find { |column| column.name == name }
       end
 
+      #
+      # @param name [Symbol] name of property to look up
+      # @return [TableProperty] property as defined on table
+      #
       def property(name)
         @properties[name].try(:value)
       end
 
+      #
+      # @return [Boolean] `true` if this table uses compact storage
+      #
       def compact_storage?
         !!@compact_storage
       end
 
       protected
+
       attr_reader :columns_by_name
 
       private
@@ -121,9 +287,6 @@ module Cequel
       def type(type)
         ::Cequel::Type[type]
       end
-
     end
-
   end
-
 end