sequel_core 1.5.1 → 2.0.0

data/lib/sequel_core/schema/generator.rb

@@ -1,6 +1,19 @@
 module Sequel
+  # The Schema module holds the schema generators and the SQL code relating
+  # to SQL DDL (Data Definition Language).
   module Schema
+    # Schema::Generator is used to create tables.  It takes a Database
+    # object and a block of column/index/constraint specifications, and
+    # creates a table in the database based on the specifications.
+    #
+    # Schema::Generator has some methods but also includes method_missing,
+    # allowing users to specify column type as a method instead of using
+    # the column method, which makes for a nicer DSL.
+    #
+    # See Database#create_table.
     class Generator
+      # Set the database in which to create the table, and evaluate the block
+      # in the context of this object.
       def initialize(db, &block)
         @db = db
         @columns = []
@@ -9,171 +22,216 @@ module Sequel
         instance_eval(&block) if block
       end
       
-      def method_missing(type, name = nil, opts = {})
-        name ? column(name, type, opts) : super
-      end
-      
-      def primary_key_name
-        @primary_key ? @primary_key[:name] : nil
-      end
-      
-      def primary_key(name, *args)
-        @primary_key = @db.serial_primary_key_options.merge({:name => name})
-        
-        if opts = args.pop
-          opts = {:type => opts} unless opts.is_a?(Hash)
-          if type = args.pop
-            opts.merge!(:type => type)
-          end
-          @primary_key.merge!(opts)
-        end
-        @primary_key
+      # Add a unnamed constraint to the DDL, specified by the given block
+      # or args.
+      def check(*args, &block)
+        constraint(nil, *args, &block)
       end
-      
+
+      # Add a column with the given name, type, and opts to the DDL. 
+      #
+      # You can also create columns via method missing, so the following are
+      # equivalent:
+      #
+      #   column :number, :integer
+      #   integer :number
+      #
+      # The following options are supported:
+      #
+      # * :default - The default value for the column.
+      # * :index - Create an index on this column.
+      # * :key - For foreign key columns, the column in the associated table
+      #   that this column references.  Unnecessary if this column
+      #   references the primary key of the associated table.
+      # * :null - Mark the column as allowing NULL values (if true),
+      #   or not allowing NULL values (if false).  If unspecified, will default
+      #   to whatever the database default is.
+      # * :on_delete - Specify the behavior of this column when being deleted.
+      #   See Schema::SQL#on_delete_clause for options.
+      # * :size - The size of the column, generally used with string
+      #   columns to specify the maximum number of characters the column will hold.
+      # * :unique - Mark the column is unique, generally has the same effect as
+      #   creating a unique index on the column.
+      # * :unsigned - Make the column type unsigned, only useful for integer
+      #   columns.
       def column(name, type, opts = {})
         @columns << {:name => name, :type => type}.merge(opts)
         index(name) if opts[:index]
       end
       
-      def foreign_key(name, opts = {})
-        @columns << {:name => name, :type => :integer}.merge(opts)
-        index(name) if opts[:index]
+      # Adds a named constraint (or unnamed if name is nil) to the DDL,
+      # with the given block or args.
+      def constraint(name, *args, &block)
+        @columns << {:name => name, :type => :check, :check => block || args}
       end
       
-      def check(*args, &block)
-        @columns << {:name => nil, :type => :check, :check => block || args}
+      # Return the DDL created by the generator as a array of two elements,
+      # the first being the columns and the second being the indexes.
+      def create_info
+        @columns.unshift(@primary_key) if @primary_key && !has_column?(primary_key_name)
+        [@columns, @indexes]
       end
 
-      def constraint(name, *args, &block)
-        @columns << {:name => name, :type => :check, :check => block || args}
+      # Add a foreign key in the table that references another table to the DDL. See column
+      # for available options.
+      def foreign_key(name, table=nil, opts = {})
+        opts = case table
+        when Hash
+          table.merge(opts)
+        when Symbol
+          opts.merge(:table=>table)
+        when NilClass
+          opts
+        else
+          raise(Error, "The seconds argument to foreign_key should be a Hash, Symbol, or nil")
+        end
+        column(name, :integer, opts)
+      end
+      
+      # Add a full text index on the given columns to the DDL.
+      def full_text_index(columns, opts = {})
+        index(columns, opts.merge(:type => :full_text))
       end
       
+      # True if the DDL includes the creation of a column with the given name.
       def has_column?(name)
-        @columns.each {|c| return true if c[:name] == name}
-        false
+        @columns.any?{|c| c[:name] == name}
       end
       
+      # Add an index on the given column(s) with the given options to the DDL.
+      # The available options are:
+      #
+      # * :type - The type of index to use (only supported by some databases)
+      # * :unique - Make the index unique, so duplicate values are not allowed.
+      # * :where - Create a partial index (only supported by some databases)
       def index(columns, opts = {})
-        columns = [columns] unless columns.is_a?(Array)
-        @indexes << {:columns => columns}.merge(opts)
+        @indexes << {:columns => Array(columns)}.merge(opts)
       end
       
-      def full_text_index(columns, opts = {})
-        index(columns, opts.merge(:type => :full_text))
+      # Add a column with the given type, name, and opts to the DDL.  See column for available
+      # options.
+      def method_missing(type, name = nil, opts = {})
+        name ? column(name, type, opts) : super
       end
       
+      # Add a column with the given name and primary key options to the DDL. You
+      # can optionally provide a type argument and/or an options hash argument
+      # to change the primary key options. See column for available options.
+      def primary_key(name, *args)
+        @primary_key = @db.serial_primary_key_options.merge({:name => name})
+        
+        if opts = args.pop
+          opts = {:type => opts} unless opts.is_a?(Hash)
+          if type = args.pop
+            opts.merge!(:type => type)
+          end
+          @primary_key.merge!(opts)
+        end
+        @primary_key
+      end
+      
+      # The name of the primary key for this table, if it has a primary key.
+      def primary_key_name
+        @primary_key[:name] if @primary_key
+      end
+      
+      # Add a spatial index on the given columns to the DDL.
       def spatial_index(columns, opts = {})
         index(columns, opts.merge(:type => :spatial))
       end
 
+      # Add a unique index on the given columns to the DDL.
       def unique(columns, opts = {})
         index(columns, opts.merge(:unique => true))
       end
-      
-      def create_info
-        if @primary_key && !has_column?(@primary_key[:name])
-          @columns.unshift(@primary_key)
-        end
-        [@columns, @indexes]
-      end
     end
   
+    # The Schema::AlterTableGenerator creates DDL operations on existing tables,
+    # such as adding/removing/modifying columns/indexes/constraints.
     class AlterTableGenerator
+      # An array of DDL operations to perform
       attr_reader :operations
       
+      # Set the Database object to which to apply the DDL, and evaluate the
+      # block in the context of this object.
       def initialize(db, &block)
         @db = db
         @operations = []
         instance_eval(&block) if block
       end
       
+      # Add a column with the given name, type, and opts to the DDL for the table.
+      # See Generator#column for the available options.
       def add_column(name, type, opts = {})
-        @operations << { \
-          :op => :add_column, \
-          :name => name, \
-          :type => type \
-        }.merge(opts)
+        @operations << {:op => :add_column, :name => name, :type => type}.merge(opts)
       end
       
-      def drop_column(name)
-        @operations << { \
-          :op => :drop_column, \
-          :name => name \
-        }
+      # Add a constraint with the given name and args to the DDL for the table.
+      # See Generator#constraint.
+      def add_constraint(name, *args, &block)
+        @operations << {:op => :add_constraint, :name => name, :type => :check, \
+          :check => block || args}
+      end
+
+      # Add a foreign key with the given name and referencing the given table
+      # to the DDL for the table.  See Generator#column for the available options.
+      def add_foreign_key(name, table, opts = {})
+        add_column(name, :integer, {:table=>table}.merge(opts))
       end
       
-      def rename_column(name, new_name, opts = {})
-        @operations << { \
-          :op => :rename_column, \
-          :name => name, \
-          :new_name => new_name \
-        }.merge(opts)
+      # Add a full text index on the given columns to the DDL for the table.
+      # See Generator#index for available options.
+      def add_full_text_index(columns, opts = {})
+        add_index(columns, {:type=>:full_text}.merge(opts))
       end
       
-      def set_column_type(name, type)
-        @operations << { \
-          :op => :set_column_type, \
-          :name => name, \
-          :type => type \
-        }
+      # Add an index on the given columns to the DDL for the table.  See
+      # Generator#index for available options.
+      def add_index(columns, opts = {})
+        @operations << {:op => :add_index, :columns => Array(columns)}.merge(opts)
       end
       
-      def set_column_default(name, default)
-        @operations << { \
-          :op => :set_column_default, \
-          :name => name, \
-          :default => default \
-        }
+      # Add a primary key to the DDL for the table.  See Generator#column
+      # for the available options.
+      def add_primary_key(name, opts = {})
+        opts = @db.serial_primary_key_options.merge(opts)
+        add_column(name, opts.delete(:type), opts)
       end
       
-      def add_index(columns, opts = {})
-        columns = [columns] unless columns.is_a?(Array)
-        @operations << { \
-          :op => :add_index, \
-          :columns => columns \
-        }.merge(opts)
+      # Add a spatial index on the given columns to the DDL for the table.
+      # See Generator#index for available options.
+      def add_spatial_index(columns, opts = {})
+        add_index(columns, {:type=>:spatial}.merge(opts))
       end
       
-      def add_full_text_index(columns, opts = {})
-        columns = [columns] unless columns.is_a?(Array)
-        @operations << { \
-          :op => :add_index, \
-          :columns => columns, \
-          :type => :full_text \
-        }.merge(opts)
+      # Remove a column from the DDL for the table.
+      def drop_column(name)
+        @operations << {:op => :drop_column, :name => name}
       end
       
-      def add_spatial_index(columns, opts = {})
-        columns = [columns] unless columns.is_a?(Array)
-        @operations << { \
-          :op => :add_index, \
-          :columns => columns, \
-          :type => :spatial \
-        }.merge(opts)
+      # Remove a constraint from the DDL for the table.
+      def drop_constraint(name)
+        @operations << {:op => :drop_constraint, :name => name}
       end
       
+      # Remove an index from the DDL for the table.
       def drop_index(columns)
-        columns = [columns] unless columns.is_a?(Array)
-        @operations << { \
-          :op => :drop_index, \
-          :columns => columns \
-        }
+        @operations << {:op => :drop_index, :columns => Array(columns)}
       end
 
-      def add_constraint(name, *args, &block)
-        @operations << { \
-          :op => :add_constraint, \
-          :name => name, \
-          :type => :check, \
-          :check => block || args \
-        }
+      # Modify a column's name in the DDL for the table.
+      def rename_column(name, new_name, opts = {})
+        @operations << {:op => :rename_column, :name => name, :new_name => new_name}.merge(opts)
+      end
+      
+      # Modify a column's default value in the DDL for the table.
+      def set_column_default(name, default)
+        @operations << {:op => :set_column_default, :name => name, :default => default}
       end
 
-      def drop_constraint(name)
-        @operations << { \
-          :op => :drop_constraint, \
-          :name => name \
-        }
+      # Modify a column's type in the DDL for the table.
+      def set_column_type(name, type)
+        @operations << {:op => :set_column_type, :name => name, :type => type}
       end
     end
   end