sequel 3.11.0 → 3.12.0

data/lib/sequel/database/schema_generator.rb

@@ -13,7 +13,7 @@ module Sequel
     # the column method, which makes for a nicer DSL.
     #
     # For more information on Sequel's support for schema modification, see
-    # the {"Schema Modification" guide}[link:files/doc/schema_rdoc.html].
+    # the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
     class Generator
       # Classes specifying generic types that Sequel will convert to database-specific types.
       GENERIC_TYPES=[String, Integer, Fixnum, Bignum, Float, Numeric, BigDecimal,
@@ -75,7 +75,7 @@ module Sequel
       #   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 Dataset#on_delete_clause for options.
+      #   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
@@ -86,6 +86,10 @@ module Sequel
       #   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.
       def column(name, type, opts = {})
         columns << {:name => name, :type => type}.merge(opts)
         index(name) if opts[:index]
@@ -205,7 +209,7 @@ module Sequel
     # alter a table's description.
     #
     # For more information on Sequel's support for schema modification, see
-    # the {"Schema Modification" guide}[link:files/doc/schema_rdoc.html].
+    # the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
     class AlterTableGenerator
       # An array of DDL operations to perform
       attr_reader :operations

data/lib/sequel/database/schema_methods.rb

@@ -1,5 +1,25 @@
 module Sequel
   class Database
+    # ---------------------
+    # :section: 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
+
     # Adds a column to the specified table. This method expects a column name,
     # a datatype and optionally a hash with additional constraints and options:
     #
@@ -46,11 +66,12 @@ module Sequel
     # definitions using create_table, and #add_index accepts all the options
     # available for index definition.
     #
-    # See Schema::AlterTableGenerator and the {"Schema Modification" guide}[link:files/doc/schema_rdoc.html].
+    # See Schema::AlterTableGenerator and the {"Migrations and Schema Modification" guide}[link:files/doc/migration_rdoc.html].
     def alter_table(name, generator=nil, &block)
-      remove_cached_schema(name)
       generator ||= Schema::AlterTableGenerator.new(self, &block)
       alter_table_sql_list(name, generator.operations).flatten.each {|sql| execute_ddl(sql)}
+      remove_cached_schema(name)
+      nil
     end
     
     # Creates a table with the columns given in the provided block:
@@ -66,12 +87,14 @@ module Sequel
     # * :temp - Create the table as a temporary table.
     # * :ignore_index_errors - Ignore any errors when creating indexes.
     #
-    # See Schema::Generator and the {"Schema Modification" guide}[link:files/doc/schema_rdoc.html].
+    # See Schema::Generator 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)
       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
     
     # Forcibly creates a table, attempting to drop it unconditionally (and catching any errors), then creating it.
@@ -90,9 +113,10 @@ module Sequel
     #   DB.create_or_replace_view(:cheap_items, "SELECT * FROM items WHERE price < 100")
     #   DB.create_or_replace_view(:ruby_items, DB[:items].filter(:category => 'ruby'))
     def create_or_replace_view(name, source)
-      remove_cached_schema(name)
       source = source.sql if source.is_a?(Dataset)
       execute_ddl("CREATE OR REPLACE VIEW #{quote_schema_table(name)} AS #{source}")
+      remove_cached_schema(name)
+      nil
     end
     
     # Creates a view based on a dataset or an SQL string:
@@ -128,9 +152,10 @@ module Sequel
     #   DB.drop_table(:posts, :comments)
     def drop_table(*names)
       names.each do |n|
-        remove_cached_schema(n)
         execute_ddl(drop_table_sql(n))
+        remove_cached_schema(n)
       end
+      nil
     end
     
     # Drops one or more views corresponding to the given names:
@@ -138,9 +163,10 @@ module Sequel
     #   DB.drop_view(:cheap_items)
     def drop_view(*names)
       names.each do |n|
-        remove_cached_schema(n)
         execute_ddl("DROP VIEW #{quote_schema_table(n)}")
+        remove_cached_schema(n)
       end
+      nil
     end
 
     # Renames a table:
@@ -149,8 +175,9 @@ module Sequel
     #   DB.rename_table :items, :old_items
     #   DB.tables #=> [:old_items]
     def rename_table(name, new_name)
-      remove_cached_schema(name)
       execute_ddl(rename_table_sql(name, new_name))
+      remove_cached_schema(name)
+      nil
     end
     
     # Renames a column in the specified table. This method expects the current
@@ -183,6 +210,108 @@ module Sequel
 
     private
 
+    # 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)
+      quoted_name = quote_identifier(op[:name]) if op[:name]
+      alter_table_op = case op[:op]
+      when :add_column
+        "ADD COLUMN #{column_definition_sql(op)}"
+      when :drop_column
+        "DROP COLUMN #{quoted_name}"
+      when :rename_column
+        "RENAME COLUMN #{quoted_name} TO #{quote_identifier(op[:new_name])}"
+      when :set_column_type
+        "ALTER COLUMN #{quoted_name} TYPE #{type_literal(op)}"
+      when :set_column_default
+        "ALTER COLUMN #{quoted_name} SET DEFAULT #{literal(op[:default])}"
+      when :set_column_null
+        "ALTER COLUMN #{quoted_name} #{op[:null] ? 'DROP' : 'SET'} NOT NULL"
+      when :add_index
+        return index_definition_sql(table, op)
+      when :drop_index
+        return drop_index_sql(table, op)
+      when :add_constraint
+        "ADD #{constraint_definition_sql(op)}"
+      when :drop_constraint
+        "DROP CONSTRAINT #{quoted_name}"
+      else
+        raise Error, "Unsupported ALTER TABLE operation"
+      end
+      "ALTER TABLE #{quote_schema_table(table)} #{alter_table_op}"
+    end
+
+    # Array of SQL DDL modification statements for the given table,
+    # corresponding to the DDL changes specified by the operations.
+    def alter_table_sql_list(table, operations)
+      operations.map{|op| alter_table_sql(table, op)}
+    end
+    
+    # The SQL string specify the autoincrement property, generally used by
+    # primary keys.
+    def auto_increment_sql
+      AUTOINCREMENT
+    end
+    
+    # SQL DDL fragment containing the column creation SQL for the given column.
+    def column_definition_sql(column)
+      sql = "#{quote_identifier(column[:name])} #{type_literal(column)}"
+      sql << UNIQUE if column[:unique]
+      null = column.fetch(:null, column[:allow_null])
+      sql << NOT_NULL if null == false
+      sql << NULL if null == true
+      sql << " DEFAULT #{literal(column[:default])}" if column.include?(:default)
+      sql << PRIMARY_KEY if column[:primary_key]
+      sql << " #{auto_increment_sql}" if column[:auto_increment]
+      sql << column_references_column_constraint_sql(column) if column[:table]
+      sql
+    end
+    
+    # SQL DDL fragment containing the column creation
+    # SQL for all given columns, used inside a CREATE TABLE block.
+    def column_list_sql(generator)
+      (generator.columns.map{|c| column_definition_sql(c)} + generator.constraints.map{|c| constraint_definition_sql(c)}).join(COMMA_SEPARATOR)
+    end
+
+    # SQL DDL fragment for column foreign key references (column constraints)
+    def column_references_column_constraint_sql(column)
+      column_references_sql(column)
+    end
+
+    # SQL DDL fragment for column foreign key references
+    def column_references_sql(column)
+      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 << " DEFERRABLE INITIALLY DEFERRED" if column[:deferrable]
+      sql
+    end
+  
+    # SQL DDL fragment for table foreign key references (table constraints)
+    def column_references_table_constraint_sql(constraint)
+      "FOREIGN KEY #{literal(constraint[:columns])}#{column_references_sql(constraint)}"
+    end
+
+    # SQL DDL fragment specifying a constraint on a table.
+    def constraint_definition_sql(constraint)
+      sql = constraint[:name] ? "CONSTRAINT #{quote_identifier(constraint[:name])} " : ""
+      case constraint[:type]
+      when :check
+        check = constraint[:check]
+        sql << "CHECK #{filter_expr((check.is_a?(Array) && check.length == 1) ? check.first : check)}"
+      when :primary_key
+        sql << "PRIMARY KEY #{literal(constraint[:columns])}"
+      when :foreign_key
+        sql << column_references_table_constraint_sql(constraint)
+      when :unique
+        sql << "UNIQUE #{literal(constraint[:columns])}"
+      else
+        raise Error, "Invalid constriant type #{constraint[:type]}, should be :check, :primary_key, :foreign_key, or :unique"
+      end
+      sql
+    end
+
     # Execute the create table statements using the generator.
     def create_table_from_generator(name, generator, options)
       execute_ddl(create_table_sql(name, generator, options))
@@ -199,5 +328,220 @@ module Sequel
         end
       end
     end
+
+    # 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)})"
+    end
+
+    # Default index name for the table and columns, may be too long
+    # for certain databases.
+    def default_index_name(table_name, columns)
+      schema, table = schema_and_table(table_name)
+      "#{"#{schema}_" if schema and schema != default_schema}#{table}_#{columns.map{|c| [String, Symbol].any?{|cl| c.is_a?(cl)} ? c : literal(c).gsub(/\W/, '_')}.join(UNDERSCORE)}_index"
+    end
+  
+    # The SQL to drop an index for the table.
+    def drop_index_sql(table, op)
+      "DROP INDEX #{quote_identifier(op[:name] || default_index_name(table, op[:columns]))}"
+    end
+
+    # SQL DDL statement to drop the table with the given name.
+    def drop_table_sql(name)
+      "DROP TABLE #{quote_schema_table(name)}"
+    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))
+    end
+
+    # SQL DDL statement for creating an index for the table with the given name
+    # and index specifications.
+    def index_definition_sql(table_name, index)
+      index_name = index[:name] || default_index_name(table_name, index[:columns])
+      if index[:type]
+        raise Error, "Index types are not supported for this database"
+      elsif index[:where]
+        raise Error, "Partial indexes are not supported for this database"
+      else
+        "CREATE #{'UNIQUE ' if index[:unique]}INDEX #{quote_identifier(index_name)} ON #{quote_schema_table(table_name)} #{literal(index[:columns])}"
+      end
+    end
+  
+    # Array of SQL DDL statements, one for each index specification,
+    # for the given table.
+    def index_sql_list(table_name, indexes)
+      indexes.map{|i| index_definition_sql(table_name, i)}
+    end
+
+    # SQL DDL ON DELETE fragment to use, based on the given action.
+    # The following actions are recognized:
+    # 
+    # * :cascade - Delete rows referencing this row.
+    # * :no_action (default) - Raise an error if other rows reference this
+    #   row, allow deferring of the integrity check.
+    # * :restrict - Raise an error if other rows reference this row,
+    #   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.
+    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
+    end
+    
+    # Proxy the quote_schema_table method to the dataset
+    def quote_schema_table(table)
+      schema_utility_dataset.quote_schema_table(table)
+    end
+    
+    # Proxy the quote_identifier method to the dataset, used for quoting tables and columns.
+    def quote_identifier(v)
+      schema_utility_dataset.quote_identifier(v)
+    end
+    
+    # SQL DDL statement for renaming a table.
+    def rename_table_sql(name, new_name)
+      "ALTER TABLE #{quote_schema_table(name)} RENAME TO #{quote_schema_table(new_name)}"
+    end
+
+    # Remove the cached schema_utility_dataset, because the identifier
+    # quoting has changed.
+    def reset_schema_utility_dataset
+      @schema_utility_dataset = nil
+    end
+    
+    # Split the schema information from the table
+    def schema_and_table(table_name)
+      schema_utility_dataset.schema_and_table(table_name)
+    end
+
+    # Return true if the given column schema represents an autoincrementing primary key.
+    def schema_autoincrementing_primary_key?(schema)
+      !!schema[:primary_key]
+    end
+
+    # The dataset to use for proxying certain schema methods.
+    def schema_utility_dataset
+      @schema_utility_dataset ||= dataset
+    end
+
+    # SQL DDL fragment for temporary table
+    def temporary_table_sql
+      self.class.const_get(:TEMPORARY)
+    end
+
+    # SQL fragment specifying the type of a given column.
+    def type_literal(column)
+      column[:type].is_a?(Class) ? type_literal_generic(column) : type_literal_specific(column)
+    end
+    
+    # SQL fragment specifying the full type of a column,
+    # consider the type with possible modifiers.
+    def type_literal_generic(column)
+      meth = "type_literal_generic_#{column[:type].name.to_s.downcase}"
+      if respond_to?(meth, true)
+        send(meth, column)
+      else
+        raise Error, "Unsupported ruby class used as database type: #{column[:type]}"
+      end
+    end
+
+    # Alias for type_literal_generic_numeric, to make overriding in a subclass easier.
+    def type_literal_generic_bigdecimal(column)
+      type_literal_generic_numeric(column)
+    end
+
+    # Sequel uses the bigint type by default for Bignums.
+    def type_literal_generic_bignum(column)
+      :bigint
+    end
+
+    # Sequel uses the date type by default for Dates.
+    def type_literal_generic_date(column)
+      :date
+    end
+
+    # Sequel uses the timestamp type by default for DateTimes.
+    def type_literal_generic_datetime(column)
+      :timestamp
+    end
+
+    # Alias for type_literal_generic_trueclass, to make overriding in a subclass easier.
+    def type_literal_generic_falseclass(column)
+      type_literal_generic_trueclass(column)
+    end
+
+    # Sequel uses the blob type by default for Files.
+    def type_literal_generic_file(column)
+      :blob
+    end
+
+    # Alias for type_literal_generic_integer, to make overriding in a subclass easier.
+    def type_literal_generic_fixnum(column)
+      type_literal_generic_integer(column)
+    end
+
+    # Sequel uses the double precision type by default for Floats.
+    def type_literal_generic_float(column)
+      :"double precision"
+    end
+
+    # Sequel uses the integer type by default for integers
+    def type_literal_generic_integer(column)
+      :integer
+    end
+
+    # Sequel uses the numeric type by default for Numerics and BigDecimals.
+    # If a size is given, it is used, otherwise, it will default to whatever
+    # the database default is for an unsized value.
+    def type_literal_generic_numeric(column)
+      column[:size] ? "numeric(#{Array(column[:size]).join(', ')})" : :numeric
+    end
+
+    # Sequel uses the varchar type by default for Strings.  If a
+    # size isn't present, Sequel assumes a size of 255.  If the
+    # :fixed option is used, Sequel uses the char type.  If the
+    # :text option is used, Sequel uses the :text type.
+    def type_literal_generic_string(column)
+      if column[:text]
+        :text
+      elsif column[:fixed]
+        "char(#{column[:size]||255})"
+      else
+        "varchar(#{column[:size]||255})"
+      end
+    end
+    
+    # Sequel uses the timestamp type by default for Time values.
+    # If the :only_time option is used, the time type is used.
+    def type_literal_generic_time(column)
+      column[:only_time] ? :time : :timestamp
+    end
+
+    # Sequel uses the boolean type by default for TrueClass and FalseClass.
+    def type_literal_generic_trueclass(column)
+      :boolean
+    end
+
+    # SQL fragment for the given type of a column if the column is not one of the
+    # generic types specified with a ruby class.
+    def type_literal_specific(column)
+      type = column[:type]
+      type = "double precision" if type.to_s == 'double'
+      column[:size] ||= 255 if type.to_s == 'varchar'
+      elements = column[:size] || column[:elements]
+      "#{type}#{literal(Array(elements)) if elements}#{UNSIGNED if column[:unsigned]}"
+    end
   end
 end