colincasey-sequel 2.10.0 → 2.10.1

data/lib/sequel_core/schema/generator.rb

@@ -0,0 +1,320 @@
+module Sequel
+  # The Schema module holds the schema generators and the SQL code relating
+  # to SQL DDL (Data Definition Language).
+  module Schema
+    # Schema::Generator is an internal class that the user is not expected
+    # to instantiate directly.  Instances are created by Database#create_table.
+    # It is used to specify table creation parameters.  It takes a Database
+    # object and a block of column/index/constraint specifications, and
+    # gives the Database a table description, which the database uses to
+    # create a table.
+    #
+    # Schema::Generator has some methods but also includes method_missing,
+    # allowing users to specify column type as a method instead of using
+    # the column method, which makes for a nicer DSL.
+    class Generator
+      # Classes specifying generic types that Sequel will convert to database-specific types.
+      GENERIC_TYPES=[String, Integer, Fixnum, Bignum, Float, Numeric, BigDecimal,
+      Date, DateTime, Time, File, TrueClass, FalseClass]
+      
+      # Set the database in which to create the table, and evaluate the block
+      # in the context of this object.
+      def initialize(db, &block)
+        @db = db
+        @columns = []
+        @indexes = []
+        @primary_key = nil
+        instance_eval(&block) if block
+      end
+      
+      # Add a method for each of the given types that creates a column
+      # with that type as a constant.  Types given should either already
+      # be constants/classes or a capitalized string/symbol with the same name
+      # as a constant/class.
+      def self.add_type_method(*types)
+        types.each do |type|
+          class_eval "def #{type}(name, opts={}); column(name, #{type}, opts); end"
+        end
+      end
+      
+      # Add a unnamed constraint to the DDL, specified by the given block
+      # or args.
+      def check(*args, &block)
+        constraint(nil, *args, &block)
+      end
+
+      # Add a column with the given name, type, and opts to the DDL. 
+      #
+      # You can also create columns via method missing, so the following are
+      # equivalent:
+      #
+      #   column :number, :integer
+      #   integer :number
+      #
+      # 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.
+      # * :unique - Mark the column is 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]
+      end
+      
+      # Adds a named constraint (or unnamed if name is nil) to the DDL,
+      # with the given block or args.
+      def constraint(name, *args, &block)
+        @columns << {:name => name, :type => :check, :check => block || args,
+                     :constraint_type => :check}
+      end
+      
+      # Return the DDL created by the generator as a array of two elements,
+      # the first being the columns and the second being the indexes.
+      def create_info
+        @columns.unshift(@primary_key) if @primary_key && !has_column?(primary_key_name)
+        [@columns, @indexes]
+      end
+
+      # Add a foreign key in the table that references another table to the DDL. See column
+      # for available options.
+      def foreign_key(name, table=nil, opts = {})
+        opts = case table
+        when Hash
+          table.merge(opts)
+        when Symbol
+          opts.merge(:table=>table)
+        when NilClass
+          opts
+        else
+          raise(Error, "The second argument to foreign_key should be a Hash, Symbol, or nil")
+        end
+        return composite_foreign_key(name, opts) if name.is_a?(Array)
+        column(name, Integer, opts)
+      end
+      
+      # Add a full text index on the given columns to the DDL.
+      def full_text_index(columns, opts = {})
+        index(columns, opts.merge(:type => :full_text))
+      end
+      
+      # True if the DDL includes the creation of a column with the given name.
+      def has_column?(name)
+        @columns.any?{|c| c[:name] == name}
+      end
+      
+      # 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)
+      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
+      # 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.
+      # 
+      # 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})
+        
+        if opts = args.pop
+          opts = {:type => opts} unless opts.is_a?(Hash)
+          if type = args.pop
+            opts.merge!(:type => type)
+          end
+          @primary_key.merge!(opts)
+        end
+        @primary_key
+      end
+
+      # The name of the primary key for this table, if it has a primary key.
+      def primary_key_name
+        @primary_key[:name] if @primary_key
+      end
+      
+      # Add a spatial index on the given columns to the DDL.
+      def spatial_index(columns, opts = {})
+        index(columns, opts.merge(:type => :spatial))
+      end
+
+      # Add a unique constraint on the given columns to the DDL.
+      def unique(columns, opts = {})
+        @columns << {:type => :check, :constraint_type => :unique,
+                     :name => nil, :columns => Array(columns)}.merge(opts)
+      end
+
+      private
+
+      def composite_primary_key(columns, *args)
+        opts = args.pop || {}
+        @columns << {:type => :check, :constraint_type => :primary_key,
+                     :name => nil, :columns => columns}.merge(opts)
+      end
+
+      def composite_foreign_key(columns, opts)
+        @columns << {:type => :check, :constraint_type => :foreign_key,
+                     :name => nil, :columns => columns }.merge(opts)
+      end
+      
+      add_type_method(*GENERIC_TYPES)
+    end
+  
+    # Schema::AlterTableGenerator is an internal class that the user is not expected
+    # 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
+    # alter a table's description.
+    class AlterTableGenerator
+      # An array of DDL operations to perform
+      attr_reader :operations
+      
+      # Set the Database object to which to apply the DDL, and evaluate the
+      # block in the context of this object.
+      def initialize(db, &block)
+        @db = db
+        @operations = []
+        instance_eval(&block) if block
+      end
+      
+      # Add a column with the given name, type, and opts to the DDL for the table.
+      # See Generator#column for the available options.
+      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.
+      def add_constraint(name, *args, &block)
+        @operations << {:op => :add_constraint, :name => name, :type => :check, \
+          :constraint_type => :check, :check => block || args}
+      end
+
+      def add_unique_constraint(columns, opts = {})
+        @operations << {:op => :add_constraint, :type => :check,
+          :constraint_type => :unique, :columns => Array(columns)}.merge(opts)
+      end
+
+      # Add a foreign key with the given name and referencing the given table
+      # 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.
+      #
+      # NOTE: If you need to add a foreign key constraint to an existing column
+      # use the composite key syntax even if it is only one column.
+      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))
+      end
+      
+      # Add a full text index on the given columns to the DDL for the table.
+      # See Generator#index for available options.
+      def add_full_text_index(columns, opts = {})
+        add_index(columns, {:type=>:full_text}.merge(opts))
+      end
+      
+      # Add an index on the given columns to the DDL for the table.  See
+      # Generator#index for available options.
+      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.
+      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)
+        add_column(name, opts.delete(:type), opts)
+      end
+      
+      # Add a spatial index on the given columns to the DDL for the table.
+      # See Generator#index for available options.
+      def add_spatial_index(columns, opts = {})
+        add_index(columns, {:type=>:spatial}.merge(opts))
+      end
+      
+      # Remove a column from the DDL for the table.
+      def drop_column(name)
+        @operations << {:op => :drop_column, :name => name}
+      end
+      
+      # Remove a constraint from the DDL for the table.
+      def drop_constraint(name)
+        @operations << {:op => :drop_constraint, :name => name}
+      end
+      
+      # Remove an index from the DDL for the table.
+      def drop_index(columns)
+        @operations << {:op => :drop_index, :columns => Array(columns)}
+      end
+
+      # Modify a column's name in the DDL for the table.
+      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.
+      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.
+      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.
+      def set_column_allow_null(name, allow_null)
+        @operations << {:op => :set_column_null, :name => name, :null => allow_null}
+      end
+
+      private
+
+      def add_composite_primary_key(columns, opts)
+        @operations << {:op => :add_constraint, :type => :check,
+          :constraint_type => :primary_key, :columns => columns}.merge(opts)
+      end
+
+      def add_composite_foreign_key(columns, table, opts)
+        @operations << {:op => :add_constraint, :type => :check,
+          :constraint_type => :foreign_key, :columns => columns,
+          :table => table}.merge(opts)
+      end
+    end
+  end
+end
+

data/lib/sequel_core/schema/sql.rb

@@ -0,0 +1,325 @@
+module Sequel
+  module Schema
+    module SQL
+      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
+      TYPES = Hash.new {|h, k| k}
+      TYPES.merge!(:double=>'double precision', String=>'varchar(255)',
+        Integer=>'integer', Fixnum=>'integer', Bignum=>'bigint',
+        Float=>'double precision', BigDecimal=>'numeric', Numeric=>'numeric',
+        Date=>'date', DateTime=>'timestamp', Time=>'timestamp', File=>'blob',
+        TrueClass=>'boolean', FalseClass=>'boolean')
+      UNDERSCORE = '_'.freeze
+      UNIQUE = ' UNIQUE'.freeze
+      UNSIGNED = ' UNSIGNED'.freeze
+
+      # 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)
+        return constraint_definition_sql(column) if column[:type] == :check
+        sql = "#{quote_identifier(column[:name])} #{type_literal(column)}"
+        sql << UNIQUE if column[:unique]
+        sql << NOT_NULL if column[:null] == false
+        sql << NULL if column[: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_sql(column) if column[:table]
+        sql
+      end
+      
+      # SQL DDL fragment containing the column creation
+      # SQL for all given columns, used instead a CREATE TABLE block.
+      def column_list_sql(columns)
+        columns.map{|c| column_definition_sql(c)}.join(COMMA_SEPARATOR)
+      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
+      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[:constraint_type]
+        when :primary_key
+          sql << "PRIMARY KEY #{literal(constraint[:columns])}"
+        when :foreign_key
+          sql << "FOREIGN KEY #{literal(constraint[:columns])}"
+          sql << column_references_sql(constraint)
+        when :unique
+          sql << "UNIQUE #{literal(constraint[:columns])}"
+        else
+          check = constraint[:check]
+          sql << "CHECK #{filter_expr((check.is_a?(Array) && check.length == 1) ? check.first : check)}"
+        end
+        sql
+      end
+
+      # Array of SQL DDL statements, the first for creating a table with the given
+      # name and column specifications, and the others for specifying indexes on
+      # the table.
+      def create_table_sql_list(name, columns, indexes = nil, options = {})
+        sql = ["CREATE TABLE #{quote_schema_table(name)} (#{column_list_sql(columns)})"]
+        sql.concat(index_list_sql_list(name, indexes)) if indexes && !indexes.empty?
+        sql
+      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| c.is_one_of?(String, Symbol) ? 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_identifier(table_name)} #{literal(index[:columns])}"
+        end
+      end
+    
+      # Array of SQL DDL statements, one for each index specification,
+      # for the given table.
+      def index_list_sql_list(table_name, indexes)
+        indexes.map{|i| index_definition_sql(table_name, i)}
+      end
+  
+      # Proxy the literal call to the dataset, used for default values.
+      def literal(v)
+        schema_utility_dataset.literal(v)
+      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
+
+      # Parse the schema from the database.
+      # If the table_name is not given, returns the schema for all tables as a hash.
+      # If the table_name is given, returns the schema for a single table as an
+      # array with all members being arrays of length 2.  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.
+      def schema(table = nil, opts={})
+        raise(Error, 'schema parsing is not implemented on this database') unless respond_to?(:schema_parse_table, true)
+
+        if table
+          sch, table_name = schema_and_table(table)
+          quoted_name = quote_schema_table(table)
+        end
+        opts = opts.merge(:schema=>sch) if sch && !opts.include?(:schema)
+        if opts[:reload] && @schemas
+          if table_name
+            @schemas.delete(quoted_name)
+          else
+            @schemas = nil
+          end
+        end
+
+        if @schemas
+          if table_name
+            return @schemas[quoted_name] if @schemas[quoted_name]
+          else
+            return @schemas
+          end
+        end
+        
+        raise(Error, '#tables does not exist, you must provide a specific table to #schema') if table.nil? && !respond_to?(:tables, true)
+
+        @schemas ||= Hash.new do |h,k|
+          quote_name = quote_schema_table(k)
+          h[quote_name] if h.include?(quote_name)
+        end
+
+        if table_name
+          cols = schema_parse_table(table_name, opts)
+          raise(Error, 'schema parsing returned no columns, table probably doesn\'t exist') if cols.blank?
+          @schemas[quoted_name] = cols
+        else
+          tables.each{|t| @schemas[quote_schema_table(t)] = schema_parse_table(t.to_s, opts)}
+          @schemas
+        end
+      end
+      
+      # The dataset to use for proxying certain schema methods.
+      def schema_utility_dataset
+        @schema_utility_dataset ||= dataset
+      end
+      
+      private
+
+      # 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 cached schema_utility_dataset, because the identifier
+      # quoting has changed.
+      def reset_schema_utility_dataset
+        @schema_utility_dataset = nil
+      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.
+      def schema_column_type(db_type)
+        case db_type
+        when /\Atinyint/io
+          Sequel.convert_tinyint_to_bool ? :boolean : :integer
+        when /\Ainterval\z/io
+          :interval
+        when /\A(character( varying)?|varchar|text)/io
+          :string
+        when /\A(int(eger)?|bigint|smallint)/io
+          :integer
+        when /\Adate\z/io
+          :date
+        when /\A(datetime|timestamp( with(out)? time zone)?)\z/io
+          :datetime
+        when /\Atime( with(out)? time zone)?\z/io
+          :time
+        when /\Aboolean\z/io
+          :boolean
+        when /\A(real|float|double( precision)?)\z/io
+          :float
+        when /\A(numeric(\(\d+,\d+\))?|decimal|money)\z/io
+          :decimal
+        when /\Abytea\z/io
+          :blob
+        end
+      end
+
+      # SQL fragment specifying the type of a given column.
+      def type_literal(column)
+        type = type_literal_base(column)
+        column[:size] ||= 255 if type.to_s == 'varchar'
+        elements = column[:size] || column[:elements]
+        "#{type}#{literal(Array(elements)) if elements}#{UNSIGNED if column[:unsigned]}"
+      end
+
+      # SQL fragment specifying the base type of a given column,
+      # without the size or elements.
+      def type_literal_base(column)
+        TYPES[column[:type]]
+      end
+    end
+  end
+end

data/lib/sequel_core/schema.rb

@@ -0,0 +1,2 @@
+require 'sequel_core/schema/generator'
+require 'sequel_core/schema/sql'