sequel 3.21.0 → 3.36.0

data/lib/sequel/dataset/features.rb

@@ -1,17 +1,20 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Methods that describe what the dataset supports
+    # :section: 4 - Methods that describe what the dataset supports
     # These methods all return booleans, with most describing whether or not the
     # dataset supports a feature.
     # ---------------------
     
-    # Method used to check if WITH is supported
-    WITH_SUPPORTED=:select_with_sql
-    
     # Whether this dataset quotes identifiers.
     def quote_identifiers?
-      @quote_identifiers
+      if defined?(@quote_identifiers)
+        @quote_identifiers
+      elsif db.respond_to?(:quote_identifiers?)
+        @quote_identifiers = db.quote_identifiers?
+      else
+        @quote_identifiers = false
+      end
     end
     
     # Whether this dataset will provide accurate number of rows matched for
@@ -21,22 +24,59 @@ module Sequel
       true
     end
     
+    # Whether you must use a column alias list for recursive CTEs (false by
+    # default).
+    def recursive_cte_requires_column_aliases?
+      false
+    end
+
     # Whether the dataset requires SQL standard datetimes (false by default,
     # as most allow strings with ISO 8601 format).
     def requires_sql_standard_datetimes?
       false
     end
 
+    # Whether type specifiers are required for prepared statement/bound
+    # variable argument placeholders (i.e. :bv__integer)
+    def requires_placeholder_type_specifiers?
+      false
+    end
+
     # Whether the dataset supports common table expressions (the WITH clause).
-    def supports_cte?
-      select_clause_methods.include?(WITH_SUPPORTED)
+    # If given, +type+ can be :select, :insert, :update, or :delete, in which case it
+    # determines whether WITH is supported for the respective statement type.
+    def supports_cte?(type=:select)
+      send(:"#{type}_clause_methods").include?(:"#{type}_with_sql")
+    end
+
+    # Whether the dataset supports common table expressions (the WITH clause)
+    # in subqueries.  If false, applies the WITH clause to the main query, which can cause issues
+    # if multiple WITH clauses use the same name.
+    def supports_cte_in_subqueries?
+      false
     end
 
-    # Whether the dataset supports the DISTINCT ON clause, false by default.
+    # Whether the dataset supports or can emulate the DISTINCT ON clause, false by default.
     def supports_distinct_on?
       false
     end
 
+    # Whether the dataset supports CUBE with GROUP BY.
+    def supports_group_cube?
+      false
+    end
+
+    # Whether the dataset supports ROLLUP with GROUP BY.
+    def supports_group_rollup?
+      false
+    end
+
+    # Whether this dataset supports the +insert_select+ method for returning all columns values
+    # directly from an insert query.
+    def supports_insert_select?
+      supports_returning?(:insert)
+    end
+
     # Whether the dataset supports the INTERSECT and EXCEPT compound operations, true by default.
     def supports_intersect_except?
       true
@@ -67,7 +107,24 @@ module Sequel
     def supports_multiple_column_in?
       true
     end
+
+    # Whether the dataset supports or can fully emulate the DISTINCT ON clause,
+    # including respecting the ORDER BY clause, false by default
+    def supports_ordered_distinct_on?
+      supports_distinct_on?
+    end
     
+    # Whether the RETURNING clause is supported for the given type of query.
+    # +type+ can be :insert, :update, or :delete.
+    def supports_returning?(type)
+      send(:"#{type}_clause_methods").include?(:"#{type}_returning_sql")
+    end
+
+    # Whether the database supports SELECT *, column FROM table
+    def supports_select_all_and_column?
+      true
+    end
+
     # Whether the dataset supports timezones in literal timestamps
     def supports_timestamp_timezones?
       false
@@ -82,5 +139,36 @@ module Sequel
     def supports_window_functions?
       false
     end
+    
+    # Whether the dataset supports WHERE TRUE (or WHERE 1 for databases that
+    # that use 1 for true).
+    def supports_where_true?
+      true
+    end
+
+    private
+
+    # Whether insert(nil) or insert({}) must be emulated by
+    # using at least one value, false by default.
+    def insert_supports_empty_values?
+      true
+    end
+
+    # Whether using an offset returns an extra row number column that should be
+    # eliminated, false by default.
+    def offset_returns_row_number_column?
+      false
+    end
+
+    # Whether the RETURNING clause is used for the given dataset.
+    # +type+ can be :insert, :update, or :delete.
+    def uses_returning?(type)
+      opts[:returning] && !@opts[:sql] && supports_returning?(type)
+    end
+    
+    # Whether the dataset uses WITH ROLLUP/CUBE instead of ROLLUP()/CUBE().
+    def uses_with_rollup?
+      false
+    end
   end
 end

data/lib/sequel/dataset/graph.rb

@@ -1,7 +1,7 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Methods related to dataset graphing
+    # :section: 5 - Methods related to dataset graphing
     # Dataset graphing changes the dataset to yield hashes where keys are table
     # name symbols and values are hashes representing the columns related to
     # that table.  All of these methods return modified copies of the receiver.
@@ -115,7 +115,11 @@ module Sequel
       add_columns = !ds.opts.include?(:graph_aliases)
 
       # Setup the initial graph data structure if it doesn't exist
-      unless graph = opts[:graph]
+      if graph = opts[:graph]
+        opts[:graph] = graph = graph.dup
+        select = opts[:select].dup
+        [:column_aliases, :table_aliases, :column_alias_num].each{|k| graph[k] = graph[k].dup}
+      else
         master = alias_symbol(ds.first_source_alias)
         raise_alias_error.call if master == table_alias
         # Master hash storing all .graph related information
@@ -130,10 +134,33 @@ module Sequel
         # aliased, but are not included if set_graph_aliases
         # has been used.
         if add_columns
-          select = opts[:select] = []
-          columns.each do |column|
-            column_aliases[column] = [master, column]
-            select.push(SQL::QualifiedIdentifier.new(master, column))
+          if (select = @opts[:select]) && !select.empty? && !(select.length == 1 && (select.first.is_a?(SQL::ColumnAll)))
+            select = select.each do |sel|
+              column = case sel
+              when Symbol
+                _, c, a = split_symbol(sel)
+                (a || c).to_sym
+              when SQL::Identifier
+                sel.value.to_sym
+              when SQL::QualifiedIdentifier
+                column = sel.column
+                column = column.value if column.is_a?(SQL::Identifier)
+                column.to_sym
+              when SQL::AliasedExpression
+                column = sel.aliaz
+                column = column.value if column.is_a?(SQL::Identifier)
+                column.to_sym
+              else
+                raise Error, "can't figure out alias to use for graphing for #{sel.inspect}"
+              end
+              column_aliases[column] = [master, column]
+            end
+            select = qualified_expression(select, master)
+          else
+            select = columns.map do |column|
+              column_aliases[column] = [master, column]
+              SQL::QualifiedIdentifier.new(master, column)
+            end
           end
         end
       end
@@ -147,7 +174,6 @@ module Sequel
 
       # Add the columns to the selection unless we are ignoring them
       if add_table && add_columns
-        select = opts[:select]
         column_aliases = graph[:column_aliases]
         ca_num = graph[:column_alias_num]
         # Which columns to add to the result set
@@ -165,15 +191,16 @@ module Sequel
               column_alias = :"#{column_alias}_#{column_alias_num}" 
               ca_num[column_alias] += 1
             end
-            [column_alias, SQL::QualifiedIdentifier.new(table_alias, column).as(column_alias)]
+            [column_alias, SQL::AliasedExpression.new(SQL::QualifiedIdentifier.new(table_alias, column), column_alias)]
           else
-            [column, SQL::QualifiedIdentifier.new(table_alias, column)]
+            ident = SQL::QualifiedIdentifier.new(table_alias, column)
+            [column, ident]
           end
           column_aliases[col_alias] = [table_alias, column]
           select.push(identifier)
         end
       end
-      ds
+      add_columns ? ds.select(*select) : ds
     end
 
     # This allows you to manually specify the graph aliases to use
@@ -225,7 +252,7 @@ module Sequel
         column ||= col_alias
         gas[col_alias] = [table, column]
         identifier = value || SQL::QualifiedIdentifier.new(table, column)
-        identifier = SQL::AliasedExpression.new(identifier, col_alias) if value or column != col_alias
+        identifier = SQL::AliasedExpression.new(identifier, col_alias) if value || column != col_alias
         identifier
       end
       [identifiers, gas]

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,12 +1,12 @@
 module Sequel
   class Dataset
     # ---------------------
-    # :section: Mutation methods
+    # :section: 7 - Mutation methods
     # These methods modify the receiving dataset and should be used with care.
     # ---------------------
     
     # All methods that should have a ! method added that modifies the receiver.
-    MUTATION_METHODS = QUERY_METHODS
+    MUTATION_METHODS = QUERY_METHODS - [:paginate, :naked]
     
     # Setup mutation (e.g. filter!) methods.  These operate the same as the
     # non-! methods, but replace the options of the current dataset with the
@@ -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.
@@ -40,6 +39,12 @@ module Sequel
         instance_eval("def #{meth}!(*args, &block); mutation_method(:#{meth}, *args, &block) end", __FILE__, __LINE__)
       end
     end
+
+    # Remove the row_proc from the current dataset.
+    def naked!
+      self.row_proc = nil
+      self
+    end
     
     private
     

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].
     # ---------------------
@@ -12,15 +12,12 @@ module Sequel
     # native database support for bind variables and prepared
     # statements (as opposed to the emulated ones used by default).
     module ArgumentMapper
-      SQL_QUERY_TYPE = Hash.new{|h,k| h[k] = k}
-      SQL_QUERY_TYPE[:first] = SQL_QUERY_TYPE[:all] = :select
-      
       # The name of the prepared statement, if any.
       attr_accessor :prepared_statement_name
       
       # The bind arguments to use for running this prepared statement
       attr_accessor :bind_arguments
-      
+
       # Set the bind arguments based on the hash and call super.
       def call(bind_vars={}, &block)
         ds = bind(bind_vars)
@@ -35,16 +32,9 @@ 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
-      
-      private
-      
-      # The type of query (:select, :insert, :delete, :update).
-      def sql_query_type
-        SQL_QUERY_TYPE[@prepared_type]
-      end
     end
 
     # Backbone of the prepared statement support.  Grafts bind variable
@@ -56,6 +46,10 @@ module Sequel
     module PreparedStatementMethods
       PLACEHOLDER_RE = /\A\$(.*)\z/
       
+      # Whether to log the full SQL query.  By default, just the prepared statement
+      # name is generally logged on adapters that support native prepared statements.
+      attr_accessor :log_sql
+      
       # The type of prepared statement, should be one of :select, :first,
       # :insert, :update, or :delete
       attr_accessor :prepared_type
@@ -63,6 +57,9 @@ module Sequel
       # The array/hash of bound variable placeholder names.
       attr_accessor :prepared_args
       
+      # The dataset that created this prepared statement.
+      attr_accessor :orig_dataset
+      
       # The argument to supply to insert and update, which may use
       # placeholders specified by prepared_args
       attr_accessor :prepared_modify_values
@@ -72,31 +69,46 @@ module Sequel
       def call(bind_vars={}, &block)
         bind(bind_vars).run(&block)
       end
+
+      # Send the columns to the original dataset, as calling it
+      # on the prepared statement can cause problems.
+      def columns
+        orig_dataset.columns
+      end
       
       # Returns the SQL for the prepared statement, depending on
       # the type of the statement and the prepared_modify_values.
       def prepared_sql
         case @prepared_type
-        when :select, :all
+        when :select, :all, :each
+          # Most common scenario, so listed first.
           select_sql
         when :first
           clone(:limit=>1).select_sql
+        when :insert_select
+          returning.insert_sql(*@prepared_modify_values)
         when :insert
           insert_sql(*@prepared_modify_values)
         when :update
           update_sql(*@prepared_modify_values)
         when :delete
           delete_sql
+        else
+          select_sql
         end
       end
       
       # Changes the values of symbols if they start with $ and
       # prepared_args is present.  If so, they are considered placeholders,
       # and they are substituted using prepared_arg.
-      def literal_symbol(v)
+      def literal_symbol_append(sql, 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
+          if prepared_arg?(s)
+            literal_append(sql, prepared_arg(s))
+          else
+            sql << v.to_s
+          end
         else
           super
         end
@@ -117,7 +129,12 @@ module Sequel
       def run(&block)
         case @prepared_type
         when :select, :all
+          # Most common scenario, so listed first
           all(&block)
+        when :each
+          each(&block)
+        when :insert_select
+          with_sql(prepared_sql).first
         when :first
           first
         when :insert
@@ -126,6 +143,13 @@ module Sequel
           update(*@prepared_modify_values)
         when :delete
           delete
+        when Array
+          case @prepared_type.at(0)
+          when :map, :to_hash, :to_hash_groups
+            send(*@prepared_type, &block) 
+          end
+        else
+          all(&block)
         end
       end
       
@@ -136,11 +160,16 @@ 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.
-      def subselect_sql(ds)
-        ps = ds.prepare(:select)
+      def subselect_sql_append(sql, ds)
+        ps = ds.clone(:append_sql=>sql).prepare(:select)
         ps = ps.bind(@opts[:bind_vars]) if @opts[:bind_vars]
         ps.prepared_args = prepared_args
         ps.prepared_sql
@@ -171,6 +200,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 +218,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 +229,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)
     #
@@ -212,7 +249,7 @@ module Sequel
     #   DB.call(:select_by_name, :name=>'Blah') # Same thing
     def prepare(type, name=nil, *values)
       ps = to_prepared_statement(type, values)
-      db.prepared_statements[name] = ps if name
+      db.set_prepared_statement(name, ps) if name
       ps
     end
     
@@ -223,6 +260,7 @@ module Sequel
     def to_prepared_statement(type, values=nil)
       ps = bind
       ps.extend(PreparedStatementMethods)
+      ps.orig_dataset = self
       ps.prepared_type = type
       ps.prepared_modify_values = values
       ps