sequel 5.39.0 → 5.72.0

data/lib/sequel/dataset/query.rb

@@ -12,6 +12,10 @@ module Sequel
     # in the extension).
     EXTENSIONS = {}
 
+    # Hash of extension name symbols to modules to load to implement the extension.
+    EXTENSION_MODULES = {}
+    private_constant :EXTENSION_MODULES
+
     EMPTY_ARRAY = [].freeze
 
     # The dataset options that require the removal of cached columns if changed.
@@ -45,12 +49,8 @@ module Sequel
     METHS
 
     # Register an extension callback for Dataset objects.  ext should be the
-    # extension name symbol, and mod should either be a Module that the
-    # dataset is extended with, or a callable object called with the database
-    # object.  If mod is not provided, a block can be provided and is treated
-    # as the mod object.
-    #
-    # If mod is a module, this also registers a Database extension that will
+    # extension name symbol, and mod should be a Module that will be
+    # included in the dataset's class. This also registers a Database extension that will
     # extend all of the database's datasets.
     def self.register_extension(ext, mod=nil, &block)
       if mod
@@ -58,14 +58,20 @@ module Sequel
         if mod.is_a?(Module)
           block = proc{|ds| ds.extend(mod)}
           Sequel::Database.register_extension(ext){|db| db.extend_datasets(mod)}
+          Sequel.synchronize{EXTENSION_MODULES[ext] = mod}
         else
           block = mod
         end
       end
+
+      unless mod.is_a?(Module)
+        Sequel::Deprecation.deprecate("Providing a block or non-module to Sequel::Dataset.register_extension is deprecated and support for it will be removed in Sequel 6.")
+      end
+
       Sequel.synchronize{EXTENSIONS[ext] = block}
     end
 
-    # On Ruby 2.4+, use clone(:freeze=>false) to create clones, because
+    # On Ruby 2.4+, use clone(freeze: false) to create clones, because
     # we use true freezing in that case, and we need to modify the opts
     # in the frozen copy.
     #
@@ -116,7 +122,7 @@ module Sequel
     #  DB[:items].order(:id).distinct(:id) # SQL: SELECT DISTINCT ON (id) * FROM items ORDER BY id
     #  DB[:items].order(:id).distinct{func(:id)} # SQL: SELECT DISTINCT ON (func(id)) * FROM items ORDER BY id
     #
-    # There is support for emualting the DISTINCT ON support in MySQL, but it
+    # There is support for emulating the DISTINCT ON support in MySQL, but it
     # does not support the ORDER of the dataset, and also doesn't work in many
     # cases if the ONLY_FULL_GROUP_BY sql_mode is used, which is the default on
     # MySQL 5.7.5+.
@@ -195,11 +201,15 @@ module Sequel
     if TRUE_FREEZE
       # Return a clone of the dataset loaded with the given dataset extensions.
       # If no related extension file exists or the extension does not have
-      # specific support for Dataset objects, an Error will be raised.
-      def extension(*a)
-        c = _clone(:freeze=>false)
-        c.send(:_extension!, a)
-        c.freeze
+      # specific support for Dataset objects, an error will be raised.
+      def extension(*exts)
+        Sequel.extension(*exts)
+        mods = exts.map{|ext| Sequel.synchronize{EXTENSION_MODULES[ext]}}
+        if mods.all?
+          with_extend(*mods)
+        else
+          with_extend(DeprecatedSingletonClassMethods).extension(*exts)
+        end
       end
     else
       # :nocov:
@@ -508,6 +518,7 @@ module Sequel
     #                            argument.
     #            :implicit_qualifier :: The name to use for qualifying implicit conditions.  By default,
     #                                   the last joined or primary table is used.
+    #            :join_using :: Force the using of JOIN USING, even if +expr+ is not an array of symbols.
     #            :reset_implicit_qualifier :: Can set to false to ignore this join when future joins determine qualifier
     #                                         for implicit conditions.
     #            :qualify :: Can be set to false to not do any implicit qualification.  Can be set
@@ -541,7 +552,7 @@ module Sequel
         return s.join_table(type, ds, expr, options, &block)
       end
 
-      using_join = expr.is_a?(Array) && !expr.empty? && expr.all?{|x| x.is_a?(Symbol)}
+      using_join = options[:join_using] || (expr.is_a?(Array) && !expr.empty? && expr.all?{|x| x.is_a?(Symbol)})
       if using_join && !supports_join_using?
         h = {}
         expr.each{|e| h[e] = e}
@@ -616,7 +627,7 @@ module Sequel
     UNCONDITIONED_JOIN_TYPES.each do |jtype|
       class_eval(<<-END, __FILE__, __LINE__+1)
         def #{jtype}_join(table, opts=Sequel::OPTS)
-          raise(Sequel::Error, '#{jtype}_join does not accept join table blocks') if block_given?
+          raise(Sequel::Error, '#{jtype}_join does not accept join table blocks') if defined?(yield)
           raise(Sequel::Error, '#{jtype}_join 2nd argument should be an options hash, not conditions') unless opts.is_a?(Hash)
           join_table(:#{jtype}, table, nil, opts)
         end
@@ -677,6 +688,56 @@ module Sequel
       clone(:lock => style)
     end
     
+    # Return a dataset with a WHEN MATCHED THEN DELETE clause added to the
+    # MERGE statement.  If a block is passed, treat it as a virtual row and
+    # use it as additional conditions for the match.
+    #
+    #   merge_delete
+    #   # WHEN MATCHED THEN DELETE
+    #
+    #   merge_delete{a > 30}
+    #   # WHEN MATCHED AND (a > 30) THEN DELETE
+    def merge_delete(&block)
+      _merge_when(:type=>:delete, &block)
+    end
+
+    # Return a dataset with a WHEN NOT MATCHED THEN INSERT clause added to the
+    # MERGE statement.  If a block is passed, treat it as a virtual row and
+    # use it as additional conditions for the match.
+    #
+    # The arguments provided can be any arguments that would be accepted by
+    # #insert.
+    #
+    #   merge_insert(i1: :i2, a: Sequel[:b]+11)
+    #   # WHEN NOT MATCHED THEN INSERT (i1, a) VALUES (i2, (b + 11))
+    #
+    #   merge_insert(:i2, Sequel[:b]+11){a > 30}
+    #   # WHEN NOT MATCHED AND (a > 30) THEN INSERT VALUES (i2, (b + 11))
+    def merge_insert(*values, &block)
+      _merge_when(:type=>:insert, :values=>values, &block)
+    end
+    
+    # Return a dataset with a WHEN MATCHED THEN UPDATE clause added to the
+    # MERGE statement.  If a block is passed, treat it as a virtual row and
+    # use it as additional conditions for the match.
+    #
+    #   merge_update(i1: Sequel[:i1]+:i2+10, a: Sequel[:a]+:b+20)
+    #   # WHEN MATCHED THEN UPDATE SET i1 = (i1 + i2 + 10), a = (a + b + 20)
+    #
+    #   merge_update(i1: :i2){a > 30}
+    #   # WHEN MATCHED AND (a > 30) THEN UPDATE SET i1 = i2
+    def merge_update(values, &block)
+      _merge_when(:type=>:update, :values=>values, &block)
+    end
+
+    # Return a dataset with the source and join condition to use for the MERGE statement.
+    #
+    #   merge_using(:m2, i1: :i2)
+    #   # USING m2 ON (i1 = i2)
+    def merge_using(source, join_condition)
+      clone(:merge_using => [source, join_condition].freeze)
+    end
+
     # Returns a cloned dataset without a row_proc.
     #
     #   ds = DB[:items].with_row_proc(:invert.to_proc)
@@ -699,7 +760,7 @@ module Sequel
     end
 
     # Returns a copy of the dataset with a specified order. Can be safely combined with limit.
-    # If you call limit with an offset, it will override override the offset if you've called
+    # If you call limit with an offset, it will override the offset if you've called
     # offset first.
     #
     #   DB[:items].offset(10) # SELECT * FROM items OFFSET 10
@@ -736,7 +797,7 @@ module Sequel
     #   DB[:items].order(Sequel.lit('a + b')) # SELECT * FROM items ORDER BY a + b
     #   DB[:items].order(Sequel[:a] + :b) # SELECT * FROM items ORDER BY (a + b)
     #   DB[:items].order(Sequel.desc(:name)) # SELECT * FROM items ORDER BY name DESC
-    #   DB[:items].order(Sequel.asc(:name, :nulls=>:last)) # SELECT * FROM items ORDER BY name ASC NULLS LAST
+    #   DB[:items].order(Sequel.asc(:name, nulls: :last)) # SELECT * FROM items ORDER BY name ASC NULLS LAST
     #   DB[:items].order{sum(name).desc} # SELECT * FROM items ORDER BY sum(name) DESC
     #   DB[:items].order(nil) # SELECT * FROM items
     def order(*columns, &block)
@@ -806,13 +867,13 @@ module Sequel
     #   DB[:items].returning(nil) # RETURNING NULL
     #   DB[:items].returning(:id, :name) # RETURNING id, name
     #
-    #   DB[:items].returning.insert(:a=>1) do |hash|
+    #   DB[:items].returning.insert(a: 1) do |hash|
     #     # hash for each row inserted, with values for all columns
     #   end
-    #   DB[:items].returning.update(:a=>1) do |hash|
+    #   DB[:items].returning.update(a: 1) do |hash|
     #     # hash for each row updated, with values for all columns
     #   end
-    #   DB[:items].returning.delete(:a=>1) do |hash|
+    #   DB[:items].returning.delete(a: 1) do |hash|
     #     # hash for each row deleted, with values for all columns
     #   end
     def returning(*values)
@@ -1051,7 +1112,7 @@ module Sequel
     # referenced in window functions. See Sequel::SQL::Window for a list of
     # options that can be passed in. Example:
     #
-    #   DB[:items].window(:w, :partition=>:c1, :order=>:c2)
+    #   DB[:items].window(:w, partition: :c1, order: :c2)
     #   # SELECT * FROM items WINDOW w AS (PARTITION BY c1 ORDER BY c2)
     def window(name, opts)
       clone(:window=>((@opts[:window]||EMPTY_ARRAY) + [[name, SQL::Window.new(opts)].freeze]).freeze)
@@ -1059,13 +1120,12 @@ module Sequel
 
     # Add a common table expression (CTE) with the given name and a dataset that defines the CTE.
     # A common table expression acts as an inline view for the query.
+    #
     # Options:
     # :args :: Specify the arguments/columns for the CTE, should be an array of symbols.
     # :recursive :: Specify that this is a recursive CTE
-    #
-    # PostgreSQL Specific Options:
     # :materialized :: Set to false to force inlining of the CTE, or true to force not inlining
-    #                  the CTE (PostgreSQL 12+).
+    #                  the CTE (PostgreSQL 12+/SQLite 3.35+).
     #
     #   DB[:items].with(:items, DB[:syx].where(Sequel[:name].like('A%')))
     #   # WITH items AS (SELECT * FROM syx WHERE (name LIKE 'A%' ESCAPE '\')) SELECT * FROM items
@@ -1081,20 +1141,60 @@ module Sequel
 
     # Add a recursive common table expression (CTE) with the given name, a dataset that
     # defines the nonrecursive part of the CTE, and a dataset that defines the recursive part
-    # of the CTE.  Options:
+    # of the CTE.
+    #
+    # Options:
     # :args :: Specify the arguments/columns for the CTE, should be an array of symbols.
     # :union_all :: Set to false to use UNION instead of UNION ALL combining the nonrecursive and recursive parts.
     #
+    # PostgreSQL 14+ Options:
+    # :cycle :: Stop recursive searching when a cycle is detected. Includes two columns in the
+    #           result of the CTE, a cycle column indicating whether a cycle was detected for
+    #           the current row, and a path column for the path traversed to get to the current
+    #           row.  If given, must be a hash with the following keys:
+    #           :columns :: (required) The column or array of columns to use to detect a cycle.
+    #                       If the value of these columns match columns already traversed, then
+    #                       a cycle is detected, and recursive searching will not traverse beyond
+    #                       the cycle (the CTE will include the row where the cycle was detected).
+    #           :cycle_column :: The name of the cycle column in the output, defaults to :is_cycle.
+    #           :cycle_value :: The value of the cycle column in the output if the current row was
+    #                           detected as a cycle, defaults to true.
+    #           :noncycle_value :: The value of the cycle column in the output if the current row
+    #                              was not detected as a cycle, defaults to false. Only respected
+    #                              if :cycle_value is given.
+    #           :path_column :: The name of the path column in the output, defaults to :path.
+    # :search :: Include an order column in the result of the CTE that allows for breadth or
+    #            depth first searching. If given, must be a hash with the following keys:
+    #            :by :: (required) The column or array of columns to search by.
+    #            :order_column :: The name of the order column in the output, defaults to :ordercol.
+    #            :type :: Set to :breadth to use breadth-first searching (depth-first searching
+    #                     is the default).
+    #
     #   DB[:t].with_recursive(:t,
     #     DB[:i1].select(:id, :parent_id).where(parent_id: nil),
     #     DB[:i1].join(:t, id: :parent_id).select(Sequel[:i1][:id], Sequel[:i1][:parent_id]),
-    #     :args=>[:id, :parent_id])
+    #     args: [:id, :parent_id])
     #   
     #   # WITH RECURSIVE t(id, parent_id) AS (
     #   #   SELECT id, parent_id FROM i1 WHERE (parent_id IS NULL)
     #   #   UNION ALL
     #   #   SELECT i1.id, i1.parent_id FROM i1 INNER JOIN t ON (t.id = i1.parent_id)
     #   # ) SELECT * FROM t
+    #
+    #   DB[:t].with_recursive(:t,
+    #     DB[:i1].where(parent_id: nil),
+    #     DB[:i1].join(:t, id: :parent_id).select_all(:i1),
+    #     search: {by: :id, type: :breadth},
+    #     cycle: {columns: :id, cycle_value: 1, noncycle_value: 2})
+    #     
+    #   # WITH RECURSIVE t AS (
+    #   #     SELECT * FROM i1 WHERE (parent_id IS NULL)
+    #   #     UNION ALL
+    #   #     (SELECT i1.* FROM i1 INNER JOIN t ON (t.id = i1.parent_id))
+    #   #   )
+    #   #   SEARCH BREADTH FIRST BY id SET ordercol
+    #   #   CYCLE id SET is_cycle TO 1 DEFAULT 2 USING path
+    #   # SELECT * FROM t
     def with_recursive(name, nonrecursive, recursive, opts=OPTS)
       raise(Error, 'This dataset does not support common table expressions') unless supports_cte?
       if hoist_cte?(nonrecursive)
@@ -1109,16 +1209,27 @@ module Sequel
     end
     
     if TRUE_FREEZE
-      # Return a clone of the dataset extended with the given modules.
+      # Create a subclass of the receiver's class, and include the given modules
+      # into it. If a block is provided, a DatasetModule is created using the block and
+      # is included into the subclass.  Create an instance of the subclass using the
+      # same db and opts, so that the returned dataset operates similarly to a clone
+      # extended with the given modules.  This approach is used to avoid singleton
+      # classes, which significantly improves performance.
+      #
       # Note that like Object#extend, when multiple modules are provided
-      # as arguments the cloned dataset is extended with the modules in reverse
-      # order.  If a block is provided, a DatasetModule is created using the block and
-      # the clone is extended with that module after any modules given as arguments.
+      # as arguments the subclass includes the modules in reverse order.
       def with_extend(*mods, &block)
-        c = _clone(:freeze=>false)
-        c.extend(*mods) unless mods.empty?
-        c.extend(DatasetModule.new(&block)) if block
-        c.freeze
+        c = Class.new(self.class)
+        c.include(*mods) unless mods.empty?
+        c.include(DatasetModule.new(&block)) if block
+        o = c.freeze.allocate
+        o.instance_variable_set(:@db, @db)
+        o.instance_variable_set(:@opts, @opts)
+        o.instance_variable_set(:@cache, {})
+        if cols = cache_get(:_columns)
+          o.send(:columns=, cols)
+        end
+        o.freeze
       end
     else
       # :nocov:
@@ -1151,7 +1262,7 @@ module Sequel
     #
     # You can also provide a method name and arguments to call to get the SQL:
     #
-    #   DB[:items].with_sql(:insert_sql, :b=>1) # INSERT INTO items (b) VALUES (1)
+    #   DB[:items].with_sql(:insert_sql, b: 1) # INSERT INTO items (b) VALUES (1)
     #
     # Note that datasets that specify custom SQL using this method will generally
     # ignore future dataset methods that modify the SQL used, as specifying custom SQL
@@ -1225,18 +1336,22 @@ module Sequel
 
     private
 
-    # Load the extensions into the receiver, without checking if the receiver is frozen.
-    def _extension!(exts)
-      Sequel.extension(*exts)
-      exts.each do |ext|
-        if pr = Sequel.synchronize{EXTENSIONS[ext]}
-          pr.call(self)
-        else
-          raise(Error, "Extension #{ext} does not have specific support handling individual datasets (try: Sequel.extension #{ext.inspect})")
+    # :nocov:
+    unless TRUE_FREEZE
+      # Load the extensions into the receiver, without checking if the receiver is frozen.
+      def _extension!(exts)
+        Sequel.extension(*exts)
+        exts.each do |ext|
+          if pr = Sequel.synchronize{EXTENSIONS[ext]}
+            pr.call(self)
+          else
+            raise(Error, "Extension #{ext} does not have specific support handling individual datasets (try: Sequel.extension #{ext.inspect})")
+          end
         end
+        self
       end
-      self
     end
+    # :nocov:
 
     # If invert is true, invert the condition.
     def _invert_filter(cond, invert)
@@ -1247,6 +1362,18 @@ module Sequel
       end
     end
 
+    # Append to the current MERGE WHEN clauses.
+    # Mutates the hash to add the conditions, if a virtual row block is passed.
+    def _merge_when(hash, &block)
+      hash[:conditions] = Sequel.virtual_row(&block) if block
+
+      if merge_when = @opts[:merge_when]
+        clone(:merge_when => (merge_when.dup << hash.freeze).freeze)
+      else
+        clone(:merge_when => [hash.freeze].freeze)
+      end
+    end
+
     # Add the given filter condition. Arguments:
     # clause :: Symbol or which SQL clause to effect, should be :where or :having
     # cond :: The filter condition to add