sequel 3.21.0 → 3.36.0

data/lib/sequel/database/schema_methods.rb

@@ -1,27 +1,25 @@
 module Sequel
   class Database
     # ---------------------
-    # :section: Methods that modify the database schema
+    # :section: 2 - Methods that modify the database schema
     # These methods execute code on the database that modifies the database's schema.
     # ---------------------
 
     AUTOINCREMENT = 'AUTOINCREMENT'.freeze
-    CASCADE = 'CASCADE'.freeze
     COMMA_SEPARATOR = ', '.freeze
-    NO_ACTION = 'NO ACTION'.freeze
     NOT_NULL = ' NOT NULL'.freeze
     NULL = ' NULL'.freeze
     PRIMARY_KEY = ' PRIMARY KEY'.freeze
-    RESTRICT = 'RESTRICT'.freeze
-    SET_DEFAULT = 'SET DEFAULT'.freeze
-    SET_NULL = 'SET NULL'.freeze
     TEMPORARY = 'TEMPORARY '.freeze
     UNDERSCORE = '_'.freeze
     UNIQUE = ' UNIQUE'.freeze
     UNSIGNED = ' UNSIGNED'.freeze
 
     # The order of column modifiers to use when defining a column.
-    COLUMN_DEFINITION_ORDER = [:default, :null, :unique, :primary_key, :auto_increment, :references]
+    COLUMN_DEFINITION_ORDER = [:collate, :default, :null, :unique, :primary_key, :auto_increment, :references]
+
+    # The default options for join table columns.
+    DEFAULT_JOIN_TABLE_COLUMN_OPTIONS = {:null=>false}
 
     # Adds a column to the specified table. This method expects a column name,
     # a datatype and optionally a hash with additional constraints and options:
@@ -29,7 +27,7 @@ module Sequel
     #   DB.add_column :items, :name, :text, :unique => true, :null => false
     #   DB.add_column :items, :category, :text, :default => 'ruby'
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def add_column(table, *args)
       alter_table(table) {add_column(*args)}
     end
@@ -40,9 +38,9 @@ module Sequel
     #   DB.add_index :posts, [:author, :title], :unique => true
     #
     # Options:
-    # * :ignore_errors - Ignore any DatabaseErrors that are raised
+    # :ignore_errors :: Ignore any DatabaseErrors that are raised
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def add_index(table, columns, options={})
       e = options[:ignore_errors]
       begin
@@ -65,17 +63,65 @@ module Sequel
     #   end
     #
     # Note that +add_column+ accepts all the options available for column
-    # definitions using create_table, and +add_index+ accepts all the options
+    # definitions using <tt>create_table</tt>, and +add_index+ accepts all the options
     # available for index definition.
     #
-    # See Schema::AlterTableGenerator and the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
+    # See <tt>Schema::AlterTableGenerator</tt> and the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
     def alter_table(name, generator=nil, &block)
       generator ||= Schema::AlterTableGenerator.new(self, &block)
-      alter_table_sql_list(name, generator.operations).flatten.each {|sql| execute_ddl(sql)}
       remove_cached_schema(name)
+      apply_alter_table(name, generator.operations)
       nil
     end
-    
+
+    # Create a join table using a hash of foreign keys to referenced
+    # table names.  Example:
+    #
+    #   create_join_table(:cat_id=>:cats, :dog_id=>:dogs)
+    #   # CREATE TABLE cats_dogs (
+    #   #  cat_id integer NOT NULL REFERENCES cats,
+    #   #  dog_id integer NOT NULL REFERENCES dogs,
+    #   #  PRIMARY KEY (cat_id, dog_id)
+    #   # )
+    #   # CREATE INDEX cats_dogs_dog_id_cat_id_index ON cats_dogs(dog_id, cat_id)
+    #
+    # The primary key and index are used so that almost all operations
+    # on the table can benefit from one of the two indexes, and the primary
+    # key ensures that entries in the table are unique, which is the typical
+    # desire for a join table.
+    #
+    # You can provide column options by making the values in the hash
+    # be option hashes, so long as the option hashes have a :table
+    # entry giving the table referenced:
+    #
+    #   create_join_table(:cat_id=>{:table=>:cats, :type=>Bignum}, :dog_id=>:dogs)
+    #   
+    # You can provide a second argument which is a table options hash:
+    #
+    #   create_join_table({:cat_id=>:cats, :dog_id=>:dogs}, :temp=>true)
+    #
+    # Some table options are handled specially:
+    #
+    # :index_options :: The options to pass to the index
+    # :name :: The name of the table to create
+    # :no_index :: Set to true not to create the second index.
+    # :no_primary_key :: Set to true to not create the primary key.
+    def create_join_table(hash, options={})
+      keys = hash.keys.sort_by{|k| k.to_s}
+      create_table(join_table_name(hash, options), options) do
+        keys.each do |key|
+          v = hash[key]
+          unless v.is_a?(Hash)
+            v = {:table=>v}
+          end
+          v = DEFAULT_JOIN_TABLE_COLUMN_OPTIONS.merge(v)
+          foreign_key(key, v)
+        end
+        primary_key(keys) unless options[:no_primary_key]
+        index(keys.reverse, options[:index_options] || {}) unless options[:no_index]
+      end
+    end
+
     # Creates a table with the columns given in the provided block:
     #
     #   DB.create_table :posts do
@@ -85,33 +131,55 @@ module Sequel
     #     index :title
     #   end
     #
-    # Options:
-    # :temp :: Create the table as a temporary table.
+    # General options:
+    # :as :: Create the table using the value, which should be either a
+    #        dataset or a literal SQL string.  If this option is used,
+    #        a block should not be given to the method.
     # :ignore_index_errors :: Ignore any errors when creating indexes.
+    # :temp :: Create the table as a temporary table.
+    #
+    # MySQL specific options:
+    # :charset :: The character set to use for the table.
+    # :collate :: The collation to use for the table.
+    # :engine :: The table engine to use for the table.
     #
-    # See Schema::Generator and the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
+    # See <tt>Schema::Generator</tt> and the {"Schema Modification" guide}[link:files/doc/schema_modification_rdoc.html].
     def create_table(name, options={}, &block)
       remove_cached_schema(name)
       options = {:generator=>options} if options.is_a?(Schema::Generator)
-      generator = options[:generator] || Schema::Generator.new(self, &block)
-      create_table_from_generator(name, generator, options)
-      create_table_indexes_from_generator(name, generator, options)
-      nil
+      if sql = options[:as]
+        raise(Error, "can't provide both :as option and block to create_table") if block
+        create_table_as(name, sql, options)
+      else
+        generator = options[:generator] || Schema::Generator.new(self, &block)
+        create_table_from_generator(name, generator, options)
+        create_table_indexes_from_generator(name, generator, options)
+        nil
+      end
     end
-    
-    # Forcibly creates a table, attempting to drop it unconditionally (and catching any errors), then creating it.
+
+    # Forcibly create a table, attempting to drop it if it already exists, then creating it.
     # 
     #   DB.create_table!(:a){Integer :a} 
-    #   # DROP TABLE a
+    #   # SELECT NULL FROM a LIMIT 1 -- check existence
+    #   # DROP TABLE a -- drop table if already exists
     #   # CREATE TABLE a (a integer)
     def create_table!(name, options={}, &block)
-      drop_table(name) rescue nil
+      drop_table?(name)
       create_table(name, options, &block)
     end
     
-    # Creates the table unless the table already exists
+    # Creates the table unless the table already exists.
+    # 
+    #   DB.create_table?(:a){Integer :a} 
+    #   # SELECT NULL FROM a LIMIT 1 -- check existence
+    #   # CREATE TABLE a (a integer) -- if it doesn't already exist
     def create_table?(name, options={}, &block)
-      create_table(name, options, &block) unless table_exists?(name)
+      if supports_create_table_if_not_exists?
+        create_table(name, options.merge(:if_not_exists=>true), &block)
+      elsif !table_exists?(name)
+        create_table(name, options, &block)
+      end
     end
     
     # Creates a view, replacing it if it already exists:
@@ -138,7 +206,7 @@ module Sequel
     #
     #   DB.drop_column :items, :category
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def drop_column(table, *args)
       alter_table(table) {drop_column(*args)}
     end
@@ -148,28 +216,63 @@ module Sequel
     #   DB.drop_index :posts, :title
     #   DB.drop_index :posts, [:author, :title]
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def drop_index(table, columns, options={})
       alter_table(table){drop_index(columns, options)}
     end
+
+    # Drop the join table that would have been created with the
+    # same arguments to create_join_table:
+    #
+    #   drop_join_table(:cat_id=>:cats, :dog_id=>:dogs)
+    #   # DROP TABLE cats_dogs
+    def drop_join_table(hash, options={})
+      drop_table(join_table_name(hash, options), options)
+    end
     
     # Drops one or more tables corresponding to the given names:
     #
+    #   DB.drop_table(:posts) # DROP TABLE posts
     #   DB.drop_table(:posts, :comments)
+    #   DB.drop_table(:posts, :comments, :cascade=>true)
     def drop_table(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
       names.each do |n|
-        execute_ddl(drop_table_sql(n))
+        execute_ddl(drop_table_sql(n, options))
         remove_cached_schema(n)
       end
       nil
     end
     
+    # Drops the table if it already exists.  If it doesn't exist,
+    # does nothing.
+    # 
+    #   DB.drop_table?(:a)
+    #   # SELECT NULL FROM a LIMIT 1 -- check existence
+    #   # DROP TABLE a -- if it already exists
+    def drop_table?(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
+      if supports_drop_table_if_exists?
+        options = options.merge(:if_exists=>true)
+        names.each do |name|
+          drop_table(name, options)
+        end
+      else
+        names.each do |name|
+          drop_table(name, options) if table_exists?(name)
+        end
+      end
+    end
+    
     # Drops one or more views corresponding to the given names:
     #
     #   DB.drop_view(:cheap_items)
+    #   DB.drop_view(:cheap_items, :pricey_items)
+    #   DB.drop_view(:cheap_items, :pricey_items, :cascade=>true)
     def drop_view(*names)
+      options = names.last.is_a?(Hash) ? names.pop : {}
       names.each do |n|
-        execute_ddl("DROP VIEW #{quote_schema_table(n)}")
+        execute_ddl(drop_view_sql(n, options))
         remove_cached_schema(n)
       end
       nil
@@ -191,7 +294,7 @@ module Sequel
     #
     #   DB.rename_column :items, :cntr, :counter
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def rename_column(table, *args)
       alter_table(table) {rename_column(*args)}
     end
@@ -200,7 +303,7 @@ module Sequel
     #
     #   DB.set_column_default :items, :category, 'perl!'
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def set_column_default(table, *args)
       alter_table(table) {set_column_default(*args)}
     end
@@ -209,13 +312,18 @@ module Sequel
     #
     #   DB.set_column_type :items, :price, :float
     #
-    # See alter_table.
+    # See <tt>alter_table</tt>.
     def set_column_type(table, *args)
       alter_table(table) {set_column_type(*args)}
     end
 
     private
 
+    # Apply the changes in the given alter table ops to the table given by name.
+    def apply_alter_table(name, ops)
+      alter_table_sql_list(name, ops).flatten.each{|sql| execute_ddl(sql)}
+    end
+    
     # The SQL to execute to modify the DDL for the given table name.  op
     # should be one of the operations returned by the AlterTableGenerator.
     def alter_table_sql(table, op)
@@ -224,7 +332,7 @@ module Sequel
       when :add_column
         "ADD COLUMN #{column_definition_sql(op)}"
       when :drop_column
-        "DROP COLUMN #{quoted_name}"
+        "DROP COLUMN #{quoted_name}#{' CASCADE' if op[:cascade]}"
       when :rename_column
         "RENAME COLUMN #{quoted_name} TO #{quote_identifier(op[:new_name])}"
       when :set_column_type
@@ -240,7 +348,7 @@ module Sequel
       when :add_constraint
         "ADD #{constraint_definition_sql(op)}"
       when :drop_constraint
-        "DROP CONSTRAINT #{quoted_name}"
+        "DROP CONSTRAINT #{quoted_name}#{' CASCADE' if op[:cascade]}"
       else
         raise Error, "Unsupported ALTER TABLE operation"
       end
@@ -275,7 +383,12 @@ module Sequel
     def column_definition_auto_increment_sql(sql, column)
       sql << " #{auto_increment_sql}" if column[:auto_increment]
     end
-    
+
+    # Add collate SQL fragment to column creation SQL.
+    def column_definition_collate_sql(sql, column)
+      sql << " COLLATE #{column[:collate]}" if column[:collate]
+    end
+
     # Add default SQL fragment to column creation SQL.
     def column_definition_default_sql(sql, column)
       sql << " DEFAULT #{literal(column[:default])}" if column.include?(:default)
@@ -318,7 +431,7 @@ module Sequel
       sql = " REFERENCES #{quote_schema_table(column[:table])}"
       sql << "(#{Array(column[:key]).map{|x| quote_identifier(x)}.join(COMMA_SEPARATOR)})" if column[:key]
       sql << " ON DELETE #{on_delete_clause(column[:on_delete])}" if column[:on_delete]
-      sql << " ON UPDATE #{on_delete_clause(column[:on_update])}" if column[:on_update]
+      sql << " ON UPDATE #{on_update_clause(column[:on_update])}" if column[:on_update]
       sql << " DEFERRABLE INITIALLY DEFERRED" if column[:deferrable]
       sql
     end
@@ -354,7 +467,7 @@ module Sequel
 
     # Execute the create index statements using the generator.
     def create_table_indexes_from_generator(name, generator, options)
-      e = options[:ignore_index_errors]
+      e = options[:ignore_index_errors] || options[:if_not_exists]
       generator.indexes.each do |index|
         begin
           index_sql_list(name, [index]).each{|sql| execute_ddl(sql)}
@@ -366,7 +479,25 @@ module Sequel
 
     # DDL statement for creating a table with the given name, columns, and options
     def create_table_sql(name, generator, options)
-      "CREATE #{temporary_table_sql if options[:temp]}TABLE #{quote_schema_table(name)} (#{column_list_sql(generator)})"
+      "#{create_table_prefix_sql(name, options)} (#{column_list_sql(generator)})"
+    end
+
+    # Run a command to create the table with the given name from the given
+    # SELECT sql statement.
+    def create_table_as(name, sql, options)
+      sql = sql.sql if sql.is_a?(Sequel::Dataset)
+      run(create_table_as_sql(name, sql, options))
+    end
+    
+    # DDL statement for creating a table from the result of a SELECT statement.
+    # +sql+ should be a string representing a SELECT query.
+    def create_table_as_sql(name, sql, options)
+      "#{create_table_prefix_sql(name, options)} AS #{sql}"
+    end
+
+    # DDL statement for creating a table with the given name, columns, and options
+    def create_table_prefix_sql(name, options)
+      "CREATE #{temporary_table_sql if options[:temp]}TABLE#{' IF NOT EXISTS' if options[:if_not_exists]} #{options[:temp] ? quote_identifier(name) : quote_schema_table(name)}"
     end
 
     # Default index name for the table and columns, may be too long
@@ -382,10 +513,15 @@ module Sequel
     end
 
     # SQL DDL statement to drop the table with the given name.
-    def drop_table_sql(name)
-      "DROP TABLE #{quote_schema_table(name)}"
+    def drop_table_sql(name, options)
+      "DROP TABLE#{' IF EXISTS' if options[:if_exists]} #{quote_schema_table(name)}#{' CASCADE' if options[:cascade]}"
     end
     
+    # SQL DDL statement to drop a view with the given name.
+    def drop_view_sql(name, options)
+      "DROP VIEW #{quote_schema_table(name)}#{' CASCADE' if options[:cascade]}"
+    end
+
     # Proxy the filter_expr call to the dataset, used for creating constraints.
     def filter_expr(*args, &block)
       schema_utility_dataset.literal(schema_utility_dataset.send(:filter_expr, *args, &block))
@@ -410,6 +546,32 @@ module Sequel
       indexes.map{|i| index_definition_sql(table_name, i)}
     end
 
+    # Extract the join table name from the arguments given to create_join_table.
+    # Also does argument validation for the create_join_table method.
+    def join_table_name(hash, options)
+      entries = hash.values
+      raise Error, "must have 2 entries in hash given to (create|drop)_join_table" unless entries.length == 2
+      if options[:name]
+        options[:name]
+      else
+        table_names = entries.map{|e| join_table_name_extract(e)}
+        table_names.map{|t| t.to_s}.sort.join('_')
+      end
+    end
+
+    # Extract an individual join table name, which should either be a string
+    # or symbol, or a hash containing one of those as the value for :table.
+    def join_table_name_extract(entry)
+      case entry
+      when Symbol, String
+        entry
+      when Hash
+        join_table_name_extract(entry[:table])
+      else
+        raise Error, "can't extract table name from #{entry.inspect}"
+      end
+    end
+    
     # SQL DDL ON DELETE fragment to use, based on the given action.
     # The following actions are recognized:
     # 
@@ -420,19 +582,15 @@ module Sequel
     #   but do not allow deferring the integrity check.
     # * :set_default - Set columns referencing this row to their default value.
     # * :set_null - Set columns referencing this row to NULL.
+    #
+    # Any other object given is just converted to a string, with "_" converted to " " and upcased.
     def on_delete_clause(action)
-      case action
-      when :restrict
-        RESTRICT
-      when :cascade
-        CASCADE
-      when :set_null
-        SET_NULL
-      when :set_default
-        SET_DEFAULT
-      else
-        NO_ACTION
-      end
+      action.to_s.gsub("_", " ").upcase
+    end
+
+    # Alias of #on_delete_clause, since the two usually behave the same.
+    def on_update_clause(action)
+      on_delete_clause(action)
     end
     
     # Proxy the quote_schema_table method to the dataset