sequel 3.21.0 → 3.31.0

data/lib/sequel/database/schema_methods.rb

@@ -1,7 +1,7 @@
 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.
     # ---------------------
 
@@ -21,7 +21,7 @@ module Sequel
     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]
 
     # 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 +29,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 +40,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 +65,17 @@ 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
-    
+
     # Creates a table with the columns given in the provided block:
     #
     #   DB.create_table :posts do
@@ -89,7 +89,7 @@ module Sequel
     # :temp :: Create the table as a temporary table.
     # :ignore_index_errors :: Ignore any errors when creating indexes.
     #
-    # See Schema::Generator and the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
+    # See <tt>Schema::Generator</tt> and the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
     def create_table(name, options={}, &block)
       remove_cached_schema(name)
       options = {:generator=>options} if options.is_a?(Schema::Generator)
@@ -99,19 +99,28 @@ module Sequel
       nil
     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 * FROM a LIMIT a -- 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) if table_exists?(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 * FROM a LIMIT a -- 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 +147,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,17 +157,20 @@ 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
     
     # Drops one or more tables corresponding to the given names:
     #
+    #   DB.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
@@ -167,9 +179,12 @@ module Sequel
     # 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 +206,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 +215,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 +224,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 +244,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 +260,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 +295,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)
@@ -354,7 +379,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 +391,7 @@ 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 #{temporary_table_sql if options[:temp]}TABLE#{' IF NOT EXISTS' if options[:if_not_exists]} #{options[:temp] ? quote_identifier(name) : quote_schema_table(name)} (#{column_list_sql(generator)})"
     end
 
     # Default index name for the table and columns, may be too long
@@ -382,10 +407,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 #{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))