sequel 4.26.0 → 5.37.0

data/lib/sequel/database/query.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   class Database
     # ---------------------
@@ -5,10 +7,8 @@ module Sequel
     # This methods generally execute SQL code on the database server.
     # ---------------------
 
-    STRING_DEFAULT_RE = /\A'(.*)'\z/
-    CURRENT_TIMESTAMP_RE = /now|today|CURRENT|getdate|\ADate\(\)\z/io
-    COLUMN_SCHEMA_DATETIME_TYPES = [:date, :datetime]
-    COLUMN_SCHEMA_STRING_TYPES = [:string, :blob, :date, :datetime, :time, :enum, :set, :interval]
+    COLUMN_SCHEMA_DATETIME_TYPES = [:date, :datetime].freeze
+    COLUMN_SCHEMA_STRING_TYPES = [:string, :blob, :date, :datetime, :time, :enum, :set, :interval].freeze
 
     # The prepared statement object hash for this database, keyed by name symbol
     attr_reader :prepared_statements
@@ -30,9 +30,9 @@ module Sequel
     # Call the prepared statement with the given name with the given hash
     # of arguments.
     #
-    #   DB[:items].filter(:id=>1).prepare(:first, :sa)
+    #   DB[:items].where(id: 1).prepare(:first, :sa)
     #   DB.call(:sa) # SELECT * FROM items WHERE id = 1
-    def call(ps_name, hash={}, &block)
+    def call(ps_name, hash=OPTS, &block)
       prepared_statement(ps_name).call(hash, &block)
     end
     
@@ -43,7 +43,7 @@ module Sequel
       execute_dui(sql, opts, &block)
     end
 
-    # Method that should be used when issuing a DELETE, UPDATE, or INSERT
+    # Method that should be used when issuing a DELETE or UPDATE
     # statement.  By default, calls execute.
     # This method should not be called directly by user code.
     def execute_dui(sql, opts=OPTS, &block)
@@ -57,11 +57,11 @@ module Sequel
       execute_dui(sql, opts, &block)
     end
 
-    # Returns a single value from the database, e.g.:
+    # Returns a single value from the database, see Dataset#get.
     #
     #   DB.get(1) # SELECT 1
     #   # => 1
-    #   DB.get{server_version{}} # SELECT server_version()
+    #   DB.get{server_version.function} # SELECT server_version()
     def get(*args, &block)
       @default_dataset.get(*args, &block)
     end
@@ -86,7 +86,7 @@ module Sequel
     # :schema :: An explicit schema to use.  It may also be implicitly provided
     #            via the table name.
     #
-    # If schema parsing is supported by the database, the column information should hash at least contain the
+    # If schema parsing is supported by the database, the column information hash should contain at least the
     # following entries:
     #
     # :allow_null :: Whether NULL is an allowed value for the column.
@@ -157,11 +157,11 @@ module Sequel
       end
 
       cols = schema_parse_table(table_name, opts)
-      raise(Error, 'schema parsing returned no columns, table probably doesn\'t exist') if cols.nil? || cols.empty?
+      raise(Error, "schema parsing returned no columns, table #{table_name.inspect} probably doesn't exist") if cols.nil? || cols.empty?
 
       primary_keys = 0
       auto_increment_set = false
-      cols.all? do |_,c|
+      cols.each do |_,c|
         auto_increment_set = true if c.has_key?(:auto_increment)
         primary_keys += 1 if c[:primary_key]
       end
@@ -176,6 +176,8 @@ module Sequel
           c[:max_length] = max_length
         end
       end
+      schema_post_process(cols)
+
       Sequel.synchronize{@schemas[quoted_name] = cols} if cache_schema
       cols
     end
@@ -191,7 +193,8 @@ module Sequel
     def table_exists?(name)
       sch, table_name = schema_and_table(name)
       name = SQL::QualifiedIdentifier.new(sch, table_name) if sch
-      _table_exists?(from(name))
+      ds = from(name)
+      transaction(:savepoint=>:only){_table_exists?(ds)}
       true
     rescue DatabaseError
       false
@@ -237,7 +240,7 @@ module Sequel
       when :time
         Sequel.string_to_time(default)
       when :decimal
-        BigDecimal.new(default)
+        BigDecimal(default)
       end
     end
    
@@ -245,7 +248,7 @@ module Sequel
     # and return the normalized value.
     def column_schema_normalize_default(default, type)
       if column_schema_default_string_type?(type)
-        return unless m = STRING_DEFAULT_RE.match(default)
+        return unless m = /\A'(.*)'\z/.match(default)
         m[1].gsub("''", "'")
       else
         default
@@ -257,7 +260,7 @@ module Sequel
     def column_schema_to_ruby_default(default, type)
       return default unless default.is_a?(String)
       if COLUMN_SCHEMA_DATETIME_TYPES.include?(type)
-        if CURRENT_TIMESTAMP_RE.match(default)
+        if /now|today|CURRENT|getdate|\ADate\(\)\z/i.match(default)
           if type == :date
             return Sequel::CURRENT_DATE
           else
@@ -284,16 +287,16 @@ module Sequel
       (ds || dataset).method(:input_identifier)
     end
     
+    # Uncached version of metadata_dataset, designed for overriding.
+    def _metadata_dataset
+      dataset
+    end
+
     # Return a dataset that uses the default identifier input and output methods
     # for this database.  Used when parsing metadata so that column symbols are
     # returned as expected.
     def metadata_dataset
-      @metadata_dataset ||= (
-        ds = dataset;
-        ds.identifier_input_method = identifier_input_method_default;
-        ds.identifier_output_method = identifier_output_method_default;
-        ds
-      )
+      @metadata_dataset ||= _metadata_dataset
     end
 
     # Return a Method object for the dataset's output_identifier_method.
@@ -305,10 +308,10 @@ module Sequel
 
     # Remove the cached schema for the given schema name
     def remove_cached_schema(table)
-      if @schemas
-        k = quote_schema_table(table)
-        Sequel.synchronize{@schemas.delete(k)}
-      end
+      cache = @default_dataset.send(:cache)
+      Sequel.synchronize{cache.clear}
+      k = quote_schema_table(table)
+      Sequel.synchronize{@schemas.delete(k)}
     end
     
     # Match the database's column type to a ruby type via a
@@ -322,13 +325,13 @@ module Sequel
         :integer
       when /\Adate\z/io
         :date
-      when /\A((small)?datetime|timestamp( with(out)? time zone)?)(\(\d+\))?\z/io
+      when /\A((small)?datetime|timestamp(\(\d\))?( with(out)? time zone)?)\z/io
         :datetime
       when /\Atime( with(out)? time zone)?\z/io
         :time
       when /\A(bool(ean)?)\z/io
         :boolean
-      when /\A(real|float|double( precision)?|double\(\d+,\d+\)( unsigned)?)\z/io
+      when /\A(real|float( unsigned)?|double( precision)?|double\(\d+,\d+\)( unsigned)?)\z/io
         :float
       when /\A(?:(?:(?:num(?:ber|eric)?|decimal)(?:\(\d+,\s*(\d+|false|true)\))?))\z/io
         $1 && ['0', 'false'].include?($1) ? :integer : :decimal
@@ -338,5 +341,25 @@ module Sequel
         :enum
       end
     end
+
+    # Post process the schema values.  
+    def schema_post_process(cols)
+      # :nocov:
+      if RUBY_VERSION >= '2.5'
+      # :nocov:
+        cols.each do |_, h|
+          db_type = h[:db_type]
+          if db_type.is_a?(String)
+            h[:db_type] = -db_type
+          end
+        end
+      end
+
+      cols.each do |_,c|
+        c.each_value do |val|
+          val.freeze if val.is_a?(String)
+        end
+      end
+    end
   end
 end

data/lib/sequel/database/schema_generator.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module Sequel
   # The Schema module holds the schema generators.
   module Schema
@@ -16,16 +18,15 @@ module Sequel
     # the {"Schema Modification" guide}[rdoc-ref:doc/schema_modification.rdoc].
     class CreateTableGenerator
       # Classes specifying generic types that Sequel will convert to database-specific types.
-      GENERIC_TYPES=[String, Integer, Fixnum, Bignum, Float, Numeric, BigDecimal,
-      Date, DateTime, Time, File, TrueClass, FalseClass]
+      GENERIC_TYPES=%w'String Integer Float Numeric BigDecimal Date DateTime Time File TrueClass FalseClass'.freeze
       
-      # Return the column hashes created by this generator
+      # Column hashes created by this generator
       attr_reader :columns
 
-      # Return the constraint hashes created by this generator
+      # Constraint hashes created by this generator
       attr_reader :constraints
 
-      # Return the index hashes created by this generator
+      # Index hashes created by this generator
       attr_reader :indexes
 
       # Set the database in which to create the table, and evaluate the block
@@ -36,38 +37,55 @@ module Sequel
         @indexes = []
         @constraints = []
         @primary_key = nil
-        instance_eval(&block) if block
-        @columns.unshift(@primary_key) if @primary_key && !has_column?(primary_key_name)
+        instance_exec(&block) if block
+      end
+
+      # Use custom Bignum method to use :Bignum instead of Bignum class, to work
+      # correctly in cases where Bignum is the same as Integer.
+      def Bignum(name, opts=OPTS)
+        column(name, :Bignum, opts)
       end
       
+      # Use custom Fixnum method to use Integer instead of Fixnum class, to avoid 
+      # warnings on ruby 2.4+.
+      def Fixnum(name, opts=OPTS)
+        column(name, Integer, opts)
+      end
+
       # Add a method for each of the given types that creates a column
       # with that type as a constant.  Types given should either already
       # be constants/classes or a capitalized string/symbol with the same name
       # as a constant/class.
-      #
-      # Do not call this method with untrusted input, as that can result in
-      # arbitrary code execution.
       def self.add_type_method(*types)
         types.each do |type|
-          class_eval("def #{type}(name, opts={}); column(name, #{type}, opts); end", __FILE__, __LINE__)
+          case type
+          when Symbol, String
+            method = type
+            type = Object.const_get(type)
+          else
+            method = type.to_s
+          end
+
+          define_method(method){|name, opts=OPTS| column(name, type, opts)}
         end
+        nil
       end
       
-      # Add an unnamed constraint to the DDL, specified by the given block
+      # Add an unnamed constraint, specified by the given block
       # or args:
       #
-      #   check(:num=>1..5) # CHECK num >= 1 AND num <= 5
-      #   check{num > 5} # CHECK num > 5
+      #   check(num: 1..5) # CHECK num >= 1 AND num <= 5
+      #   check{num > 5}   # CHECK num > 5
       def check(*args, &block)
         constraint(nil, *args, &block)
       end
 
-      # Add a column with the given name, type, and opts to the DDL. 
+      # Add a column with the given name, type, and opts:
       #
       #   column :num, :integer
       #   # num INTEGER
       #
-      #   column :name, String, :null=>false, :default=>'a'
+      #   column :name, String, null: false, default: 'a'
       #   # name varchar(255) NOT NULL DEFAULT 'a'
       #
       #   inet :ip
@@ -91,6 +109,9 @@ module Sequel
       #                yet exist on referenced table (but will exist before the transaction commits).
       #                Basically it adds DEFERRABLE INITIALLY DEFERRED on key creation.
       #                If you use :immediate as the value, uses DEFERRABLE INITIALLY IMMEDIATE.
+      # :generated_always_as :: Specify a GENERATED ALWAYS AS column expression,
+      #                         if generated columns are supported (PostgreSQL 12+, MariaDB 5.2.0+,
+      #                         and MySQL 5.7.6+).
       # :index :: Create an index on this column.  If given a hash, use the hash as the
       #           options for the index.
       # :key :: For foreign key columns, the column in the associated table
@@ -98,47 +119,61 @@ module Sequel
       #         references the primary key of the associated table, except if you are
       #         using MySQL.
       # :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.
+      #          or not allowing NULL values (if false).  The default is to allow NULL values.
       # :on_delete :: Specify the behavior of this column when being deleted
       #               (:restrict, :cascade, :set_null, :set_default, :no_action).
       # :on_update :: Specify the behavior of this column when being updated
       #               (:restrict, :cascade, :set_null, :set_default, :no_action).
-      # :primary_key :: Make the column as a single primary key column.  This should only
-      #                 be used if you have a single, nonautoincrementing primary key column.
+      # :primary_key :: Make the column as a single primary key column.  This should not
+      #                 be used if you want a single autoincrementing primary key column
+      #                 (use the primary_key method in that case).
       # :primary_key_constraint_name :: The name to give the primary key constraint
+      # :primary_key_deferrable :: Similar to :deferrable, but for the primary key constraint
+      #                            if :primary_key is used.
       # :type :: Overrides the type given as the argument.  Generally not used by column
       #          itself, but can be passed as an option to other methods that call column.
       # :unique :: Mark the column as unique, generally has the same effect as
       #            creating a unique index on the column.
       # :unique_constraint_name :: The name to give the unique key constraint
+      # :unique_deferrable :: Similar to :deferrable, but for the unique constraint if :unique
+      #                       is used.
+      #
+      # PostgreSQL specific options:
+      #
+      # :identity :: Create an identity column.
+      #
+      # MySQL specific options:
+      # :generated_type :: Set the type of column when using :generated_always_as,
+      #                    should be :virtual or :stored to force a type.
       def column(name, type, opts = OPTS)
         columns << {:name => name, :type => type}.merge!(opts)
         if index_opts = opts[:index]
-          index(name, index_opts.is_a?(Hash) ? index_opts : {})
+          index(name, index_opts.is_a?(Hash) ? index_opts : OPTS)
         end
+        nil
       end
       
-      # Adds a named constraint (or unnamed if name is nil) to the DDL,
+      # Adds a named constraint (or unnamed if name is nil),
       # with the given block or args. To provide options for the constraint, pass
       # a hash as the first argument.
       #
-      #   constraint(:blah, :num=>1..5)
+      #   constraint(:blah, num: 1..5)
       #   # CONSTRAINT blah CHECK num >= 1 AND num <= 5
-      #   constraint({:name=>:blah, :deferrable=>true}, :num=>1..5)
+      #   constraint({name: :blah, deferrable: true}, num: 1..5)
       #   # CONSTRAINT blah CHECK num >= 1 AND num <= 5 DEFERRABLE INITIALLY DEFERRED
       def constraint(name, *args, &block)
         opts = name.is_a?(Hash) ? name : {:name=>name}
         constraints << opts.merge(:type=>:check, :check=>block || args)
+        nil
       end
       
-      # Add a foreign key in the table that references another table to the DDL. See column
+      # Add a foreign key in the table that references another table. See #column
       # for available options.
       #
       #   foreign_key(:artist_id) # artist_id INTEGER
       #   foreign_key(:artist_id, :artists) # artist_id INTEGER REFERENCES artists
-      #   foreign_key(:artist_id, :artists, :key=>:id) # artist_id INTEGER REFERENCES artists(id)
-      #   foreign_key(:artist_id, :artists, :type=>String) # artist_id varchar(255) REFERENCES artists(id)
+      #   foreign_key(:artist_id, :artists, key: :id) # artist_id INTEGER REFERENCES artists(id)
+      #   foreign_key(:artist_id, :artists, type: String) # artist_id varchar(255) REFERENCES artists(id)
       #
       # Additional Options:
       #
@@ -148,24 +183,22 @@ module Sequel
       # composite foreign key), you can provide an array of columns as the first argument, and
       # you can provide the :name option to name the constraint:
       #
-      #   foreign_key([:artist_name, :artist_location], :artists, :name=>:artist_fk)
+      #   foreign_key([:artist_name, :artist_location], :artists, name: :artist_fk)
       #   # ADD CONSTRAINT artist_fk FOREIGN KEY (artist_name, artist_location) REFERENCES artists
       def foreign_key(name, table=nil, opts = OPTS)
         opts = case table
         when Hash
           table.merge(opts)
-        when Symbol
-          opts.merge(:table=>table)
         when NilClass
           opts
         else
-          raise(Error, "The second argument to foreign_key should be a Hash, Symbol, or nil")
+          opts.merge(:table=>table)
         end
         return composite_foreign_key(name, opts) if name.is_a?(Array)
         column(name, Integer, opts)
       end
 
-      # Add a full text index on the given columns to the DDL.
+      # Add a full text index on the given columns.
       #
       # PostgreSQL specific options:
       # :index_type :: Can be set to :gist to use a GIST index instead of the
@@ -178,12 +211,12 @@ module Sequel
         index(columns, opts.merge(:type => :full_text))
       end
       
-      # True if the DDL includes the creation of a column with the given name.
+      # True if the generator includes the creation of a column with the given name.
       def has_column?(name)
         columns.any?{|c| c[:name] == name}
       end
       
-      # Add an index on the given column(s) with the given options to the DDL.
+      # Add an index on the given column(s) with the given options.
       # General options:
       #
       # :name :: The name to use for the index. If not given, a default name
@@ -198,6 +231,9 @@ module Sequel
       #                  operations on the table while the index is being
       #                  built.
       # :opclass :: Use a specific operator class in the index.
+      # :include :: Include additional column values in the index, without
+      #             actually indexing on those values (PostgreSQL 11+).
+      # :tablespace :: Specify tablespace for index.
       #
       # Microsoft SQL Server specific options:
       #
@@ -211,9 +247,10 @@ module Sequel
       #   # CREATE INDEX table_artist_id_name_index ON table (artist_id, name)
       def index(columns, opts = OPTS)
         indexes << {:columns => Array(columns)}.merge!(opts)
+        nil
       end
       
-      # Add a column with the given type, name, and opts to the DDL.  See +column+ for available
+      # Add a column with the given type, name, and opts.  See #column for available
       # options.
       def method_missing(type, name = nil, opts = OPTS)
         name ? column(name, type, opts) : super
@@ -224,7 +261,7 @@ module Sequel
         true
       end
       
-      # Adds an autoincrementing primary key column or a primary key constraint to the DDL.
+      # Adds an autoincrementing primary key column or a primary key constraint.
       # To just create a constraint, the first argument should be an array of column symbols
       # specifying the primary key columns. To create an autoincrementing primary key
       # column, a single symbol can be used. In both cases, an options hash can be used
@@ -232,26 +269,39 @@ module Sequel
       # 
       # If you want to create a primary key column that is not autoincrementing, you
       # should not use this method.  Instead, you should use the regular +column+ method
-      # with a <tt>:primary_key=>true</tt> option.
+      # with a <tt>primary_key: true</tt> option.
       #
       # If an array of column symbols is used, you can specify the :name option
       # to name the constraint.
+      #
+      # Options:
+      # :keep_order :: For non-composite primary keys, respects the existing order of
+      #                columns, overriding the default behavior of making the primary
+      #                key the first column.
       # 
       # Examples:
       #   primary_key(:id)
-      #   primary_key([:street_number, :house_number], :name=>:some constraint_name)
+      #   primary_key(:id, type: :Bignum, keep_order: true)
+      #   primary_key([:street_number, :house_number], name: :some constraint_name)
       def primary_key(name, *args)
         return composite_primary_key(name, *args) if name.is_a?(Array)
-        @primary_key = @db.serial_primary_key_options.merge({:name => name})
+        column = @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)
+            opts = opts.merge(:type => type)
           end
-          @primary_key.merge!(opts)
+          column.merge!(opts)
         end
-        @primary_key
+
+        @primary_key = column
+        if column[:keep_order]
+          columns << column
+        else
+          columns.unshift(column)
+        end
+        nil
       end
 
       # The name of the primary key for this generator, if it has a primary key.
@@ -259,12 +309,12 @@ module Sequel
         @primary_key[:name] if @primary_key
       end
       
-      # Add a spatial index on the given columns to the DDL.
+      # Add a spatial index on the given columns.
       def spatial_index(columns, opts = OPTS)
         index(columns, opts.merge(:type => :spatial))
       end
 
-      # Add a unique constraint on the given columns to the DDL.
+      # Add a unique constraint on the given columns.
       #
       #   unique(:name) # UNIQUE (name)
       #
@@ -272,27 +322,27 @@ module Sequel
       # to name the constraint.
       def unique(columns, opts = OPTS)
         constraints << {:type => :unique, :columns => Array(columns)}.merge!(opts)
+        nil
       end
 
       private
 
       # Add a composite primary key constraint
       def composite_primary_key(columns, *args)
-        opts = args.pop || {}
+        opts = args.pop || OPTS
         constraints << {:type => :primary_key, :columns => columns}.merge!(opts)
+        nil
       end
 
       # Add a composite foreign key constraint
       def composite_foreign_key(columns, opts)
         constraints << {:type => :foreign_key, :columns => columns}.merge!(opts)
+        nil
       end
       
       add_type_method(*GENERIC_TYPES)
     end
 
-    # Alias of CreateTableGenerator for backwards compatibility.
-    Generator = CreateTableGenerator
-  
     # Schema::AlterTableGenerator is an internal class that the user is not expected
     # to instantiate directly.  Instances are created by Database#alter_table.
     # It is used to specify table alteration parameters.  It takes a Database
@@ -303,49 +353,63 @@ module Sequel
     # For more information on Sequel's support for schema modification, see
     # the {"Schema Modification" guide}[link:files/doc/schema_modification_rdoc.html].
     class AlterTableGenerator
-      # An array of DDL operations to perform
+      # An array of operations to perform
       attr_reader :operations
       
-      # Set the Database object to which to apply the DDL, and evaluate the
+      # Set the Database object to which to apply the changes, and evaluate the
       # block in the context of this object.
       def initialize(db, &block)
         @db = db
         @operations = []
-        instance_eval(&block) if block
+        instance_exec(&block) if block
       end
       
-      # Add a column with the given name, type, and opts to the DDL for the table.
-      # See CreateTableGenerator#column for the available options.
+      # Add a column with the given name, type, and opts.
+      # See CreateTableGenerator#column for the available options (except for +:index+, use a
+      # separate +add_index+ call to add an index for the column).
       #
       #   add_column(:name, String) # ADD COLUMN name varchar(255)
+      #
+      # PostgreSQL specific options:
+      #
+      # :if_not_exists :: Set to true to not add the column if it already exists (PostgreSQL 9.6+)
+      #
+      # MySQL specific options:
+      #
+      # :after :: The name of an existing column that the new column should be positioned after
+      # :first :: Create this new column before all other existing columns
       def add_column(name, type, opts = OPTS)
         @operations << {:op => :add_column, :name => name, :type => type}.merge!(opts)
+        nil
       end
       
-      # Add a constraint with the given name and args to the DDL for the table.
+      # Add a constraint with the given name and args.
       # See CreateTableGenerator#constraint.
       #
       #   add_constraint(:valid_name, Sequel.like(:name, 'A%'))
       #   # ADD CONSTRAINT valid_name CHECK (name LIKE 'A%' ESCAPE '\')
-      #   add_constraint({:name=>:valid_name, :deferrable=>true}, Sequel.like(:name, 'A%'))
+      #   add_constraint({name: :valid_name, deferrable: true}, Sequel.like(:name, 'A%'))
       #   # ADD CONSTRAINT valid_name CHECK (name LIKE 'A%' ESCAPE '\') DEFERRABLE INITIALLY DEFERRED
       def add_constraint(name, *args, &block)
         opts = name.is_a?(Hash) ? name : {:name=>name}
         @operations << opts.merge(:op=>:add_constraint, :type=>:check, :check=>block || args)
+        nil
       end
 
       # Add a unique constraint to the given column(s)
       #
       #   add_unique_constraint(:name) # ADD UNIQUE (name)
-      #   add_unique_constraint(:name, :name=>:unique_name) # ADD CONSTRAINT unique_name UNIQUE (name)
+      #   add_unique_constraint(:name, name: :unique_name) # ADD CONSTRAINT unique_name UNIQUE (name)
       #
       # Supports the same :deferrable option as CreateTableGenerator#column.
       def add_unique_constraint(columns, opts = OPTS)
         @operations << {:op => :add_constraint, :type => :unique, :columns => Array(columns)}.merge!(opts)
+        nil
       end
 
-      # Add a foreign key with the given name and referencing the given table
-      # to the DDL for the table.  See CreateTableGenerator#column for the available options.
+      # Add a foreign key with the given name and referencing the given table.
+      # See CreateTableGenerator#column for the available options (except for +:index+, use a
+      # separate +add_index+ call to add an index for the column).
       #
       # You can also pass an array of column names for creating composite foreign
       # keys. In this case, it will assume the columns exist and will only add
@@ -371,21 +435,50 @@ module Sequel
         add_column(name, Integer, {:table=>table}.merge!(opts))
       end
       
-      # Add a full text index on the given columns to the DDL for the table.
+      # Add a full text index on the given columns.
       # See CreateTableGenerator#index for available options.
       def add_full_text_index(columns, opts = OPTS)
         add_index(columns, {:type=>:full_text}.merge!(opts))
       end
       
-      # Add an index on the given columns to the DDL for the table.  See
+      # Add an index on the given columns. See
       # CreateTableGenerator#index for available options.
       #
       #   add_index(:artist_id) # CREATE INDEX table_artist_id_index ON table (artist_id)
+      #
+      # Options:
+      #
+      # :name :: Give a specific name for the index. Highly recommended if you plan on
+      #          dropping the index later.
+      # :where :: A filter expression, used to setup a partial index (if supported).
+      # :unique :: Create a unique index.
+      #
+      # PostgreSQL specific options:
+      #
+      # :concurrently :: Create the index concurrently, so it doesn't require an exclusive lock
+      #                  on the table.
+      # :index_type :: The underlying index type to use for a full_text index, gin by default).
+      # :language :: The language to use for a full text index (simple by default).
+      # :opclass :: Set an opclass to use for all columns (per-column opclasses require
+      #             custom SQL).
+      # :type :: Set the index type (e.g. full_text, spatial, hash, gin, gist, btree).
+      # :if_not_exists :: Only create the index if an index of the same name doesn't already exists
+      #
+      # MySQL specific options:
+      #
+      # :type :: Set the index type, with full_text and spatial indexes handled specially.
+      #
+      # Microsoft SQL Server specific options:
+      #
+      # :include :: Includes additional columns in the index.
+      # :key_index :: Sets the KEY INDEX to the given value.
+      # :type :: clustered uses a clustered index, full_text uses a full text index.
       def add_index(columns, opts = OPTS)
         @operations << {:op => :add_index, :columns => Array(columns)}.merge!(opts)
+        nil
       end
       
-      # Add a primary key to the DDL for the table.  See CreateTableGenerator#column
+      # Add a primary key.  See CreateTableGenerator#column
       # for the available options.  Like +add_foreign_key+, if you specify
       # the column name as an array, it just creates a constraint:
       #
@@ -397,16 +490,16 @@ module Sequel
         add_column(name, opts.delete(:type), opts)
       end
       
-      # Add a spatial index on the given columns to the DDL for the table.
+      # Add a spatial index on the given columns.
       # See CreateTableGenerator#index for available options.
       def add_spatial_index(columns, opts = OPTS)
         add_index(columns, {:type=>:spatial}.merge!(opts))
       end
       
-      # Remove a column from the DDL for the table.
+      # Remove a column from the table.
       #
       #   drop_column(:artist_id) # DROP COLUMN artist_id
-      #   drop_column(:artist_id, :cascade=>true) # DROP COLUMN artist_id CASCADE
+      #   drop_column(:artist_id, cascade: true) # DROP COLUMN artist_id CASCADE
       #
       # Options:
       #
@@ -418,20 +511,24 @@ module Sequel
       #               exist.
       def drop_column(name, opts=OPTS)
         @operations << {:op => :drop_column, :name => name}.merge!(opts)
+        nil
       end
       
-      # Remove a constraint from the DDL for the table. MySQL/SQLite specific options:
+      # Remove a constraint from the table:
+      #
+      #   drop_constraint(:unique_name) # DROP CONSTRAINT unique_name
+      #   drop_constraint(:unique_name, cascade: true) # DROP CONSTRAINT unique_name CASCADE
+      #
+      # MySQL/SQLite specific options:
       #
       # :type :: Set the type of constraint to drop, either :primary_key, :foreign_key,
       #          or :unique.
-      #
-      #   drop_constraint(:unique_name) # DROP CONSTRAINT unique_name
-      #   drop_constraint(:unique_name, :cascade=>true) # DROP CONSTRAINT unique_name CASCADE
       def drop_constraint(name, opts=OPTS)
         @operations << {:op => :drop_constraint, :name => name}.merge!(opts)
+        nil
       end
       
-      # Remove a foreign key and the associated column from the DDL for the table. General options:
+      # Remove a foreign key and the associated column from the table. General options:
       #
       # :name :: The name of the constraint to drop.  If not given, uses the same name
       #          that would be used by add_foreign_key with the same columns.
@@ -442,11 +539,15 @@ module Sequel
       #   drop_foreign_key(:artist_id) # DROP CONSTRAINT table_artist_id_fkey, DROP COLUMN artist_id
       #   drop_foreign_key([:name]) # DROP CONSTRAINT table_name_fkey
       def drop_foreign_key(name, opts=OPTS)
+        if !name.is_a?(Array) && opts[:foreign_key_constraint_name]
+          opts = Hash[opts]
+          opts[:name] = opts[:foreign_key_constraint_name]
+        end
         drop_composite_foreign_key(Array(name), opts)
         drop_column(name) unless name.is_a?(Array)
       end
       
-      # Remove an index from the DDL for the table. General options:
+      # Remove an index from the table. General options:
       #
       # :name :: The name of the index to drop.  If not given, uses the same name
       #          that would be used by add_index with the same columns.
@@ -460,29 +561,36 @@ module Sequel
       #
       #   drop_index(:artist_id) # DROP INDEX table_artist_id_index
       #   drop_index([:a, :b]) # DROP INDEX table_a_b_index
-      #   drop_index([:a, :b], :name=>:foo) # DROP INDEX foo
+      #   drop_index([:a, :b], name: :foo) # DROP INDEX foo
       def drop_index(columns, options=OPTS)
         @operations << {:op => :drop_index, :columns => Array(columns)}.merge!(options)
+        nil
       end
 
-      # Modify a column's name in the DDL for the table.
+      # Rename one of the table's columns.
       #
       #   rename_column(:name, :artist_name) # RENAME COLUMN name TO artist_name
       def rename_column(name, new_name, opts = OPTS)
         @operations << {:op => :rename_column, :name => name, :new_name => new_name}.merge!(opts)
+        nil
       end
       
-      # Modify a column's default value in the DDL for the table.
+      # Modify the default value for one of the table's column.
       #
       #   set_column_default(:artist_name, 'a') # ALTER COLUMN artist_name SET DEFAULT 'a'
       #
+      # To remove an existing default value, use +nil+ as the value:
+      #
+      #   set_column_default(:artist_name, nil) # ALTER COLUMN artist_name SET DEFAULT NULL
+      #
       # On MySQL, make sure to use a symbol for the name of the column, as otherwise you
       # can lose the type and NULL/NOT NULL setting for the column.
       def set_column_default(name, default)
         @operations << {:op => :set_column_default, :name => name, :default => default}
+        nil
       end
 
-      # Modify a column's type in the DDL for the table.
+      # Modify the type of one of the table's column.
       #
       #   set_column_type(:artist_name, 'char(10)') # ALTER COLUMN artist_name TYPE char(10)
       #
@@ -494,6 +602,7 @@ module Sequel
       # can lose the default and NULL/NOT NULL setting for the column.
       def set_column_type(name, type, opts=OPTS)
         @operations << {:op => :set_column_type, :name => name, :type => type}.merge!(opts)
+        nil
       end
       
       # Set a given column as allowing NULL values.
@@ -504,6 +613,7 @@ module Sequel
       # can lose the default and type for the column.
       def set_column_allow_null(name, allow_null=true)
         @operations << {:op => :set_column_null, :name => name, :null => allow_null}
+        nil
       end
 
       # Set a given column as not allowing NULL values.
@@ -521,16 +631,19 @@ module Sequel
       # Add a composite primary key constraint
       def add_composite_primary_key(columns, opts)
         @operations << {:op => :add_constraint, :type => :primary_key, :columns => columns}.merge!(opts)
+        nil
       end
 
       # Add a composite foreign key constraint
       def add_composite_foreign_key(columns, table, opts)
         @operations << {:op => :add_constraint, :type => :foreign_key, :columns => columns, :table => table}.merge!(opts)
+        nil
       end
 
       # Drop a composite foreign key constraint
       def drop_composite_foreign_key(columns, opts)
-        @operations << {:op => :drop_constraint, :type => :foreign_key, :columns => columns}.merge!(opts)
+        @operations << opts.merge(:op => :drop_constraint, :type => :foreign_key, :columns => columns)
+        nil
       end
     end
   end