sequel 3.13.0 → 3.14.0

data/lib/sequel/database/dataset_defaults.rb

@@ -58,7 +58,11 @@ module Sequel
       end
     end
     
-    # Set the method to call on identifiers going into the database
+    # Set the method to call on identifiers going into the database:
+    #
+    #   DB[:items] # SELECT * FROM items
+    #   DB.identifier_input_method = :upcase
+    #   DB[:items] # SELECT * FROM ITEMS
     def identifier_input_method=(v)
       reset_schema_utility_dataset
       @identifier_input_method = v || ""
@@ -77,13 +81,21 @@ module Sequel
       end
     end
     
-    # Set the method to call on identifiers coming from the database
+    # Set the method to call on identifiers coming from the database:
+    #
+    #   DB[:items].first # {:id=>1, :name=>'foo'}
+    #   DB.identifier_output_method = :upcase
+    #   DB[:items].first # {:ID=>1, :NAME=>'foo'}
     def identifier_output_method=(v)
       reset_schema_utility_dataset
       @identifier_output_method = v || ""
     end
 
-    # Whether to quote identifiers (columns and tables) for this database
+    # Set whether to quote identifiers (columns and tables) for this database:
+    #
+    #   DB[:items] # SELECT * FROM items
+    #   DB.quote_identifiers = true
+    #   DB[:items] # SELECT * FROM "items"
     def quote_identifiers=(v)
       reset_schema_utility_dataset
       @quote_identifiers = v

data/lib/sequel/database/logging.rb

@@ -9,7 +9,7 @@ module Sequel
     # level instead of info level.
     attr_accessor :log_warn_duration
 
-    # Array of SQL loggers to use for this database
+    # Array of SQL loggers to use for this database.
     attr_accessor :loggers
     
     # Log a message at level info to all loggers.
@@ -33,7 +33,9 @@ module Sequel
       end
     end
 
-    # Remove any existing loggers and just use the given logger.
+    # Remove any existing loggers and just use the given logger:
+    #
+    #   DB.logger = Logger.new($stdout)
     def logger=(logger)
       @loggers = Array(logger)
     end
@@ -57,6 +59,5 @@ module Sequel
     def log_each(level, message)
       @loggers.each{|logger| logger.send(level, message)}
     end
-
   end
 end

data/lib/sequel/database/misc.rb

@@ -16,24 +16,24 @@ module Sequel
     end
     private_class_method :uri_to_options
     
-    # The options for this database
+    # The options hash for this database
     attr_reader :opts
     
     # Constructs a new instance of a database connection with the specified
     # options hash.
     #
-    # Sequel::Database is an abstract class that is not useful by itself.
+    # Accepts the following options:
+    # :default_schema :: The default schema to use, should generally be nil
+    # :disconnection_proc :: A proc used to disconnect the connection
+    # :identifier_input_method :: A string method symbol to call on identifiers going into the database
+    # :identifier_output_method :: A string method symbol to call on identifiers coming from the database
+    # :logger :: A specific logger to use
+    # :loggers :: An array of loggers to use
+    # :quote_identifiers :: Whether to quote identifiers
+    # :servers :: A hash specifying a server/shard specific options, keyed by shard symbol 
+    # :single_threaded :: Whether to use a single-threaded connection pool
     #
-    # Takes the following options:
-    # * :default_schema : The default schema to use, should generally be nil
-    # * :disconnection_proc: A proc used to disconnect the connection.
-    # * :identifier_input_method: A string method symbol to call on identifiers going into the database
-    # * :identifier_output_method: A string method symbol to call on identifiers coming from the database
-    # * :loggers : An array of loggers to use.
-    # * :quote_identifiers : Whether to quote identifiers
-    # * :single_threaded : Whether to use a single-threaded connection pool
-    #
-    # All options given are also passed to the ConnectionPool.  If a block
+    # All options given are also passed to the connection pool.  If a block
     # is given, it is used as the connection_proc for the ConnectionPool.
     def initialize(opts = {}, &block)
       @opts ||= opts
@@ -58,6 +58,9 @@ module Sequel
     end
     
     # Cast the given type to a literal type
+    #
+    #   DB.cast_type_literal(Float) # double precision
+    #   DB.cast_type_literal(:foo) # foo
     def cast_type_literal(type)
       type_literal(:type=>type)
     end
@@ -69,28 +72,33 @@ module Sequel
       "#<#{self.class}: #{(uri rescue opts).inspect}>" 
     end
 
-    # Proxy the literal call to the dataset, used for default values.
+    # Proxy the literal call to the dataset.
+    #
+    #   DB.literal(1) # 1
+    #   DB.literal(:a) # a
+    #   DB.literal('a') # 'a'
     def literal(v)
       schema_utility_dataset.literal(v)
     end
 
-    # Default serial primary key options.
+    # Default serial primary key options, used by the table creation
+    # code.
     def serial_primary_key_options
       {:primary_key => true, :type => Integer, :auto_increment => true}
     end
 
     # Whether the database and adapter support prepared transactions
-    # (two-phase commit), false by default
+    # (two-phase commit), false by default.
     def supports_prepared_transactions?
       false
     end
 
-    # Whether the database and adapter support savepoints, false by default
+    # Whether the database and adapter support savepoints, false by default.
     def supports_savepoints?
       false
     end
 
-    # Whether the database and adapter support transaction isolation levels, false by default
+    # Whether the database and adapter support transaction isolation levels, false by default.
     def supports_transaction_isolation_levels?
       false
     end
@@ -110,12 +118,17 @@ module Sequel
       end
     end
     
-    # Returns the URI identifying the database.
+    # Returns the URI identifying the database, which may not be the
+    # same as the URI used when connecting.
     # This method can raise an error if the database used options
-    # instead of a connection string.
+    # instead of a connection string, and will not include uri
+    # parameters.
+    #
+    #   Sequel.connect('postgres://localhost/db?user=billg').url
+    #   # => "postgres://billg@localhost/db"
     def uri
       uri = URI::Generic.new(
-        self.class.adapter_scheme.to_s,
+        adapter_scheme.to_s,
         nil,
         @opts[:host],
         @opts[:port],
@@ -203,7 +216,6 @@ module Sequel
 
     # Typecast the value to a DateTime or Time depending on Sequel.datetime_class
     def typecast_value_datetime(value)
-      raise(Sequel::InvalidValue, "invalid value for Datetime: #{value.inspect}") unless [DateTime, Date, Time, String, Hash].any?{|c| value.is_a?(c)}
       klass = Sequel.datetime_class
       if value.is_a?(Hash)
         klass.send(klass == Time ? :mktime : :new, *[:year, :month, :day, :hour, :minute, :second].map{|x| (value[x] || value[x.to_s]).to_i})

data/lib/sequel/database/query.rb

@@ -26,7 +26,7 @@ module Sequel
     MYSQL_TIMESTAMP_RE = /\ACURRENT_(?:DATE|TIMESTAMP)?\z/
     STRING_DEFAULT_RE = /\A'(.*)'\z/
 
-    # The prepared statement objects for this database, keyed by name
+    # The prepared statement object hash for this database, keyed by name symbol
     attr_reader :prepared_statements
     
     # The default transaction isolation level for this database,
@@ -44,6 +44,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.call(:sa) # SELECT * FROM items WHERE id = 1
     def call(ps_name, hash={})
       prepared_statements[ps_name].call(hash)
     end
@@ -55,7 +58,7 @@ module Sequel
     end
     
     # Method that should be used when submitting any DDL (Data Definition
-    # Language) SQL.  By default, calls execute_dui.
+    # Language) SQL, such as +create_table+.  By default, calls +execute_dui+.
     # This method should not be called directly by user code.
     def execute_ddl(sql, opts={}, &block)
       execute_dui(sql, opts, &block)
@@ -77,11 +80,9 @@ module Sequel
 
     # Returns a single value from the database, e.g.:
     #
-    #   # SELECT 1
-    #   DB.get(1) #=> 1 
-    #
-    #   # SELECT version()
-    #   DB.get(:version.sql_function) #=> ...
+    #   DB.get(1) # SELECT 1
+    #   # => 1
+    #   DB.get{version{}} # SELECT server_version()
     def get(*args, &block)
       dataset.get(*args, &block)
     end
@@ -92,13 +93,18 @@ module Sequel
     # depending on if the index is unique.
     #
     # Should not include the primary key index, functional indexes, or partial indexes.
+    #
+    #   DB.indexes(:artists)
+    #   # => {:artists_name_ukey=>{:columns=>[:name], :unique=>true}}
     def indexes(table, opts={})
       raise NotImplemented, "#indexes should be overridden by adapters"
     end
     
     # Runs the supplied SQL statement string on the database server. Returns nil.
     # Options:
-    # * :server - The server to run the SQL on.
+    # :server :: The server to run the SQL on.
+    #
+    #   DB.run("SET some_server_variable = 42")
     def run(sql, opts={})
       execute_ddl(sql, opts)
       nil
@@ -109,13 +115,40 @@ module Sequel
     # the first member being the column name, and the second member being a hash of column information.
     # Available options are:
     #
-    # * :reload - Get fresh information from the database, instead of using
-    #   cached information.  If table_name is blank, :reload should be used
-    #   unless you are sure that schema has not been called before with a
-    #   table_name, otherwise you may only getting the schemas for tables
-    #   that have been requested explicitly.
-    # * :schema - An explicit schema to use.  It may also be implicitly provided
-    #   via the table name.
+    # :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:
+    #
+    # :allow_null :: Whether NULL is an allowed value for the column.
+    # :db_type :: The database type for the column, as a database specific string.
+    # :default :: The database default for the column, as a database specific string.
+    # :primary_key :: Whether the columns is a primary key column.  If this column is not present,
+    #                 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.
+    # :type :: A symbol specifying the type, such as :integer or :string.
+    #
+    # Example:
+    #
+    #   DB.schema(:artists)
+    #   # [[:id,
+    #   #   {:type=>:integer,
+    #   #    :primary_key=>true,
+    #   #    :default=>"nextval('artist_id_seq'::regclass)",
+    #   #    :ruby_default=>nil,
+    #   #    :db_type=>"integer",
+    #   #    :allow_null=>false}],
+    #   #  [:name,
+    #   #   {:type=>:string,
+    #   #    :primary_key=>false,
+    #   #    :default=>nil,
+    #   #    :ruby_default=>nil,
+    #   #    :db_type=>"text",
+    #   #    :allow_null=>false}]]
     def schema(table, opts={})
       raise(Error, 'schema parsing is not implemented on this database') unless respond_to?(:schema_parse_table, true)
 
@@ -134,6 +167,8 @@ module Sequel
 
     # Returns true if a table with the given name exists.  This requires a query
     # to the database.
+    #
+    #   DB.table_exists?(:foo) # => false
     def table_exists?(name)
       begin 
         from(name).first
@@ -144,6 +179,8 @@ module Sequel
     end
     
     # Return all tables in the database as an array of symbols.
+    #
+    #   DB.tables # => [:albums, :artists]
     def tables(opts={})
       raise NotImplemented, "#tables should be overridden by adapters"
     end
@@ -155,13 +192,15 @@ module Sequel
     # The following options are respected:
     #
     # :isolation :: The transaction isolation level to use for this transaction,
-    #               should be :uncommitted, :committed, :repeatable, or :serializable.
+    #               should be :uncommitted, :committed, :repeatable, or :serializable,
+    #               used if given and the database/adapter supports customizable
+    #               transaction isolation levels.
     # :prepare :: A string to use as the transaction identifier for a
     #             prepared transaction (two-phase commit), if the database/adapter
-    #             supports prepared transactions
-    # :server :: The server to use for the transaction
+    #             supports prepared transactions.
+    # :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
+    #               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.
     def transaction(opts={}, &block)
@@ -175,7 +214,7 @@ module Sequel
     
     # Internal generic transaction method.  Any exception raised by the given
     # block will cause the transaction to be rolled back.  If the exception is
-    # not Sequel::Rollback, the error will be reraised. If no exception occurs
+    # not a Sequel::Rollback, the error will be reraised. If no exception occurs
     # inside the block, the transaction is commited.
     def _transaction(conn, opts={})
       begin
@@ -379,8 +418,8 @@ module Sequel
     end
 
     # Match the database's column type to a ruby type via a
-    # regular expression.  The following ruby types are supported:
-    # integer, string, date, datetime, boolean, and float.
+    # regular expression, and return the ruby type as a symbol
+    # such as :integer or :string.
     def schema_column_type(db_type)
       case db_type
       when /\Ainterval\z/io

data/lib/sequel/database/schema_generator.rb

@@ -19,13 +19,13 @@ module Sequel
       GENERIC_TYPES=[String, Integer, Fixnum, Bignum, Float, Numeric, BigDecimal,
       Date, DateTime, Time, File, TrueClass, FalseClass]
       
-      # Return the columns created by this generator
+      # Return the column hashes created by this generator
       attr_reader :columns
 
-      # Return the constraints created by this generator
+      # Return the constraint hashes created by this generator
       attr_reader :constraints
 
-      # Return the indexes created by this generator
+      # Return the index hashes created by this generator
       attr_reader :indexes
 
       # Set the database in which to create the table, and evaluate the block
@@ -50,14 +50,26 @@ module Sequel
         end
       end
       
-      # Add a unnamed constraint to the DDL, specified by the given block
-      # or args.
+      # Add an unnamed constraint to the DDL, specified by the given block
+      # or args:
+      #
+      #   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. 
       #
+      #   column :num, :integer
+      #   # num INTEGER
+      #
+      #   column :name, String, :null=>false, :default=>'a'
+      #   # name varchar(255) NOT NULL DEFAULT 'a'
+      #
+      #   inet :ip
+      #   # ip inet
+      #
       # You can also create columns via method missing, so the following are
       # equivalent:
       #
@@ -66,30 +78,32 @@ module Sequel
       #
       # 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.
-      # * :on_update - Specify the behavior of this column when being updated.
-      #   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.
-      #   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.
-      # * :deferrable - This ensure Referential Integrity will work even if
-      #   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.
+      # :default :: The default value for the column.
+      # :deferrable :: This ensure Referential Integrity will work even if
+      #                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.
+      # :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
+      #               (: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.
+      # :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]
@@ -97,12 +111,19 @@ module Sequel
       
       # Adds a named constraint (or unnamed if name is nil) to the DDL,
       # with the given block or args.
+      #
+      #   constraint(:blah, :num=>1..5) # CONSTRAINT blah CHECK num >= 1 AND num <= 5
+      #   check(:foo){num > 5} # CONSTRAINT foo CHECK num > 5
       def constraint(name, *args, &block)
         constraints << {:name => name, :type => :check, :check => block || args}
       end
       
       # Add a foreign key in the table that references another table to the DDL. 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)
       def foreign_key(name, table=nil, opts = {})
         opts = case table
         when Hash
@@ -131,31 +152,38 @@ module Sequel
       # 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)
+      # :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)
+      #
+      #   index :name
+      #   # CREATE INDEX table_name_index ON table (name)
+      #
+      #   index [:artist_id, :name]
+      #   # CREATE INDEX table_artist_id_name_index ON table (artist_id, name)
       def index(columns, opts = {})
         indexes << {:columns => Array(columns)}.merge(opts)
       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 to the DDL.  See +column+ for available
       # options.
       def method_missing(type, name = nil, opts = {})
         name ? column(name, type, opts) : super
       end
       
-      # Add primary key information to the DDL. Takes between one and three
-      # arguments. The last one is an options hash as for Generator#column.
-      # The first one distinguishes two modes: an array of existing column
-      # names adds a composite primary key constraint. A single symbol adds a
-      # new column of that name and makes it the primary key. In that case the
-      # optional middle argument denotes the type.
+      # Adds an autoincrementing primary key column or a primary key constraint to the DDL.
+      # To 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
+      # as the second argument.
+      # 
+      # 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.
       # 
       # Examples:
       #   primary_key(:id)
-      #   primary_key(:zip_code, :null => false)
       #   primary_key([:street_number, :house_number])
-      #   primary_key(:id, :string, :auto_increment => false)
       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})
@@ -170,7 +198,7 @@ module Sequel
         @primary_key
       end
 
-      # The name of the primary key for this table, if it has a primary key.
+      # The name of the primary key for this generator, if it has a primary key.
       def primary_key_name
         @primary_key[:name] if @primary_key
       end
@@ -181,6 +209,8 @@ module Sequel
       end
 
       # Add a unique constraint on the given columns to the DDL.
+      #
+      #   unique(:name) # UNIQUE (name)
       def unique(columns, opts = {})
         constraints << {:type => :unique, :columns => Array(columns)}.merge(opts)
       end
@@ -205,7 +235,7 @@ module Sequel
     # to instantiate directly.  Instances are created by Database#alter_table.
     # It is used to specify table alteration parameters.  It takes a Database
     # object and a block of operations to perform on the table, and
-    # gives the Database a table an array of operations, which the database uses to
+    # gives the Database an array of table altering operations, which the database uses to
     # alter a table's description.
     #
     # For more information on Sequel's support for schema modification, see
@@ -224,17 +254,25 @@ module Sequel
       
       # Add a column with the given name, type, and opts to the DDL for the table.
       # See Generator#column for the available options.
+      #
+      #   add_column(:name, String) # ADD COLUMN name varchar(255)
       def add_column(name, type, opts = {})
         @operations << {:op => :add_column, :name => name, :type => type}.merge(opts)
       end
       
       # Add a constraint with the given name and args to the DDL for the table.
       # See Generator#constraint.
+      #
+      #   add_constraint(:valid_name, :name.like('A%'))
+      #   # ADD CONSTRAINT valid_name CHECK (name LIKE 'A%')
       def add_constraint(name, *args, &block)
         @operations << {:op => :add_constraint, :name => name, :type => :check, :check => block || args}
       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)
       def add_unique_constraint(columns, opts = {})
         @operations << {:op => :add_constraint, :type => :unique, :columns => Array(columns)}.merge(opts)
       end
@@ -246,8 +284,11 @@ module Sequel
       # keys. In this case, it will assume the columns exists and will only add
       # the constraint.
       #
-      # NOTE: If you need to add a foreign key constraint to an existing column
+      # 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.
+      #
+      #   add_foreign_key(:artist_id, :table) # ADD COLUMN artist_id integer REFERENCES table
+      #   add_foreign_key([:name], :table) # ADD FOREIGN KEY (name) REFERENCES table
       def add_foreign_key(name, table, opts = {})
         return add_composite_foreign_key(name, table, opts) if name.is_a?(Array)
         add_column(name, Integer, {:table=>table}.merge(opts))
@@ -261,12 +302,18 @@ module Sequel
       
       # Add an index on the given columns to the DDL for the table.  See
       # Generator#index for available options.
+      #
+      #   add_index(:artist_id) # CREATE INDEX table_artist_id_index ON table (artist_id)
       def add_index(columns, opts = {})
         @operations << {:op => :add_index, :columns => Array(columns)}.merge(opts)
       end
       
       # Add a primary key to the DDL for the table.  See Generator#column
-      # for the available options.
+      # for the available options.  Like +add_foreign_key+, if you specify
+      # the column name as an array, it just creates a constraint:
+      #
+      #   add_primary_key(:id) # ADD COLUMN id serial PRIMARY KEY
+      #   add_primary_key([:artist_id, :name]) # ADD PRIMARY KEY (artist_id, name)
       def add_primary_key(name, opts = {})
         return add_composite_primary_key(name, opts) if name.is_a?(Array)
         opts = @db.serial_primary_key_options.merge(opts)
@@ -280,36 +327,52 @@ module Sequel
       end
       
       # 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}
       end
       
       # Remove a constraint from the DDL for the table.
+      #
+      #   drop_constraint(:unique_name) # DROP CONSTRAINT unique_name
       def drop_constraint(name)
         @operations << {:op => :drop_constraint, :name => name}
       end
       
       # Remove an index from the DDL for the table.
+      #
+      #   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
       def drop_index(columns, options={})
         @operations << {:op => :drop_index, :columns => Array(columns)}.merge(options)
       end
 
       # Modify a column's name in the DDL for the table.
+      #
+      #   rename_column(:name, :artist_name) # RENAME COLUMN name TO artist_name
       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.
+      #
+      #   set_column_default(:artist_name, 'a') # ALTER COLUMN artist_name SET DEFAULT 'a'
       def set_column_default(name, default)
         @operations << {:op => :set_column_default, :name => name, :default => default}
       end
 
       # 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)
       def set_column_type(name, type, opts={})
         @operations << {:op => :set_column_type, :name => name, :type => type}.merge(opts)
       end
       
       # Modify a column's NOT NULL constraint.
+      #
+      #   set_column_allow_null(:artist_name, false) # ALTER COLUMN artist_name SET NOT NULL
       def set_column_allow_null(name, allow_null)
         @operations << {:op => :set_column_null, :name => name, :null => allow_null}
       end