viking-sequel 3.10.0

data/lib/sequel/database/schema_generator.rb

@@ -0,0 +1,327 @@
+module Sequel
+  # The Schema module holds the schema generators.
+  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.
+    #
+    # For more information on Sequel's support for schema modification, see
+    # the {"Schema Modification" guide}[link:files/doc/schema_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,
+      Date, DateTime, Time, File, TrueClass, FalseClass]
+      
+      # Return the columns created by this generator
+      attr_reader :columns
+
+      # Return the constraints created by this generator
+      attr_reader :constraints
+
+      # Return the indexes created by this generator
+      attr_reader :indexes
+
+      # 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 = []
+        @constraints = []
+        @primary_key = nil
+        instance_eval(&block) if block
+        @columns.unshift(@primary_key) if @primary_key && !has_column?(primary_key_name)
+      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", __FILE__, __LINE__)
+        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 Dataset#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.
+      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)
+        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.
+      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 = {})
+        constraints << {:type => :unique, :columns => Array(columns)}.merge(opts)
+      end
+
+      private
+
+      # Add a composite primary key constraint
+      def composite_primary_key(columns, *args)
+        opts = args.pop || {}
+        constraints << {:type => :primary_key, :columns => columns}.merge(opts)
+      end
+
+      # Add a composite foreign key constraint
+      def composite_foreign_key(columns, opts)
+        constraints << {:type => :foreign_key, :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.
+    #
+    # For more information on Sequel's support for schema modification, see
+    # the {"Schema Modification" guide}[link:files/doc/schema_rdoc.html].
+    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, :check => block || args}
+      end
+
+      # Add a unique constraint to the given column(s)
+      def add_unique_constraint(columns, opts = {})
+        @operations << {:op => :add_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, options={})
+        @operations << {:op => :drop_index, :columns => Array(columns)}.merge(options)
+      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
+
+      # Add a composite primary key constraint
+      def add_composite_primary_key(columns, opts)
+        @operations << {:op => :add_constraint, :type => :primary_key, :columns => columns}.merge(opts)
+      end
+
+      # Add a composite foreign key constraint
+      def add_composite_foreign_key(columns, table, opts)
+        @operations << {:op => :add_constraint, :type => :foreign_key, :columns => columns, :table => table}.merge(opts)
+      end
+    end
+  end
+end
+

data/lib/sequel/database/schema_methods.rb

@@ -0,0 +1,203 @@
+module Sequel
+  class Database
+    # Adds a column to the specified table. This method expects a column name,
+    # a datatype and optionally a hash with additional constraints and options:
+    #
+    #   DB.add_column :items, :name, :text, :unique => true, :null => false
+    #   DB.add_column :items, :category, :text, :default => 'ruby'
+    #
+    # See alter_table.
+    def add_column(table, *args)
+      alter_table(table) {add_column(*args)}
+    end
+    
+    # Adds an index to a table for the given columns:
+    # 
+    #   DB.add_index :posts, :title
+    #   DB.add_index :posts, [:author, :title], :unique => true
+    #
+    #
+    # Options:
+    # * :ignore_errors - Ignore any DatabaseErrors that are raised
+    #
+    # See alter_table.
+    def add_index(table, columns, options={})
+      e = options[:ignore_errors]
+      begin
+        alter_table(table){add_index(columns, options)}
+      rescue DatabaseError
+        raise unless e
+      end
+    end
+    
+    # Alters the given table with the specified block. Example:
+    #
+    #   DB.alter_table :items do
+    #     add_column :category, :text, :default => 'ruby'
+    #     drop_column :category
+    #     rename_column :cntr, :counter
+    #     set_column_type :value, :float
+    #     set_column_default :value, :float
+    #     add_index [:group, :category]
+    #     drop_index [:group, :category]
+    #   end
+    #
+    # Note that #add_column accepts all the options available for column
+    # 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].
+    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)}
+    end
+    
+    # Creates a table with the columns given in the provided block:
+    #
+    #   DB.create_table :posts do
+    #     primary_key :id
+    #     column :title, :text
+    #     String :content
+    #     index :title
+    #   end
+    #
+    # Options:
+    # * :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].
+    def create_table(name, options={}, &block)
+      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)
+    end
+    
+    # Forcibly creates a table, attempting to drop it unconditionally (and catching any errors), then creating it.
+    def create_table!(name, options={}, &block)
+      drop_table(name) rescue nil
+      create_table(name, options, &block)
+    end
+    
+    # Creates the table unless the table already exists
+    def create_table?(name, options={}, &block)
+      create_table(name, options, &block) unless table_exists?(name)
+    end
+    
+    # Creates a view, replacing it if it already exists:
+    #
+    #   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}")
+    end
+    
+    # Creates a view based on a dataset or an SQL string:
+    #
+    #   DB.create_view(:cheap_items, "SELECT * FROM items WHERE price < 100")
+    #   DB.create_view(:ruby_items, DB[:items].filter(:category => 'ruby'))
+    def create_view(name, source)
+      source = source.sql if source.is_a?(Dataset)
+      execute_ddl("CREATE VIEW #{quote_schema_table(name)} AS #{source}")
+    end
+    
+    # Removes a column from the specified table:
+    #
+    #   DB.drop_column :items, :category
+    #
+    # See alter_table.
+    def drop_column(table, *args)
+      alter_table(table) {drop_column(*args)}
+    end
+    
+    # Removes an index for the given table and column/s:
+    #
+    #   DB.drop_index :posts, :title
+    #   DB.drop_index :posts, [:author, :title]
+    #
+    # See alter_table.
+    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, :comments)
+    def drop_table(*names)
+      names.each do |n|
+        remove_cached_schema(n)
+        execute_ddl(drop_table_sql(n))
+      end
+    end
+    
+    # Drops one or more views corresponding to the given names:
+    #
+    #   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)}")
+      end
+    end
+
+    # Renames a table:
+    #
+    #   DB.tables #=> [:items]
+    #   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))
+    end
+    
+    # Renames a column in the specified table. This method expects the current
+    # column name and the new column name:
+    #
+    #   DB.rename_column :items, :cntr, :counter
+    #
+    # See alter_table.
+    def rename_column(table, *args)
+      alter_table(table) {rename_column(*args)}
+    end
+    
+    # Sets the default value for the given column in the given table:
+    #
+    #   DB.set_column_default :items, :category, 'perl!'
+    #
+    # See alter_table.
+    def set_column_default(table, *args)
+      alter_table(table) {set_column_default(*args)}
+    end
+    
+    # Set the data type for the given column in the given table:
+    #
+    #   DB.set_column_type :items, :price, :float
+    #
+    # See alter_table.
+    def set_column_type(table, *args)
+      alter_table(table) {set_column_type(*args)}
+    end
+
+    private
+
+    # Execute the create table statements using the generator.
+    def create_table_from_generator(name, generator, options)
+      execute_ddl(create_table_sql(name, generator, options))
+    end
+
+    # Execute the create index statements using the generator.
+    def create_table_indexes_from_generator(name, generator, options)
+      e = options[:ignore_index_errors]
+      index_sql_list(name, generator.indexes).each do |sql|
+        begin
+          execute_ddl(sql)
+        rescue DatabaseError
+          raise unless e
+        end
+      end
+    end
+  end
+end