sequel 5.39.0 → 5.72.0

data/lib/sequel/dataset/actions.rb

@@ -19,7 +19,7 @@ module Sequel
     METHS
 
     # The clone options to use when retrieving columns for a dataset.
-    COLUMNS_CLONE_OPTIONS = {:distinct => nil, :limit => 1, :offset=>nil, :where=>nil, :having=>nil, :order=>nil, :row_proc=>nil, :graph=>nil, :eager_graph=>nil}.freeze
+    COLUMNS_CLONE_OPTIONS = {:distinct => nil, :limit => 0, :offset=>nil, :where=>nil, :having=>nil, :order=>nil, :row_proc=>nil, :graph=>nil, :eager_graph=>nil}.freeze
 
     # Inserts the given argument into the database.  Returns self so it
     # can be used safely when chaining:
@@ -127,6 +127,18 @@ module Sequel
     #
     #   DB[:table].delete # DELETE * FROM table
     #   # => 3
+    #
+    # Some databases support using multiple tables in a DELETE query. This requires
+    # multiple FROM tables (JOINs can also be used). As multiple FROM tables use
+    # an implicit CROSS JOIN, you should make sure your WHERE condition uses the
+    # appropriate filters for the FROM tables:
+    #
+    #  DB.from(:a, :b).join(:c, :d=>Sequel[:b][:e]).where{{a[:f]=>b[:g], a[:id]=>c[:h]}}.
+    #    delete
+    #  # DELETE FROM a
+    #  # USING b
+    #  # INNER JOIN c ON (c.d = b.e)
+    #  # WHERE ((a.f = b.g) AND (a.id = c.h))
     def delete(&block)
       sql = delete_sql
       if uses_returning?(:delete)
@@ -162,7 +174,7 @@ module Sequel
     #   # => false
     def empty?
       cached_dataset(:_empty_ds) do
-        single_value_ds.unordered.select(EMPTY_SELECT)
+        (@opts[:sql] ? from_self : self).single_value_ds.unordered.select(EMPTY_SELECT)
       end.single_value!.nil?
     end
 
@@ -313,14 +325,18 @@ module Sequel
     
     # Inserts multiple records into the associated table. This method can be
     # used to efficiently insert a large number of records into a table in a
-    # single query if the database supports it. Inserts
-    # are automatically wrapped in a transaction.
+    # single query if the database supports it. Inserts are automatically
+    # wrapped in a transaction if necessary.
     # 
     # This method is called with a columns array and an array of value arrays:
     #
     #   DB[:table].import([:x, :y], [[1, 2], [3, 4]])
     #   # INSERT INTO table (x, y) VALUES (1, 2) 
-    #   # INSERT INTO table (x, y) VALUES (3, 4) 
+    #   # INSERT INTO table (x, y) VALUES (3, 4)
+    #
+    # or, if the database supports it:
+    #
+    #   # INSERT INTO table (x, y) VALUES (1, 2), (3, 4)
     #
     # This method also accepts a dataset instead of an array of value arrays:
     #
@@ -328,9 +344,13 @@ module Sequel
     #   # INSERT INTO table (x, y) SELECT a, b FROM table2 
     #
     # Options:
-    # :commit_every :: Open a new transaction for every given number of records.
-    #                  For example, if you provide a value of 50, will commit
-    #                  after every 50 records.
+    # :commit_every :: Open a new transaction for every given number of
+    #                  records. For example, if you provide a value of 50,
+    #                  will commit after every 50 records. When a
+    #                  transaction is not required, this option controls
+    #                  the maximum number of values to insert with a single
+    #                  statement; it does not force the use of a
+    #                  transaction.
     # :return :: When this is set to :primary_key, returns an array of
     #            autoincremented primary key values for the rows inserted.
     #            This does not have an effect if +values+ is a Dataset.
@@ -457,6 +477,55 @@ module Sequel
       _aggregate(:max, arg)
     end
 
+    # Execute a MERGE statement, which allows for INSERT, UPDATE, and DELETE
+    # behavior in a single query, based on whether rows from a source table
+    # match rows in the current table, based on the join conditions.
+    #
+    # Unless the dataset uses static SQL, to use #merge, you must first have
+    # called #merge_using to specify the merge source and join conditions.
+    # You will then likely to call one or more of the following methods
+    # to specify MERGE behavior by adding WHEN [NOT] MATCHED clauses:
+    #
+    # * #merge_insert
+    # * #merge_update
+    # * #merge_delete
+    # 
+    # The WHEN [NOT] MATCHED clauses are added to the SQL in the order these
+    # methods were called on the dataset.  If none of these methods are
+    # called, an error is raised.
+    #
+    # Example:
+    #
+    #   DB[:m1]
+    #     merge_using(:m2, i1: :i2).
+    #     merge_insert(i1: :i2, a: Sequel[:b]+11).
+    #     merge_delete{a > 30}.
+    #     merge_update(i1: Sequel[:i1]+:i2+10, a: Sequel[:a]+:b+20).
+    #     merge
+    #
+    # SQL:
+    #
+    #   MERGE INTO m1 USING m2 ON (i1 = i2)
+    #   WHEN NOT MATCHED THEN INSERT (i1, a) VALUES (i2, (b + 11))
+    #   WHEN MATCHED AND (a > 30) THEN DELETE
+    #   WHEN MATCHED THEN UPDATE SET i1 = (i1 + i2 + 10), a = (a + b + 20)
+    #
+    # On PostgreSQL, two additional merge methods are supported, for the
+    # PostgreSQL-specific DO NOTHING syntax.
+    #
+    # * #merge_do_nothing_when_matched
+    # * #merge_do_nothing_when_not_matched
+    #
+    # This method is supported on Oracle, but Oracle's MERGE support is
+    # non-standard, and has the following issues:
+    #
+    # * DELETE clause requires UPDATE clause
+    # * DELETE clause requires a condition
+    # * DELETE clause only affects rows updated by UPDATE clause
+    def merge
+      execute_ddl(merge_sql)
+    end
+
     # Returns the minimum value for the given column/expression.
     # Uses a virtual row block if no argument is given.
     #
@@ -527,7 +596,7 @@ module Sequel
     #   # SELECT * FROM table ORDER BY id LIMIT 1000 OFFSET 1000
     #   # ...
     #
-    #   DB[:table].order(:id).paged_each(:rows_per_fetch=>100){|row| }
+    #   DB[:table].order(:id).paged_each(rows_per_fetch: 100){|row| }
     #   # SELECT * FROM table ORDER BY id LIMIT 100
     #   # SELECT * FROM table ORDER BY id LIMIT 100 OFFSET 100
     #   # ...
@@ -546,7 +615,7 @@ module Sequel
       unless @opts[:order]
         raise Sequel::Error, "Dataset#paged_each requires the dataset be ordered"
       end
-      unless block_given?
+      unless defined?(yield)
         return enum_for(:paged_each, opts)
       end
 
@@ -869,6 +938,19 @@ module Sequel
     #
     #   DB[:table].update(x: Sequel[:x]+1, y: 0) # UPDATE table SET x = (x + 1), y = 0
     #   # => 10
+    #
+    # Some databases support using multiple tables in an UPDATE query. This requires
+    # multiple FROM tables (JOINs can also be used). As multiple FROM tables use
+    # an implicit CROSS JOIN, you should make sure your WHERE condition uses the
+    # appropriate filters for the FROM tables:
+    #
+    #  DB.from(:a, :b).join(:c, :d=>Sequel[:b][:e]).where{{a[:f]=>b[:g], a[:id]=>10}}.
+    #    update(:f=>Sequel[:c][:h])
+    #  # UPDATE a
+    #  # SET f = c.h
+    #  # FROM b
+    #  # INNER JOIN c ON (c.d = b.e)
+    #  # WHERE ((a.f = b.g) AND (a.id = 10))
     def update(values=OPTS, &block)
       sql = update_sql(values)
       if uses_returning?(:update)
@@ -974,18 +1056,19 @@ module Sequel
 
     # Internals of #import.  If primary key values are requested, use
     # separate insert commands for each row.  Otherwise, call #multi_insert_sql
-    # and execute each statement it gives separately.
+    # and execute each statement it gives separately. A transaction is only used
+    # if there are multiple statements to execute.
     def _import(columns, values, opts)
       trans_opts = Hash[opts]
       trans_opts[:server] = @opts[:server]
       if opts[:return] == :primary_key
-        @db.transaction(trans_opts){values.map{|v| insert(columns, v)}}
+        _import_transaction(values, trans_opts){values.map{|v| insert(columns, v)}}
       else
         stmts = multi_insert_sql(columns, values)
-        @db.transaction(trans_opts){stmts.each{|st| execute_dui(st)}}
+        _import_transaction(stmts, trans_opts){stmts.each{|st| execute_dui(st)}}
       end
     end
-  
+
     # Return an array of arrays of values given by the symbols in ret_cols.
     def _select_map_multiple(ret_cols)
       map{|r| r.values_at(*ret_cols)}
@@ -1024,6 +1107,17 @@ module Sequel
       end
     end
     
+    # Use a transaction when yielding to the block if multiple values/statements
+    # are provided. When only a single value or statement is provided, then yield
+    # without using a transaction.
+    def _import_transaction(values, trans_opts, &block)
+      if values.length > 1
+        @db.transaction(trans_opts, &block)
+      else
+        yield
+      end
+    end
+  
     # Internals of +select_hash+ and +select_hash_groups+
     def _select_hash(meth, key_column, value_column, opts=OPTS)
       select(*(key_column.is_a?(Array) ? key_column : [key_column]) + (value_column.is_a?(Array) ? value_column : [value_column])).

data/lib/sequel/dataset/deprecated_singleton_class_methods.rb

@@ -0,0 +1,42 @@
+# frozen-string-literal: true
+
+module Sequel
+  class Dataset
+    # This module implements methods to support deprecated use of extensions registered
+    # not using a module.  In such cases, for backwards compatibility, Sequel has to use
+    # a singleton class for the dataset.
+    module DeprecatedSingletonClassMethods
+      # Load the extension into a clone of the receiver.
+      def extension(*a)
+        c = _clone(:freeze=>false)
+        c.send(:_extension!, a)
+        c.freeze
+      end
+
+      # Extend the cloned of the receiver with the given modules, instead of the default
+      # approach of creating a subclass of the receiver's class and including the modules
+      # into that.
+      def with_extend(*mods, &block)
+        c = _clone(:freeze=>false)
+        c.extend(*mods) unless mods.empty?
+        c.extend(DatasetModule.new(&block)) if block
+        c.freeze
+      end
+
+      private
+
+      # Load the extensions into the receiver.
+      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
+    end
+  end
+end

data/lib/sequel/dataset/features.rb

@@ -51,6 +51,11 @@ module Sequel
       false
     end
 
+    # Whether deleting from joined datasets is supported, false by default.
+    def supports_deleting_joins?
+      supports_modifying_joins?
+    end
+    
     # Whether the database supports derived column lists (e.g.
     # "table_expr AS table_alias(column_alias1, column_alias2, ...)"), true by
     # default.
@@ -120,6 +125,11 @@ module Sequel
       false
     end
 
+    # Whether the MERGE statement is supported, false by default.
+    def supports_merge?
+      false
+    end
+
     # Whether modifying joined datasets is supported, false by default.
     def supports_modifying_joins?
       false
@@ -142,6 +152,11 @@ module Sequel
       supports_distinct_on?
     end
     
+    # Whether placeholder literalizers are supported, true by default.
+    def supports_placeholder_literalizer?
+      true
+    end
+
     # Whether the dataset supports pattern matching by regular expressions, false by default.
     def supports_regexp?
       false
@@ -178,6 +193,11 @@ module Sequel
       true
     end
     
+    # Whether updating joined datasets is supported, false by default.
+    def supports_updating_joins?
+      supports_modifying_joins?
+    end
+    
     # Whether the dataset supports the WINDOW clause to define windows used by multiple
     # window functions, false by default.
     def supports_window_clause?

data/lib/sequel/dataset/misc.rb

@@ -158,6 +158,16 @@ module Sequel
      !!((opts[:from].is_a?(Array) && opts[:from].size > 1) || opts[:join])
     end
 
+    # The class to use for placeholder literalizers for the current dataset.
+    def placeholder_literalizer_class
+      ::Sequel::Dataset::PlaceholderLiteralizer
+    end
+
+    # A placeholder literalizer loader for the current dataset.
+    def placeholder_literalizer_loader(&block)
+      placeholder_literalizer_class.loader(self, &block)
+    end
+
     # The alias to use for the row_number column, used when emulating OFFSET
     # support and for eager limit strategies
     def row_number_column
@@ -296,13 +306,13 @@ module Sequel
         loader += 1
 
         if loader >= 3
-          loader = Sequel::Dataset::PlaceholderLiteralizer.loader(self){|pl, _| yield pl}
+          loader = placeholder_literalizer_loader{|pl, _| yield pl}
           cache_set(key, loader)
         else
           cache_set(key, loader + 1)
           loader = nil
         end
-      elsif cache_sql?
+      elsif cache_sql? && supports_placeholder_literalizer?
         cache_set(key, 1)
       end
 

data/lib/sequel/dataset/placeholder_literalizer.rb

@@ -77,8 +77,8 @@ module Sequel
         # Yields the receiver and the dataset to the block, which should
         # call #arg on the receiver for each placeholder argument, and
         # return the dataset that you want to load.
-        def loader(dataset, &block)
-          PlaceholderLiteralizer.new(*process(dataset, &block))
+        def loader(pl, dataset, &block)
+          pl.new(*process(dataset, &block))
         end
 
         # Return an Argument with the specified position, or the next position. In
@@ -145,7 +145,7 @@ module Sequel
       # given block, recording the offsets at which the recorders arguments
       # are used in the query.
       def self.loader(dataset, &block)
-        Recorder.new.loader(dataset, &block)
+        Recorder.new.loader(self, dataset, &block)
       end
 
       # Save the dataset, array of SQL fragments, and ending SQL string.
@@ -199,20 +199,31 @@ module Sequel
       # Return the SQL query to use for the given arguments.
       def sql(*args)
         raise Error, "wrong number of arguments (#{args.length} for #{@arity})" unless args.length == @arity
-        s = String.new
+        s = sql_origin
+        append_sql(s, *args)
+      end
+
+      # Append the SQL query to use for the given arguments to the given SQL string.
+      def append_sql(sql, *args)
         ds = @dataset
-        @fragments.each do |sql, i, transformer|
-          s << sql
+        @fragments.each do |s, i, transformer|
+          sql << s
           if i.is_a?(Integer)
             v = args.fetch(i)
             v = transformer.call(v) if transformer
           else
             v = i.call
           end
-          ds.literal_append(s, v)
+          ds.literal_append(sql, v)
         end
-        s << @final_sql
-        s
+        sql << @final_sql
+        sql
+      end
+
+      private
+
+      def sql_origin
+        String.new
       end
     end
   end

data/lib/sequel/dataset/prepared_statements.rb

@@ -201,7 +201,9 @@ module Sequel
         when :insert_pk
           fetch_rows(prepared_sql){|r| return r.values.first}
         when Array
+          # :nocov:
           case prepared_type[0]
+          # :nocov:
           when :map, :as_hash, :to_hash, :to_hash_groups
             public_send(*prepared_type, &block) 
           end