sequel 3.10.0 → 3.11.0

data/lib/sequel/database/schema_generator.rb

@@ -11,6 +11,9 @@ module Sequel
     # 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,
@@ -200,6 +203,9 @@ module Sequel
     # 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

data/lib/sequel/database/schema_methods.rb

@@ -46,7 +46,7 @@ module Sequel
     # definitions using create_table, and #add_index accepts all the options
     # available for index definition.
     #
-    # See Schema::AlterTableGenerator.
+    # 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)
@@ -66,7 +66,7 @@ module Sequel
     # * :temp - Create the table as a temporary table.
     # * :ignore_index_errors - Ignore any errors when creating indexes.
     #
-    # See Schema::Generator.
+    # 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)
@@ -191,10 +191,10 @@ module Sequel
     # 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|
+      generator.indexes.each do |index|
         begin
-          execute_ddl(sql)
-        rescue DatabaseError
+          index_sql_list(name, [index]).each{|sql| execute_ddl(sql)}
+        rescue Error
           raise unless e
         end
       end

data/lib/sequel/database/schema_sql.rb

@@ -69,7 +69,7 @@ module Sequel
     def column_definition_sql(column)
       sql = "#{quote_identifier(column[:name])} #{type_literal(column)}"
       sql << UNIQUE if column[:unique]
-      null = column.include?(:null) ? column[:null] : column[:allow_null]
+      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)

data/lib/sequel/dataset.rb

@@ -20,199 +20,13 @@ module Sequel
   #
   # Datasets are Enumerable objects, so they can be manipulated using any
   # of the Enumerable methods, such as map, inject, etc.
+  #
+  # For more information, see the {"Dataset Basics" guide}[link:files/doc/dataset_basics_rdoc.html].
   class Dataset
     extend Metaprogramming
     include Metaprogramming
     include Enumerable
-    
-    # The dataset options that require the removal of cached columns
-    # if changed.
-    COLUMN_CHANGE_OPTS = [:select, :sql, :from, :join].freeze
-
-    # All methods that should have a ! method added that modifies
-    # the receiver.
-    MUTATION_METHODS = %w'add_graph_aliases and cross_join distinct except exclude
-    filter for_update from from_self full_join full_outer_join graph
-    group group_and_count group_by having inner_join intersect invert join join_table left_join
-    left_outer_join limit lock_style naked natural_full_join natural_join
-    natural_left_join natural_right_join or order order_by order_more paginate qualify query
-    reverse reverse_order right_join right_outer_join select select_all select_more server
-    set_defaults set_graph_aliases set_overrides unfiltered ungraphed ungrouped union
-    unlimited unordered where with with_recursive with_sql'.collect{|x| x.to_sym}
-
-    # Which options don't affect the SQL generation.  Used by simple_select_all?
-    # to determine if this is a simple SELECT * FROM table.
-    NON_SQL_OPTIONS = [:server, :defaults, :overrides, :graph, :eager_graph, :graph_aliases]
-
-    NOTIMPL_MSG = "This method must be overridden in Sequel adapters".freeze
-    WITH_SUPPORTED=:select_with_sql
-
-    # The database that corresponds to this dataset
-    attr_accessor :db
-    
-    # Set the method to call on identifiers going into the database for this dataset
-    attr_accessor :identifier_input_method
-    
-    # Set the method to call on identifiers coming the database for this dataset
-    attr_accessor :identifier_output_method
-
-    # The hash of options for this dataset, keys are symbols.
-    attr_accessor :opts
-
-    # Whether to quote identifiers for this dataset
-    attr_writer :quote_identifiers
-    
-    # The row_proc for this database, should be a Proc that takes
-    # a single hash argument and returns the object you want
-    # each to return.
-    attr_accessor :row_proc
-
-    # Constructs a new Dataset instance with an associated database and 
-    # options. Datasets are usually constructed by invoking the Database#[] method:
-    #
-    #   DB[:posts]
-    #
-    # Sequel::Dataset is an abstract class that is not useful by itself. Each
-    # database adaptor should provide a subclass of Sequel::Dataset, and have
-    # the Database#dataset method return an instance of that class.
-    def initialize(db, opts = nil)
-      @db = db
-      @quote_identifiers = db.quote_identifiers? if db.respond_to?(:quote_identifiers?)
-      @identifier_input_method = db.identifier_input_method if db.respond_to?(:identifier_input_method)
-      @identifier_output_method = db.identifier_output_method if db.respond_to?(:identifier_output_method)
-      @opts = opts || {}
-      @row_proc = nil
-    end
-    
-    ### Class Methods ###
-
-    # Setup mutation (e.g. filter!) methods.  These operate the same as the
-    # non-! methods, but replace the options of the current dataset with the
-    # options of the resulting dataset.
-    def self.def_mutation_method(*meths)
-      meths.each do |meth|
-        class_eval("def #{meth}!(*args, &block); mutation_method(:#{meth}, *args, &block) end", __FILE__, __LINE__)
-      end
-    end
-
-    ### Instance Methods ###
-
-    # Return the dataset as an aliased expression with the given alias. You can
-    # use this as a FROM or JOIN dataset, or as a column if this dataset
-    # returns a single row and column.
-    def as(aliaz)
-      ::Sequel::SQL::AliasedExpression.new(self, aliaz)
-    end
-
-    # Returns a new clone of the dataset with with the given options merged.
-    # If the options changed include options in COLUMN_CHANGE_OPTS, the cached
-    # columns are deleted.
-    def clone(opts = {})
-      c = super()
-      c.opts = @opts.merge(opts)
-      c.instance_variable_set(:@columns, nil) if opts.keys.any?{|o| COLUMN_CHANGE_OPTS.include?(o)}
-      c
-    end
-    
-    # Add a mutation method to this dataset instance.
-    def def_mutation_method(*meths)
-      meths.each do |meth|
-        instance_eval("def #{meth}!(*args, &block); mutation_method(:#{meth}, *args, &block) end", __FILE__, __LINE__)
-      end
-    end
-
-    # Yield a dataset for each server in the connection pool that is tied to that server.
-    # Intended for use in sharded environments where all servers need to be modified
-    # with the same data:
-    #
-    #   DB[:configs].where(:key=>'setting').each_server{|ds| ds.update(:value=>'new_value')}
-    def each_server
-      db.servers.each{|s| yield server(s)}
-    end
-
-    # Returns a string representation of the dataset including the class name 
-    # and the corresponding SQL select statement.
-    def inspect
-      "#<#{self.class}: #{sql.inspect}>"
-    end
-
-    # Returns a naked dataset clone - i.e. a dataset that returns records as
-    # hashes instead of calling the row proc.
-    def naked
-      ds = clone
-      ds.row_proc = nil
-      ds
-    end
-    
-    # Set the server for this dataset to use.  Used to pick a specific database
-    # shard to run a query against, or to override the default (which is SELECT uses
-    # :read_only database and all other queries use the :default database).
-    def server(servr)
-      clone(:server=>servr)
-    end
-
-    # Set the default values for insert and update statements.  The values hash passed
-    # to insert or update are merged into this hash.
-    def set_defaults(hash)
-      clone(:defaults=>(@opts[:defaults]||{}).merge(hash))
-    end
-
-    # Set values that override hash arguments given to insert and update statements.
-    # This hash is merged into the hash provided to insert or update.
-    def set_overrides(hash)
-      clone(:overrides=>hash.merge(@opts[:overrides]||{}))
-    end
-    
-    # Add the mutation methods via metaprogramming
-    def_mutation_method(*MUTATION_METHODS)
-
-    protected
-
-    # Return true if the dataset has a non-nil value for any key in opts.
-    def options_overlap(opts)
-      !(@opts.collect{|k,v| k unless v.nil?}.compact & opts).empty?
-    end
-
-    # Whether this dataset is a simple SELECT * FROM table.
-    def simple_select_all?
-      o = @opts.reject{|k,v| v.nil? || NON_SQL_OPTIONS.include?(k)}
-      o.length == 1 && (f = o[:from]) && f.length == 1 && f.first.is_a?(Symbol)
-    end
-
-    private
-    
-    # Set the server to use to :default unless it is already set in the passed opts
-    def default_server_opts(opts)
-      {:server=>@opts[:server] || :default}.merge(opts)
-    end
-
-    # Modify the identifier returned from the database based on the
-    # identifier_output_method.
-    def input_identifier(v)
-      (i = identifier_input_method) ? v.to_s.send(i) : v.to_s
-    end
-
-    # Modify the receiver with the results of sending the meth, args, and block
-    # to the receiver and merging the options of the resulting dataset into
-    # the receiver's options.
-    def mutation_method(meth, *args, &block)
-      copy = send(meth, *args, &block)
-      @opts.merge!(copy.opts)
-      self
-    end
-    
-    # Modify the identifier returned from the database based on the
-    # identifier_output_method.
-    def output_identifier(v)
-      v = 'untitled' if v == ''
-      (i = identifier_output_method) ? v.to_s.send(i).to_sym : v.to_sym
-    end
-
-    # This is run inside .all, after all of the records have been loaded
-    # via .each, but before any block passed to all is called.  It is called with
-    # a single argument, an array of all returned records.  Does nothing by
-    # default, added to make the model eager loading code simpler.
-    def post_load(all_records)
-    end
   end
+  
+  require(%w"query actions features graph prepared_statements misc mutation sql", 'dataset')
 end

data/lib/sequel/dataset/actions.rb

@@ -1,10 +1,33 @@
 module Sequel
   class Dataset
+    # ---------------------
+    # :section: Methods that execute code on the database
+    # These methods all execute the dataset's SQL on the database.
+    # They don't return modified datasets, so if used in a method chain
+    # they should be the last method called.
+    # ---------------------
+    
     # Alias for insert, but not aliased directly so subclasses
     # don't have to override both methods.
     def <<(*args)
       insert(*args)
     end
+    
+    # Returns the first record matching the conditions. Examples:
+    #
+    #   ds[:id=>1] => {:id=1}
+    def [](*conditions)
+      raise(Error, ARRAY_ACCESS_ERROR_MSG) if (conditions.length == 1 and conditions.first.is_a?(Integer)) or conditions.length == 0
+      first(*conditions)
+    end
+
+    # Update all records matching the conditions
+    # with the values specified. Examples:
+    #
+    #   ds[:id=>1] = {:id=>2} # SQL: UPDATE ... SET id = 2 WHERE id = 1
+    def []=(conditions, values)
+      filter(conditions).update(values)
+    end
 
     # Returns an array with all records in the dataset. If a block is given,
     # the array is iterated over after all items have been loaded.
@@ -15,6 +38,11 @@ module Sequel
       a.each(&block) if block
       a
     end
+    
+    # Returns the average value for the given column.
+    def avg(column)
+      aggregate_dataset.get{avg(column)}
+    end
   
     # Returns the columns in the result set in order.
     # If the columns are currently cached, returns the cached value. Otherwise,
@@ -32,7 +60,7 @@ module Sequel
       @columns = ds.instance_variable_get(:@columns)
       @columns || []
     end
-    
+        
     # Remove the cached list of columns and do a SELECT query to find
     # the columns.
     def columns!
@@ -40,6 +68,11 @@ module Sequel
       columns
     end
     
+    # Returns the number of records in the dataset.
+    def count
+      aggregate_dataset.get{COUNT(:*){}.as(count)}.to_i
+    end
+    
     # Deletes the records in the dataset.  The returned value is generally the
     # number of records deleted, but that is adapter dependent.  See delete_sql.
     def delete
@@ -62,12 +95,102 @@ module Sequel
       end
       self
     end
+    
+    # Returns true if no records exist in the dataset, false otherwise
+    def empty?
+      get(1).nil?
+    end
 
     # Executes a select query and fetches records, passing each record to the
     # supplied block.  The yielded records should be hashes with symbol keys.
     def fetch_rows(sql, &block)
       raise NotImplementedError, NOTIMPL_MSG
     end
+    
+    # If a integer argument is
+    # given, it is interpreted as a limit, and then returns all 
+    # matching records up to that limit.  If no argument is passed,
+    # it returns the first matching record.  If any other type of
+    # argument(s) is passed, it is given to filter and the
+    # first matching record is returned. If a block is given, it is used
+    # to filter the dataset before returning anything.  Examples:
+    # 
+    #   ds.first => {:id=>7}
+    #   ds.first(2) => [{:id=>6}, {:id=>4}]
+    #   ds.order(:id).first(2) => [{:id=>1}, {:id=>2}]
+    #   ds.first(:id=>2) => {:id=>2}
+    #   ds.first("id = 3") => {:id=>3}
+    #   ds.first("id = ?", 4) => {:id=>4}
+    #   ds.first{|o| o.id > 2} => {:id=>5}
+    #   ds.order(:id).first{|o| o.id > 2} => {:id=>3}
+    #   ds.first{|o| o.id > 2} => {:id=>5}
+    #   ds.first("id > ?", 4){|o| o.id < 6} => {:id=>5}
+    #   ds.order(:id).first(2){|o| o.id < 2} => [{:id=>1}]
+    def first(*args, &block)
+      ds = block ? filter(&block) : self
+
+      if args.empty?
+        ds.single_record
+      else
+        args = (args.size == 1) ? args.first : args
+        if Integer === args
+          ds.limit(args).all
+        else
+          ds.filter(args).single_record
+        end
+      end
+    end
+
+    # Return the column value for the first matching record in the dataset.
+    # Raises an error if both an argument and block is given.
+    #
+    #   ds.get(:id)
+    #   ds.get{|o| o.sum(:id)}
+    def get(column=nil, &block)
+      if column
+        raise(Error, ARG_BLOCK_ERROR_MSG) if block
+        select(column).single_value
+      else
+        select(&block).single_value
+      end
+    end
+    
+    # Inserts multiple records into the associated table. This method can be
+    # to efficiently insert a large amounts of records into a table. Inserts
+    # are automatically wrapped in a transaction.
+    # 
+    # This method is called with a columns array and an array of value arrays:
+    #
+    #   dataset.import([:x, :y], [[1, 2], [3, 4]])
+    #
+    # This method also accepts a dataset instead of an array of value arrays:
+    #
+    #   dataset.import([:x, :y], other_dataset.select(:a___x, :b___y))
+    #
+    # The method also accepts a :slice or :commit_every option that specifies
+    # the number of records to insert per transaction. This is useful especially
+    # when inserting a large number of records, e.g.:
+    #
+    #   # this will commit every 50 records
+    #   dataset.import([:x, :y], [[1, 2], [3, 4], ...], :slice => 50)
+    def import(columns, values, opts={})
+      return @db.transaction{insert(columns, values)} if values.is_a?(Dataset)
+
+      return if values.empty?
+      raise(Error, IMPORT_ERROR_MSG) if columns.empty?
+      
+      if slice_size = opts[:commit_every] || opts[:slice]
+        offset = 0
+        loop do
+          @db.transaction(opts){multi_insert_sql(columns, values[offset, slice_size]).each{|st| execute_dui(st)}}
+          offset += slice_size
+          break if offset >= values.length
+        end
+      else
+        statements = multi_insert_sql(columns, values)
+        @db.transaction{statements.each{|st| execute_dui(st)}}
+      end
+    end
   
     # Inserts values into the associated table.  The returned value is generally
     # the value of the primary key for the inserted row, but that is adapter dependent.
@@ -75,12 +198,168 @@ module Sequel
     def insert(*values)
       execute_insert(insert_sql(*values))
     end
+    
+    # Inserts multiple values. If a block is given it is invoked for each
+    # item in the given array before inserting it.  See #multi_insert as
+    # a possible faster version that inserts multiple records in one
+    # SQL statement.
+    def insert_multiple(array, &block)
+      if block
+        array.each {|i| insert(block[i])}
+      else
+        array.each {|i| insert(i)}
+      end
+    end
+    
+    # Returns the interval between minimum and maximum values for the given 
+    # column.
+    def interval(column)
+      aggregate_dataset.get{max(column) - min(column)}
+    end
+
+    # Reverses the order and then runs first.  Note that this
+    # will not necessarily give you the last record in the dataset,
+    # unless you have an unambiguous order.  If there is not
+    # currently an order for this dataset, raises an Error.
+    def last(*args, &block)
+      raise(Error, 'No order specified') unless @opts[:order]
+      reverse.first(*args, &block)
+    end
+    
+    # Maps column values for each record in the dataset (if a column name is
+    # given), or performs the stock mapping functionality of Enumerable. 
+    # Raises an error if both an argument and block are given. Examples:
+    #
+    #   ds.map(:id) => [1, 2, 3, ...]
+    #   ds.map{|r| r[:id] * 2} => [2, 4, 6, ...]
+    def map(column=nil, &block)
+      if column
+        raise(Error, ARG_BLOCK_ERROR_MSG) if block
+        super(){|r| r[column]}
+      else
+        super(&block)
+      end
+    end
+
+    # Returns the maximum value for the given column.
+    def max(column)
+      aggregate_dataset.get{max(column)}
+    end
+
+    # Returns the minimum value for the given column.
+    def min(column)
+      aggregate_dataset.get{min(column)}
+    end
+
+    # This is a front end for import that allows you to submit an array of
+    # hashes instead of arrays of columns and values:
+    # 
+    #   dataset.multi_insert([{:x => 1}, {:x => 2}])
+    #
+    # Be aware that all hashes should have the same keys if you use this calling method,
+    # otherwise some columns could be missed or set to null instead of to default
+    # values.
+    #
+    # You can also use the :slice or :commit_every option that import accepts.
+    def multi_insert(hashes, opts={})
+      return if hashes.empty?
+      columns = hashes.first.keys
+      import(columns, hashes.map{|h| columns.map{|c| h[c]}}, opts)
+    end
+
+    # Returns a Range object made from the minimum and maximum values for the
+    # given column.
+    def range(column)
+      if r = aggregate_dataset.select{[min(column).as(v1), max(column).as(v2)]}.first
+        (r[:v1]..r[:v2])
+      end
+    end
+    
+    # Returns a hash with key_column values as keys and value_column values as
+    # values.  Similar to to_hash, but only selects the two columns.
+    def select_hash(key_column, value_column)
+      select(key_column, value_column).to_hash(hash_key_symbol(key_column), hash_key_symbol(value_column))
+    end
+    
+    # Selects the column given (either as an argument or as a block), and
+    # returns an array of all values of that column in the dataset.  If you
+    # give a block argument that returns an array with multiple entries,
+    # the contents of the resulting array are undefined.
+    def select_map(column=nil, &block)
+      ds = naked.ungraphed
+      ds = if column
+        raise(Error, ARG_BLOCK_ERROR_MSG) if block
+        ds.select(column)
+      else
+        ds.select(&block)
+      end
+      ds.map{|r| r.values.first}
+    end
+    
+    # The same as select_map, but in addition orders the array by the column.
+    def select_order_map(column=nil, &block)
+      ds = naked.ungraphed
+      ds = if column
+        raise(Error, ARG_BLOCK_ERROR_MSG) if block
+        ds.select(column).order(unaliased_identifier(column))
+      else
+        ds.select(&block).order(&block)
+      end
+      ds.map{|r| r.values.first}
+    end
   
     # Alias for update, but not aliased directly so subclasses
     # don't have to override both methods.
     def set(*args)
       update(*args)
     end
+    
+    # Returns the first record in the dataset.
+    def single_record
+      clone(:limit=>1).each{|r| return r}
+      nil
+    end
+
+    # Returns the first value of the first record in the dataset.
+    # Returns nil if dataset is empty.
+    def single_value
+      if r = naked.ungraphed.single_record
+        r.values.first
+      end
+    end
+    
+    # Returns the sum for the given column.
+    def sum(column)
+      aggregate_dataset.get{sum(column)}
+    end
+
+    # Returns a string in CSV format containing the dataset records. By 
+    # default the CSV representation includes the column titles in the
+    # first line. You can turn that off by passing false as the 
+    # include_column_titles argument.
+    #
+    # This does not use a CSV library or handle quoting of values in
+    # any way.  If any values in any of the rows could include commas or line
+    # endings, you shouldn't use this.
+    def to_csv(include_column_titles = true)
+      n = naked
+      cols = n.columns
+      csv = ''
+      csv << "#{cols.join(COMMA_SEPARATOR)}\r\n" if include_column_titles
+      n.each{|r| csv << "#{cols.collect{|c| r[c]}.join(COMMA_SEPARATOR)}\r\n"}
+      csv
+    end
+    
+    # Returns a hash with one column used as key and another used as value.
+    # If rows have duplicate values for the key column, the latter row(s)
+    # will overwrite the value of the previous row(s). If the value_column
+    # is not given or nil, uses the entire hash as the value.
+    def to_hash(key_column, value_column = nil)
+      inject({}) do |m, r|
+        m[r[key_column]] = value_column ? r[value_column] : r
+        m
+      end
+    end
 
     # Truncates the dataset.  Returns nil.
     def truncate
@@ -94,6 +373,11 @@ module Sequel
     end
 
     private
+    
+    # Set the server to use to :default unless it is already set in the passed opts
+    def default_server_opts(opts)
+      {:server=>@opts[:server] || :default}.merge(opts)
+    end
 
     # Execute the given SQL on the database using execute.
     def execute(sql, opts={}, &block)
@@ -115,5 +399,43 @@ module Sequel
     def execute_insert(sql, opts={}, &block)
       @db.execute_insert(sql, default_server_opts(opts), &block)
     end
+    
+    # Return a plain symbol given a potentially qualified or aliased symbol,
+    # specifying the symbol that is likely to be used as the hash key
+    # for the column when records are returned.
+    def hash_key_symbol(s)
+      raise(Error, "#{s.inspect} is not a symbol") unless s.is_a?(Symbol)
+      _, c, a = split_symbol(s)
+      (a || c).to_sym
+    end
+    
+    # Modify the identifier returned from the database based on the
+    # identifier_output_method.
+    def output_identifier(v)
+      v = 'untitled' if v == ''
+      (i = identifier_output_method) ? v.to_s.send(i).to_sym : v.to_sym
+    end
+    
+    # This is run inside .all, after all of the records have been loaded
+    # via .each, but before any block passed to all is called.  It is called with
+    # a single argument, an array of all returned records.  Does nothing by
+    # default, added to make the model eager loading code simpler.
+    def post_load(all_records)
+    end
+
+    # Return the unaliased part of the identifier.  Handles both
+    # implicit aliases in symbols, as well as SQL::AliasedExpression
+    # objects.  Other objects are returned as is.
+    def unaliased_identifier(c)
+      case c
+      when Symbol
+        c_table, column, _ = split_symbol(c)
+        c_table ? column.to_sym.qualify(c_table) : column.to_sym
+      when SQL::AliasedExpression
+        c.expression
+      else
+        c
+      end
+    end
   end
 end