sequel 3.21.0 → 3.36.0

data/lib/sequel/database/query.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Database
     # ---------------------
-    # :section: Methods that execute queries and/or return results
+    # :section: 1 - Methods that execute queries and/or return results
     # This methods generally execute SQL code on the database server.
     # ---------------------
 
@@ -35,11 +35,19 @@ module Sequel
     # Database#transaction, as on MSSQL if affects all future transactions
     # on the same connection.
     attr_accessor :transaction_isolation_level
+
+    # Whether the schema should be cached for this database.  True by default
+    # for performance, can be set to false to always issue a database query to
+    # get the schema.
+    attr_accessor :cache_schema
     
     # Runs the supplied SQL statement string on the database server.
-    # Alias for run.
+    # Returns self so it can be safely chained:
+    #
+    #   DB << "UPDATE albums SET artist_id = NULL" << "DROP TABLE artists"
     def <<(sql)
       run(sql)
+      self
     end
     
     # Call the prepared statement with the given name with the given hash
@@ -47,8 +55,8 @@ module Sequel
     #
     #   DB[:items].filter(:id=>1).prepare(:first, :sa)
     #   DB.call(:sa) # SELECT * FROM items WHERE id = 1
-    def call(ps_name, hash={})
-      prepared_statements[ps_name].call(hash)
+    def call(ps_name, hash={}, &block)
+      prepared_statement(ps_name).call(hash, &block)
     end
     
     # Executes the given SQL on the database. This method should be overridden in descendants.
@@ -78,16 +86,34 @@ module Sequel
       execute_dui(sql, opts, &block)
     end
 
+    # Returns an array of hashes containing foreign key information from the
+    # table.  Each hash will contain at least the following fields:
+    #
+    # :columns :: An array of columns in the given table
+    # :table :: The table referenced by the columns
+    # :key :: An array of columns referenced (in the table specified by :table),
+    #         but can be nil on certain adapters if the primary key is referenced.
+    #
+    # The hash may also contain entries for:
+    #
+    # :deferrable :: Whether the constraint is deferrable
+    # :name :: The name of the constraint
+    # :on_delete :: The action to take ON DELETE
+    # :on_update :: The action to take ON UPDATE
+    def foreign_key_list(table, opts={})
+      raise NotImplemented, "#foreign_key_list should be overridden by adapters"
+    end
+    
     # Returns a single value from the database, e.g.:
     #
     #   DB.get(1) # SELECT 1
     #   # => 1
-    #   DB.get{version{}} # SELECT server_version()
+    #   DB.get{server_version{}} # SELECT server_version()
     def get(*args, &block)
       dataset.get(*args, &block)
     end
     
-    # Return a hash containing index information. Hash keys are index name symbols.
+    # Return a hash containing index information for the table. Hash keys are index name symbols.
     # Values are subhashes with two keys, :columns and :unique.  The value of :columns
     # is an array of symbols of column names.  The value of :unique is true or false
     # depending on if the index is unique.
@@ -110,17 +136,17 @@ module Sequel
       nil
     end
     
-    # Parse the schema from the database.
     # Returns the schema for the given table as an array with all members being arrays of length 2,
     # the first member being the column name, and the second member being a hash of column information.
+    # The table argument can also be a dataset, as long as it only has one table.
     # Available options are:
     #
     # :reload :: Ignore any cached results, and get fresh information from the database.
     # :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 at least contain the
-    # following columns:
+    # If schema parsing is supported by the database, the column information should hash at least contain the
+    # following entries:
     #
     # :allow_null :: Whether NULL is an allowed value for the column.
     # :db_type :: The database type for the column, as a database specific string.
@@ -129,7 +155,8 @@ module Sequel
     #                 it means that primary key information is unavailable, not that the column
     #                 is not a primary key.
     # :ruby_default :: The database default for the column, as a ruby object.  In many cases, complex
-    #                  database defaults cannot be parsed into ruby objects.
+    #                  database defaults cannot be parsed into ruby objects, in which case nil will be
+    #                  used as the value.
     # :type :: A symbol specifying the type, such as :integer or :string.
     #
     # Example:
@@ -152,32 +179,48 @@ module Sequel
     def schema(table, opts={})
       raise(Error, 'schema parsing is not implemented on this database') unless respond_to?(:schema_parse_table, true)
 
-      sch, table_name = schema_and_table(table)
-      quoted_name = quote_schema_table(table)
-      opts = opts.merge(:schema=>sch) if sch && !opts.include?(:schema)
+      opts = opts.dup
+      if table.is_a?(Dataset)
+        o = table.opts
+        from = o[:from]
+        raise(Error, "can only parse the schema for a dataset with a single from table") unless from && from.length == 1 && !o.include?(:join) && !o.include?(:sql)
+        tab = table.first_source_table
+        sch, table_name = schema_and_table(tab)
+        quoted_name = table.literal(tab)
+        opts[:dataset] = table
+      else
+        sch, table_name = schema_and_table(table)
+        quoted_name = quote_schema_table(table)
+      end
+      opts[:schema] = sch if sch && !opts.include?(:schema)
 
-      @schemas.delete(quoted_name) if opts[:reload]
-      return @schemas[quoted_name] if @schemas[quoted_name]
+      Sequel.synchronize{@schemas.delete(quoted_name)} if opts[:reload]
+      return Sequel.synchronize{@schemas[quoted_name]} if @schemas[quoted_name]
 
       cols = schema_parse_table(table_name, opts)
       raise(Error, 'schema parsing returned no columns, table probably doesn\'t exist') if cols.nil? || cols.empty?
       cols.each{|_,c| c[:ruby_default] = column_schema_to_ruby_default(c[:default], c[:type])}
-      @schemas[quoted_name] = cols
+      Sequel.synchronize{@schemas[quoted_name] = cols} if cache_schema
+      cols
     end
 
     # Returns true if a table with the given name exists.  This requires a query
     # to the database.
     #
     #   DB.table_exists?(:foo) # => false
+    #   # SELECT NULL FROM foo LIMIT 1
+    #
+    # Note that since this does a SELECT from the table, it can give false negatives
+    # if you don't have permission to SELECT from the table.
     def table_exists?(name)
-      begin 
-        from(name).first
-        true
-      rescue
-        false
-      end
+      sch, table_name = schema_and_table(name)
+      name = SQL::QualifiedIdentifier.new(sch, table_name) if sch
+      _table_exists?(from(name))
+      true
+    rescue DatabaseError
+      false
     end
-    
+
     # Return all tables in the database as an array of symbols.
     #
     #   DB.tables # => [:albums, :artists]
@@ -189,7 +232,7 @@ module Sequel
     # either all statements are successful or none of the statements are
     # successful.  Note that MySQL MyISAM tabels do not support transactions.
     #
-    # The following options are respected:
+    # The following general options are respected:
     #
     # :isolation :: The transaction isolation level to use for this transaction,
     #               should be :uncommitted, :committed, :repeatable, or :serializable,
@@ -198,11 +241,22 @@ module Sequel
     # :prepare :: A string to use as the transaction identifier for a
     #             prepared transaction (two-phase commit), if the database/adapter
     #             supports prepared transactions.
+    # :rollback :: Can the set to :reraise to reraise any Sequel::Rollback exceptions
+    #              raised, or :always to always rollback even if no exceptions occur
+    #              (useful for testing).
     # :server :: The server to use for the transaction.
     # :savepoint :: Whether to create a new savepoint for this transaction,
     #               only respected if the database/adapter supports savepoints.  By
     #               default Sequel will reuse an existing transaction, so if you want to
     #               use a savepoint you must use this option.
+    #
+    # PostgreSQL specific options:
+    #
+    # :deferrable :: (9.1+) If present, set to DEFERRABLE if true or NOT DEFERRABLE if false.
+    # :read_only :: If present, set to READ ONLY if true or READ WRITE if false.
+    # :synchronous :: if non-nil, set synchronous_commit
+    #                 appropriately.  Valid values true, :on, false, :off, :local (9.1+),
+    #                 and :remote_write (9.2+).
     def transaction(opts={}, &block)
       synchronize(opts[:server]) do |conn|
         return yield(conn) if already_in_transaction?(conn, opts)
@@ -210,47 +264,99 @@ module Sequel
       end
     end
     
+    # Return all views in the database as an array of symbols.
+    #
+    #   DB.views # => [:gold_albums, :artists_with_many_albums]
+    def views(opts={})
+      raise NotImplemented, "#views should be overridden by adapters"
+    end
+    
     private
     
+    # Should raise an error if the table doesn't not exist,
+    # and not raise an error if the table does exist.
+    def _table_exists?(ds)
+      ds.get(Sequel::NULL)
+    end
+    
     # Internal generic transaction method.  Any exception raised by the given
     # block will cause the transaction to be rolled back.  If the exception is
     # not a Sequel::Rollback, the error will be reraised. If no exception occurs
     # inside the block, the transaction is commited.
     def _transaction(conn, opts={})
+      rollback = opts[:rollback]
       begin
-        add_transaction
-        t = begin_transaction(conn, opts)
-        yield(conn)
+        add_transaction(conn, opts)
+        begin_transaction(conn, opts)
+        if rollback == :always
+          begin
+            yield(conn)
+          rescue Exception => e1
+            raise e1
+          ensure
+            raise ::Sequel::Rollback unless e1
+          end
+        else
+          yield(conn)
+        end
       rescue Exception => e
-        rollback_transaction(t, opts) if t
-        transaction_error(e)
+        begin
+          rollback_transaction(conn, opts)
+        rescue Exception => e3
+          raise_error(e3, :classes=>database_error_classes, :conn=>conn)
+        end
+        transaction_error(e, :conn=>conn, :rollback=>rollback)
       ensure
         begin
-          commit_transaction(t, opts) unless e
-        rescue Exception => e
-          raise_error(e, :classes=>database_error_classes)
+          committed = commit_or_rollback_transaction(e, conn, opts)
+        rescue Exception => e2
+          raise_error(e2, :classes=>database_error_classes, :conn=>conn)
         ensure
-          remove_transaction(t)
+          remove_transaction(conn, committed)
         end
       end
     end
-    
+
+    # Synchronize access to the current transactions, returning the hash
+    # of options for the current transaction (if any)
+    def _trans(conn)
+      Sequel.synchronize{@transactions[conn]}
+    end
+
     # Add the current thread to the list of active transactions
-    def add_transaction
-      th = Thread.current
+    def add_transaction(conn, opts)
       if supports_savepoints?
-        unless @transactions.include?(th)
-          th[:sequel_transaction_depth] = 0
-          @transactions << th
+        unless _trans(conn)
+          if (prep = opts[:prepare]) && supports_prepared_transactions?
+            Sequel.synchronize{@transactions[conn] = {:savepoint_level=>0, :prepare=>prep}}
+          else
+            Sequel.synchronize{@transactions[conn] = {:savepoint_level=>0}}
+          end
         end
+      elsif (prep = opts[:prepare]) && supports_prepared_transactions?
+        Sequel.synchronize{@transactions[conn] = {:prepare => prep}}
       else
-        @transactions << th
+        Sequel.synchronize{@transactions[conn] = {}}
       end
     end    
 
+    # Call all stored after_commit blocks for the given transaction
+    def after_transaction_commit(conn)
+      if ary = _trans(conn)[:after_commit]
+        ary.each{|b| b.call}
+      end
+    end
+
+    # Call all stored after_rollback blocks for the given transaction
+    def after_transaction_rollback(conn)
+      if ary = _trans(conn)[:after_rollback]
+        ary.each{|b| b.call}
+      end
+    end
+
     # Whether the current thread/connection is already inside a transaction
     def already_in_transaction?(conn, opts)
-      @transactions.include?(Thread.current) && (!supports_savepoints? || !opts[:savepoint])
+      _trans(conn) && (!supports_savepoints? || !opts[:savepoint])
     end
     
     # SQL to start a new savepoint
@@ -267,17 +373,16 @@ module Sequel
     # Start a new database transaction or a new savepoint on the given connection.
     def begin_transaction(conn, opts={})
       if supports_savepoints?
-        th = Thread.current
-        if (depth = th[:sequel_transaction_depth]) > 0
+        th = _trans(conn)
+        if (depth = th[:savepoint_level]) > 0
           log_connection_execute(conn, begin_savepoint_sql(depth))
         else
           begin_new_transaction(conn, opts)
         end
-        th[:sequel_transaction_depth] += 1
+        th[:savepoint_level] += 1
       else
         begin_new_transaction(conn, opts)
       end
-      conn
     end
     
     # SQL to BEGIN a transaction.
@@ -335,6 +440,38 @@ module Sequel
       end
     end
    
+    if (! defined?(RUBY_ENGINE) or RUBY_ENGINE == 'ruby' or RUBY_ENGINE == 'rbx') and RUBY_VERSION < '1.9'
+      # Whether to commit the current transaction. On ruby 1.8 and rubinius,
+      # Thread.current.status is checked because Thread#kill skips rescue
+      # blocks (so exception would be nil), but the transaction should
+      # still be rolled back.
+      def commit_or_rollback_transaction(exception, conn, opts)
+        if exception
+          false
+        else
+          if Thread.current.status == 'aborting'
+            rollback_transaction(conn, opts)
+            false
+          else
+            commit_transaction(conn, opts)
+            true
+          end
+        end
+      end
+    else
+      # Whether to commit the current transaction.  On ruby 1.9 and JRuby,
+      # transactions will be committed if Thread#kill is used on an thread
+      # that has a transaction open, and there isn't a work around.
+      def commit_or_rollback_transaction(exception, conn, opts)
+        if exception
+          false
+        else
+          commit_transaction(conn, opts)
+          true
+        end
+      end
+    end
+    
     # SQL to commit a savepoint
     def commit_savepoint_sql(depth)
       SQL_RELEASE_SAVEPOINT % depth
@@ -343,7 +480,7 @@ module Sequel
     # Commit the active transaction on the connection
     def commit_transaction(conn, opts={})
       if supports_savepoints?
-        depth = Thread.current[:sequel_transaction_depth]
+        depth = _trans(conn)[:savepoint_level]
         log_connection_execute(conn, depth > 1 ? commit_savepoint_sql(depth-1) : commit_transaction_sql)
       else
         log_connection_execute(conn, commit_transaction_sql)
@@ -364,8 +501,8 @@ module Sequel
     # Return a Method object for the dataset's output_identifier_method.
     # Used in metadata parsing to make sure the returned information is in the
     # correct format.
-    def input_identifier_meth
-      dataset.method(:input_identifier)
+    def input_identifier_meth(ds=nil)
+      (ds || dataset).method(:input_identifier)
     end
     
     # Return a dataset that uses the default identifier input and output methods
@@ -382,24 +519,28 @@ module Sequel
     # Return a Method object for the dataset's output_identifier_method.
     # Used in metadata parsing to make sure the returned information is in the
     # correct format.
-    def output_identifier_meth
-      dataset.method(:output_identifier)
+    def output_identifier_meth(ds=nil)
+      (ds || dataset).method(:output_identifier)
     end
 
-    # SQL to ROLLBACK a transaction.
-    def rollback_transaction_sql
-      SQL_ROLLBACK
-    end
-    
     # Remove the cached schema for the given schema name
     def remove_cached_schema(table)
       @schemas.delete(quote_schema_table(table)) if @schemas
     end
     
     # Remove the current thread from the list of active transactions
-    def remove_transaction(conn)
-      th = Thread.current
-      @transactions.delete(th) if !supports_savepoints? || ((th[:sequel_transaction_depth] -= 1) <= 0)
+    def remove_transaction(conn, committed)
+      if !supports_savepoints? || ((_trans(conn)[:savepoint_level] -= 1) <= 0)
+        begin
+          if committed
+            after_transaction_commit(conn)
+          else
+            after_transaction_rollback(conn)
+          end
+        ensure
+          Sequel.synchronize{@transactions.delete(conn)}
+        end
+      end
     end
 
     # SQL to rollback to a savepoint
@@ -410,13 +551,18 @@ module Sequel
     # Rollback the active transaction on the connection
     def rollback_transaction(conn, opts={})
       if supports_savepoints?
-        depth = Thread.current[:sequel_transaction_depth]
+        depth = _trans(conn)[:savepoint_level]
         log_connection_execute(conn, depth > 1 ? rollback_savepoint_sql(depth-1) : rollback_transaction_sql)
       else
         log_connection_execute(conn, rollback_transaction_sql)
       end
     end
 
+    # SQL to ROLLBACK a transaction.
+    def rollback_transaction_sql
+      SQL_ROLLBACK
+    end
+    
     # Match the database's column type to a ruby type via a
     # regular expression, and return the ruby type as a symbol
     # such as :integer or :string.
@@ -434,13 +580,13 @@ module Sequel
         :datetime
       when /\Atime( with(out)? time zone)?\z/io
         :time
-      when /\A(boolean|bit)\z/io
+      when /\A(bool(ean)?)\z/io
         :boolean
       when /\A(real|float|double( precision)?)\z/io
         :float
-      when /\A(?:(?:(?:num(?:ber|eric)?|decimal)(?:\(\d+,\s*(\d+)\))?)|(?:small)?money)\z/io
-        $1 && $1 == '0' ? :integer : :decimal
-      when /bytea|blob|image|(var)?binary/io
+      when /\A(?:(?:(?:num(?:ber|eric)?|decimal)(?:\(\d+,\s*(\d+|false|true)\))?)|(?:small)?money)\z/io
+        $1 && ['0', 'false'].include?($1) ? :integer : :decimal
+      when /bytea|[bc]lob|image|(var)?binary/io
         :blob
       when /\Aenum/io
         :enum
@@ -460,8 +606,12 @@ module Sequel
     end
 
     # Raise a database error unless the exception is an Rollback.
-    def transaction_error(e)
-      raise_error(e, :classes=>database_error_classes) unless e.is_a?(Rollback)
+    def transaction_error(e, opts={})
+      if e.is_a?(Rollback)
+        raise e if opts[:rollback] == :reraise
+      else
+        raise_error(e, opts.merge(:classes=>database_error_classes))
+      end
     end
   end
 end

data/lib/sequel/database/schema_generator.rb

@@ -83,30 +83,28 @@ module Sequel
       #                reference table will use for its foreign key a value that does not
       #                exists(yet) on referenced table. Basically it adds
       #                DEFERRABLE INITIALLY DEFERRED on key creation.
-      # :index :: Create an index on this column.
+      # :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
       #         that this column references.  Unnecessary if this column
-      #         references the primary key of the associated table.
+      #         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.
       # :on_delete :: Specify the behavior of this column when being deleted
-      #               (:restrict, cascade, :set_null, :set_default, :no_action).
+      #               (: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).
+      #               (: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.
-      # :size :: The size of the column, generally used with string
-      #          columns to specify the maximum number of characters the column will hold.
-      #          An array of two integers can be provided to set the size and the
-      #          precision, respectively, of decimal columns.
       # :unique :: Mark the column as 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]
+        if index_opts = opts[:index]
+          index(name, index_opts.is_a?(Hash) ? index_opts : {})
+        end
       end
       
       # Adds a named constraint (or unnamed if name is nil) to the DDL,
@@ -124,6 +122,13 @@ module Sequel
       #   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)
+      #
+      # If you want a foreign key constraint without adding a column (usually because it is a
+      # 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)
+      #   # ADD CONSTRAINT artist_fk FOREIGN KEY (artist_name, artist_location) REFERENCES artists
       def foreign_key(name, table=nil, opts = {})
         opts = case table
         when Hash
@@ -140,6 +145,12 @@ module Sequel
       end
 
       # Add a full text index on the given columns to the DDL.
+      #
+      # PostgreSQL specific options:
+      # :language :: Set a language to use for the index (default: simple).
+      #
+      # Microsoft SQL Server specific options:
+      # :key_index :: The KEY INDEX to use for the full text index.
       def full_text_index(columns, opts = {})
         index(columns, opts.merge(:type => :full_text))
       end
@@ -150,12 +161,26 @@ module Sequel
       end
       
       # Add an index on the given column(s) with the given options to the DDL.
-      # The available options are:
+      # General options:
       #
+      # :name :: The name to use for the index. If not given, a default name
+      #          based on the table and columns is used.
       # :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)
       #
+      # PostgreSQL specific options:
+      #
+      # :concurrently :: Create the index concurrently, so it doesn't block
+      #                  operations on the table while the index is being
+      #                  built.
+      # :op_class :: Use a specific operator class in the index.
+      #
+      # Microsoft SQL Server specific options:
+      #
+      # :include :: Include additional column values in the index, without
+      #             actually indexing on those values.
+      #
       #   index :name
       #   # CREATE INDEX table_name_index ON table (name)
       #
@@ -281,8 +306,8 @@ module Sequel
       # to the DDL for the table.  See Generator#column for the available options.
       #
       # You can also pass an array of column names for creating composite foreign
-      # keys. In this case, it will assume the columns exists and will only add
-      # the constraint.
+      # keys. In this case, it will assume the columns exist and will only add
+      # the constraint.  You can provide a :name option to name the constraint.
       #
       # NOTE: If you need to add a foreign key constraint to a single existing column
       # use the composite key syntax even if it is only one column.
@@ -329,18 +354,33 @@ module Sequel
       # Remove a column from the DDL for the table.
       #
       #   drop_column(:artist_id) # DROP COLUMN artist_id
-      def drop_column(name)
-        @operations << {:op => :drop_column, :name => name}
+      #   drop_column(:artist_id, :cascade=>true) # DROP COLUMN artist_id CASCADE
+      def drop_column(name, opts={})
+        @operations << {:op => :drop_column, :name => name}.merge(opts)
       end
       
-      # Remove a constraint from the DDL for the table.
+      # Remove a constraint from the DDL for the table. 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
-      def drop_constraint(name)
-        @operations << {:op => :drop_constraint, :name => name}
+      #   drop_constraint(:unique_name, :cascade=>true) # DROP CONSTRAINT unique_name CASCADE
+      def drop_constraint(name, opts={})
+        @operations << {:op => :drop_constraint, :name => name}.merge(opts)
       end
       
-      # Remove an index from the DDL for the table.
+      # Remove an index from the DDL for 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.
+      #
+      # PostgreSQL specific options:
+      #
+      # :cascade :: Cascade the index drop to dependent objects.
+      # :concurrently :: Drop the index using CONCURRENTLY, which doesn't block
+      #                  operations on the table.  Supported in PostgreSQL 9.2+.
+      # :if_exists :: Only drop the index if it already exists.
       #
       #   drop_index(:artist_id) # DROP INDEX table_artist_id_index
       #   drop_index([:a, :b]) # DROP INDEX table_a_b_index
@@ -366,6 +406,10 @@ module Sequel
       # Modify a column's type in the DDL for the table.
       #
       #   set_column_type(:artist_name, 'char(10)') # ALTER COLUMN artist_name TYPE char(10)
+      #
+      # PostgreSQL specific options:
+      #
+      # :using :: Add a USING clause that specifies how to convert existing values to new values.
       def set_column_type(name, type, opts={})
         @operations << {:op => :set_column_type, :name => name, :type => type}.merge(opts)
       end