sequel 3.21.0 → 3.29.0

data/lib/sequel/dataset/misc.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Miscellaneous methods
+    # :section: 6 - Miscellaneous methods
     # These methods don't fit cleanly into another section.
     # ---------------------
     
@@ -23,17 +23,13 @@ module Sequel
     #   DB[:posts]
     #
     # Sequel::Dataset is an abstract class that is not useful by itself. Each
-    # database adaptor provides a subclass of Sequel::Dataset, and has
+    # database adapter provides a subclass of Sequel::Dataset, and has
     # the Database#dataset method return an instance of that subclass.
     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
-    
+
     # Define a hash value such that datasets with the same DB, opts, and SQL
     # will be consider equal.
     def ==(o)
@@ -45,15 +41,6 @@ module Sequel
       self == o
     end
     
-    # 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.
-    #
-    #   DB.from(DB[:table].as(:b)) # SELECT * FROM (SELECT * FROM table) AS b
-    def as(aliaz)
-      ::Sequel::SQL::AliasedExpression.new(self, aliaz)
-    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:
@@ -96,10 +83,10 @@ module Sequel
     # have a table, raises an error.  If the table is aliased, returns the original
     # table, not the alias
     #
-    #   DB[:table].first_source_alias
+    #   DB[:table].first_source_table
     #   # => :table
     #
-    #   DB[:table___t].first_source_alias
+    #   DB[:table___t].first_source_table
     #   # => :table
     def first_source_table
       source = @opts[:from]
@@ -120,16 +107,48 @@ module Sequel
     # Define a hash value such that datasets with the same DB, opts, and SQL
     # will have the same hash value
     def hash
-      [db, opts.sort_by{|k| k.to_s}, sql].hash
+      [db, opts.sort_by{|k, v| k.to_s}, sql].hash
+    end
+    
+    # The String instance method to call on identifiers before sending them to
+    # the database.
+    def identifier_input_method
+      if defined?(@identifier_input_method)
+        @identifier_input_method
+      elsif db.respond_to?(:identifier_input_method)
+        @identifier_input_method = db.identifier_input_method
+      else
+        @identifier_input_method = nil
+      end
+    end
+    
+    # The String instance method to call on identifiers before sending them to
+    # the database.
+    def identifier_output_method
+      if defined?(@identifier_output_method)
+        @identifier_output_method
+      elsif db.respond_to?(:identifier_output_method)
+        @identifier_output_method = db.identifier_output_method
+      else
+        @identifier_output_method = nil
+      end
     end
     
     # Returns a string representation of the dataset including the class name 
     # and the corresponding SQL select statement.
     def inspect
-      "#<#{self.class}: #{sql.inspect}>"
+      c = self.class
+      c = c.superclass while c.name.nil? || c.name == ''
+      "#<#{c.name}: #{sql.inspect}>"
     end
     
-    # Splits a possible implicit alias in C, handling both SQL::AliasedExpressions
+    # The alias to use for the row_number column, used when emulating OFFSET
+    # support and for eager limit strategies
+    def row_number_column
+      :x_sequel_row_number_x
+    end
+
+    # Splits a possible implicit alias in +c+, handling both SQL::AliasedExpressions
     # and Symbols.  Returns an array of two elements, with the first being the
     # main expression, and the second being the alias.
     def split_alias(c)
@@ -139,6 +158,8 @@ module Sequel
         [c_table ? SQL::QualifiedIdentifier.new(c_table, column.to_sym) : column.to_sym, aliaz]
       when SQL::AliasedExpression
         [c.expression, c.aliaz]
+      when SQL::JoinClause
+        [c.table, c.table_alias]
       else
         [c, nil]
       end
@@ -151,6 +172,10 @@ module Sequel
     # used, where N is an integer starting at 0 and increasing until an
     # unused one is found.
     #
+    # You can provide a second addition array argument containing symbols
+    # that should not be considered valid table aliases.  The current aliases
+    # for the FROM and JOIN tables are automatically included in this array.
+    #
     #   DB[:table].unused_table_alias(:t)
     #   # => :t
     #
@@ -159,9 +184,11 @@ module Sequel
     #
     #   DB[:table, :table_0].unused_table_alias(:table)
     #   # => :table_1
-    def unused_table_alias(table_alias)
+    #
+    #   DB[:table, :table_0].unused_table_alias(:table, [:table_1, :table_2])
+    #   # => :table_3
+    def unused_table_alias(table_alias, used_aliases = [])
       table_alias = alias_symbol(table_alias)
-      used_aliases = []
       used_aliases += opts[:from].map{|t| alias_symbol(t)} if opts[:from]
       used_aliases += opts[:join].map{|j| j.table_alias ? alias_alias_symbol(j.table_alias) : alias_symbol(j.table)} if opts[:join]
       if used_aliases.include?(table_alias)

data/lib/sequel/dataset/mutation.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Mutation methods
+    # :section: 7 - Mutation methods
     # These methods modify the receiving dataset and should be used with care.
     # ---------------------
     
@@ -21,17 +21,16 @@ module Sequel
     def_mutation_method(*MUTATION_METHODS)
     
     # Set the method to call on identifiers going into the database for this dataset
-    attr_accessor :identifier_input_method
+    attr_writer :identifier_input_method
     
     # Set the method to call on identifiers coming the database for this dataset
-    attr_accessor :identifier_output_method
+    attr_writer :identifier_output_method
 
     # 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.
+    # The row_proc for this database, should be any object that responds to +call+ with
+    # a single hash argument and returns the object you want #each to return.
     attr_accessor :row_proc
     
     # Add a mutation method to this dataset instance.

data/lib/sequel/dataset/prepared_statements.rb

@@ -1,7 +1,7 @@
 module Sequel 
   class Dataset
     # ---------------------
-    # :section: Methods related to prepared statements or bound variables
+    # :section: 8 - Methods related to prepared statements or bound variables
     # On some adapters, these use native prepared statements and bound variables, on others
     # support is emulated.  For details, see the {"Prepared Statements/Bound Variables" guide}[link:files/doc/prepared_statements_rdoc.html].
     # ---------------------
@@ -35,7 +35,7 @@ module Sequel
         return @prepared_sql if @prepared_sql
         @prepared_args ||= []
         @prepared_sql = super
-        meta_def("#{sql_query_type}_sql"){|*args| prepared_sql}
+        @opts[:sql] = @prepared_sql
         @prepared_sql
       end
       
@@ -80,7 +80,9 @@ module Sequel
         when :select, :all
           select_sql
         when :first
-          clone(:limit=>1).select_sql
+          limit(1).select_sql
+        when :insert_select
+          returning.insert_sql(*@prepared_modify_values)
         when :insert
           insert_sql(*@prepared_modify_values)
         when :update
@@ -95,8 +97,8 @@ module Sequel
       # and they are substituted using prepared_arg.
       def literal_symbol(v)
         if @opts[:bind_vars] and match = PLACEHOLDER_RE.match(v.to_s)
-          v2 = prepared_arg(match[1].to_sym)
-          v2 ? literal(v2) : v
+          s = match[1].to_sym
+          prepared_arg?(s) ? literal(prepared_arg(s)) : v
         else
           super
         end
@@ -118,6 +120,8 @@ module Sequel
         case @prepared_type
         when :select, :all
           all(&block)
+        when :insert_select
+          with_sql(prepared_sql).first
         when :first
           first
         when :insert
@@ -136,6 +140,11 @@ module Sequel
         @opts[:bind_vars][k]
       end
 
+      # Whether there is a bound value for the given key.
+      def prepared_arg?(k)
+        @opts[:bind_vars].has_key?(k)
+      end
+
       # Use a clone of the dataset extended with prepared statement
       # support and using the same argument hash so that you can use
       # bind variables/prepared arguments in subselects.
@@ -171,6 +180,11 @@ module Sequel
         prepared_args << k
         prepared_arg_placeholder
       end
+      
+      # Always assume there is a prepared arg in the argument mapper.
+      def prepared_arg?(k)
+        true
+      end
     end
     
     # Set the bind variables to use for the call.  If bind variables have
@@ -184,11 +198,9 @@ module Sequel
       clone(:bind_vars=>@opts[:bind_vars] ? @opts[:bind_vars].merge(bind_vars) : bind_vars)
     end
     
-    # For the given type (:select, :insert, :update, or :delete),
-    # run the sql with the bind variables
-    # specified in the hash.  values is a hash of passed to
-    # insert or update (if one of those types is used),
-    # which may contain placeholders.
+    # For the given type (:select, :first, :insert, :insert_select, :update, or :delete),
+    # run the sql with the bind variables specified in the hash.  +values+ is a hash passed to
+    # insert or update (if one of those types is used), which may contain placeholders.
     #
     #   DB[:table].filter(:id=>:$id).call(:first, :id=>1)
     #   # SELECT * FROM table WHERE id = ? LIMIT 1 -- (1)
@@ -197,11 +209,16 @@ module Sequel
       prepare(type, nil, *values).call(bind_variables, &block)
     end
     
-    # Prepare an SQL statement for later execution. This returns
-    # a clone of the dataset extended with PreparedStatementMethods,
-    # on which you can call call with the hash of bind variables to
-    # do substitution.  The prepared statement is also stored in
-    # the associated database.  The following usage is identical:
+    # Prepare an SQL statement for later execution.  Takes a type similar to #call,
+    # and the +name+ symbol of the prepared statement.  While +name+ defaults to +nil+,
+    # it should always be provided as a symbol for the name of the prepared statement,
+    # as some databases require that prepared statements have names.
+    #
+    # This returns a clone of the dataset extended with PreparedStatementMethods,
+    # which you can +call+ with the hash of bind variables to use.
+    # The prepared statement is also stored in
+    # the associated database, where it can be called by name.
+    # The following usage is identical:
     #
     #   ps = DB[:table].filter(:name=>:$name).prepare(:first, :select_by_name)
     #