sequel 5.57.0 → 5.58.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ab346b95d558c843b61291c10b7033a50fa3e68b1b6d76b16c36f35eea7669a
-  data.tar.gz: eb9acbdab39df252a1e1dd6e66c82a6b13a61544d04d709e46592310ada6f693
+  metadata.gz: 2f02f6a35677e8af2ea2b164f655cc869213864e5b27f67cdd3e17c7db28c546
+  data.tar.gz: ee09f1b4d5b3f4decbf4d4af3b8ae16ef7e488af40011808dac94f8ca05da89f
 SHA512:
-  metadata.gz: 925cdbf7f82dcd9c98fadbaeba92e4b4f36a424e81bde6593a0dc9569d693dc16cc6cb901fe32d0839389348aa3870874589489db4ea4f70eb81e6b2d4e06de4
-  data.tar.gz: 270e046d9c90956dfb7e81d1e17c5baeba6feb563f8aaf66d86494697e5b59e027375b72e11b24d1eb23709b9e2272c2ed53430c4c4bfc1af2957bfba7e64416
+  metadata.gz: 89efe5f1a7f2c2eedba5ac1cf336adee1abf489278f79413756e70a41e4ba073ea818562aaf176c1f092e7ab9e763693473a0d96edc6782d9da037c759afd05d
+  data.tar.gz: 84986009ccb30a7a0fd15a555262631f539b95ef9ec8d74d6ca2a4078bd07c33ffda725092bad5afbc93b27901e67dc6d06ca735481448174ac695ef14b6ee99

data/CHANGELOG

@@ -1,3 +1,9 @@
+=== 5.58.0 (2022-07-01)
+
+* Support :disable_split_materialized Database option on MySQL to work around optimizer bug in MariaDB 10.5+ affecting association tests (jeremyevans)
+
+* Add Dataset#merge* methods to support MERGE statement on PostgreSQL 15+, MSSQL, Oracle, DB2, H2, HSQLDB, and Derby (jeremyevans)
+
 === 5.57.0 (2022-06-01)
 
 * Make Database#create_function on PostgreSQL accept :parallel option (bananarne) (#1870)

data/README.rdoc

@@ -414,6 +414,31 @@ As with +delete+, +update+ affects all rows in the dataset, so +where+ first,
   # NOT THIS:
   posts.update(:state => 'archived').where(Sequel[:stamp] < Date.today - 7)
 
+=== Merging records
+
+Merging records using the SQL MERGE statment is done using <tt>merge*</tt> methods.
+You use +merge_using+ to specify the merge source and join conditions.
+You can use +merge_insert+, +merge_delete+, and/or +merge_update+ to set the
+INSERT, DELETE, and UPDATE clauses for the merge. +merge_insert+ takes the same
+arguments as +insert+, and +merge_update+ takes the same arguments as +update+.
++merge_insert+, +merge_delete+, and +merge_update+ can all be called with blocks,
+to set the conditions for the related INSERT, DELETE, or UPDATE.
+
+Finally, after calling all of the other <tt>merge_*</tt> methods, you call +merge+
+to run the MERGE statement on the database.
+
+  ds = 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)
+
+  ds.merge
+  # 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)
+
 === Transactions
 
 You can wrap a block of code in a database transaction using the <tt>Database#transaction</tt> method:

data/doc/cheat_sheet.rdoc

@@ -57,6 +57,14 @@ Without a filename argument, the sqlite adapter will setup a new sqlite database
   dataset.where{price < 100}.update(:active => true)
   dataset.where(:active).update(:price => Sequel[:price] * 0.90)
 
+= Merge rows
+
+  dataset.
+    merge_using(:table, col1: :col2).
+    merge_insert(col3: :col4).
+    merge_delete{col5 > 30}.
+    merge_update(col3: Sequel[:col3] + :col4)
+
 == Datasets are Enumerable
 
   dataset.map{|r| r[:name]}

data/doc/opening_databases.rdoc

@@ -102,6 +102,7 @@ The following options can be specified and are passed to the database's internal
 :after_connect :: A callable object called after each new connection is made, with the
                   connection object (and server argument if the callable accepts 2 arguments),
                   useful for customizations that you want to apply to all connections (nil by default).
+:connect_sqls :: An array of sql strings to execute on each new connection, after :after_connect runs.
 :max_connections :: The maximum size of the connection pool (4 connections by default on most databases)
 :pool_timeout :: The number of seconds to wait if a connection cannot be acquired before raising an error (5 seconds by default)
 :single_threaded :: Whether to use a single-threaded (non-thread safe) connection pool
@@ -258,6 +259,8 @@ The following additional options are supported:
 :compress :: Whether to compress data sent/received via the socket connection.
 :config_default_group :: The default group to read from the in the MySQL config file, defaults to "client")
 :config_local_infile :: If provided, sets the Mysql::OPT_LOCAL_INFILE option on the connection with the given value.
+:disable_split_materialized :: Set split_materialized=off in the optimizer settings.  Necessary to pass the associations
+                               integration tests in MariaDB 10.5+, due to a unfixed bug in the optimizer.
 :encoding :: Specify the encoding/character set to use for the connection.
 :fractional_seconds :: On MySQL 5.6.5+, this option is recognized and will include fractional seconds in
                        time/timestamp values, as well as have the schema method create columns that can contain
@@ -278,7 +281,9 @@ if either the :sslca or :sslkey option is given.
 
 This is a newer MySQL adapter that does typecasting in C, so it is often faster than the
 mysql adapter.  The options given are passed to Mysql2::Client.new, see the mysql2 documentation
-for details on what options are supported.
+for details on what options are supported. The :timeout, :auto_is_null, :sql_mode, and :disable_split_materialized
+options supported by the mysql adapter are also supported for mysql2 adapter (and any other adapters connecting to
+mysql, such as the jdbc/mysql adapter).
 
 === odbc 
 

data/doc/release_notes/5.58.0.txt

@@ -0,0 +1,31 @@
+= New Features
+
+* Dataset#merge and related #merge_* methods have been added for the
+  MERGE statement.  MERGE is supported on PostgreSQL 15+, Oracle,
+  Microsoft SQL Server, DB2, H2, HSQLDB, and Derby. You can use MERGE
+  to insert, update, and/or delete in a single query.  You call
+  the #merge_* methods to setup the MERGE statement, and #merge to
+  execute it on the database:
+
+    ds = 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)
+
+    ds.merge
+    # 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, the following additional MERGE related methods are
+  available:
+
+  * #merge_do_nothing_when_matched
+  * #merge_do_nothing_when_not_matched
+
+* A :disable_split_materialized Database option is now supported on
+  MySQL. This disables split_materialized support in the optimizer,
+  working around a bug in MariaDB 10.5+ that causes failures in
+  Sequel's association tests.

data/doc/testing.rdoc

@@ -113,7 +113,7 @@ The order in which you delete/truncate the tables is important if you are using
 
 = Testing Sequel Itself
 
-Sequel has multiple separate test suites.  All test suites use minitest/spec, with the minitest-hooks, minitest-global_expectations, and minitest-shared_description extensions.  To install the dependencies necessary to test Sequel, run <tt>gem install --development sequel</tt>.
+Sequel has multiple separate test suites.  All test suites use minitest/spec, with the minitest-hooks and minitest-global_expectations extensions.  To install the dependencies necessary to test Sequel, run <tt>gem install --development sequel</tt>.
 
 == rake
 

data/lib/sequel/adapters/jdbc/derby.rb

@@ -235,6 +235,11 @@ module Sequel
           false
         end
 
+        # Derby 10.11+ supports MERGE.
+        def supports_merge?
+          db.svn_version >= 1616546
+        end
+
         # Derby does not support IN/NOT IN with multiple columns
         def supports_multiple_column_in?
           false

data/lib/sequel/adapters/jdbc/h2.rb

@@ -229,6 +229,11 @@ module Sequel
           false
         end
         
+        # H2 supports MERGE
+        def supports_merge?
+          true
+        end
+
         # H2 doesn't support multiple columns in IN/NOT IN
         def supports_multiple_column_in?
           false

data/lib/sequel/adapters/jdbc/hsqldb.rb

@@ -179,6 +179,12 @@ module Sequel
           true
         end
 
+        # HSQLDB 2.3.4+ supports MERGE.  Older versions also support MERGE, but not all
+        # features that are in Sequel's tests.
+        def supports_merge?
+          db.db_version >= 20304
+        end
+
         private
 
         def empty_from_sql

data/lib/sequel/adapters/shared/db2.rb

@@ -338,6 +338,11 @@ module Sequel
         true
       end
       
+      # DB2 supports MERGE
+      def supports_merge?
+        true
+      end
+
       # DB2 does not support multiple columns in IN.
       def supports_multiple_column_in?
         false
@@ -360,6 +365,29 @@ module Sequel
 
       private
 
+      # Normalize conditions for MERGE WHEN.
+      def _merge_when_conditions_sql(sql, data)
+        if data.has_key?(:conditions)
+          sql << " AND "
+          literal_append(sql, _normalize_merge_when_conditions(data[:conditions]))
+        end
+      end
+
+      # Handle nil, false, and true MERGE WHEN conditions to avoid non-boolean
+      # type error.
+      def _normalize_merge_when_conditions(conditions)
+        case conditions
+        when nil, false
+          {1=>0}
+        when true
+          {1=>1}
+        when Sequel::SQL::DelayedEvaluation
+          Sequel.delay{_normalize_merge_when_conditions(conditions.call(self))}
+        else
+          conditions
+        end
+      end
+
       def empty_from_sql
         ' FROM "SYSIBM"."SYSDUMMY1"'
       end

data/lib/sequel/adapters/shared/mssql.rb

@@ -734,6 +734,11 @@ module Sequel
         false
       end
 
+      # MSSQL 2008+ supports MERGE
+      def supports_merge?
+        is_2008_or_later?
+      end
+
       # MSSQL 2005+ supports modifying joined datasets
       def supports_modifying_joins?
         is_2005_or_later?
@@ -824,6 +829,35 @@ module Sequel
 
       private
 
+      # Normalize conditions for MERGE WHEN.
+      def _merge_when_conditions_sql(sql, data)
+        if data.has_key?(:conditions)
+          sql << " AND "
+          literal_append(sql, _normalize_merge_when_conditions(data[:conditions]))
+        end
+      end
+
+      # Handle nil, false, and true MERGE WHEN conditions to avoid non-boolean
+      # type error.
+      def _normalize_merge_when_conditions(conditions)
+        case conditions
+        when nil, false
+          {1=>0}
+        when true
+          {1=>1}
+        when Sequel::SQL::DelayedEvaluation
+          Sequel.delay{_normalize_merge_when_conditions(conditions.call(self))}
+        else
+          conditions
+        end
+      end
+
+      # MSSQL requires a semicolon at the end of MERGE.
+      def _merge_when_sql(sql)
+        super
+        sql << ';'
+      end
+
       # MSSQL does not allow ordering in sub-clauses unless TOP (limit) is specified
       def aggregate_dataset
         (options_overlap(Sequel::Dataset::COUNT_FROM_SELF_OPTS) && !options_overlap([:limit])) ? unordered.from_self : super

data/lib/sequel/adapters/shared/mysql.rb

@@ -333,6 +333,12 @@ module Sequel
           sqls <<  "SET sql_mode = '#{sql_mode}'"
         end
 
+        # Disable the use of split_materialized in the optimizer. This is
+        # needed to pass association tests on MariaDB 10.5+.
+        if opts[:disable_split_materialized] && typecast_value_boolean(opts[:disable_split_materialized])
+          sqls <<  "SET SESSION optimizer_switch='split_materialized=off'"
+        end
+
         sqls
       end
       

data/lib/sequel/adapters/shared/oracle.rb

@@ -478,6 +478,11 @@ module Sequel
         false
       end
     
+      # Oracle supports MERGE
+      def supports_merge?
+        true
+      end
+
       # Oracle supports NOWAIT.
       def supports_nowait?
         true
@@ -525,6 +530,70 @@ module Sequel
 
       private
 
+      # Handle nil, false, and true MERGE WHEN conditions to avoid non-boolean
+      # type error.
+      def _normalize_merge_when_conditions(conditions)
+        case conditions
+        when nil, false
+          {1=>0}
+        when true
+          {1=>1}
+        when Sequel::SQL::DelayedEvaluation
+          Sequel.delay{_normalize_merge_when_conditions(conditions.call(self))}
+        else
+          conditions
+        end
+      end
+
+      # Handle Oracle's non standard MERGE syntax
+      def _merge_when_sql(sql)
+        raise Error, "no WHEN [NOT] MATCHED clauses provided for MERGE" unless merge_when = @opts[:merge_when]
+        insert = update = delete = nil
+        types = merge_when.map{|d| d[:type]}
+        raise Error, "Oracle does not support multiple INSERT, UPDATE, or DELETE clauses in MERGE" if types != types.uniq
+
+        merge_when.each do |data|
+          case data[:type]
+          when :insert
+            insert = data
+          when :update
+            update = data
+          else # when :delete
+            delete = data
+          end
+        end
+
+        if delete
+          raise Error, "Oracle does not support DELETE without UPDATE clause in MERGE" unless update
+          raise Error, "Oracle does not support DELETE without conditions clause in MERGE" unless delete.has_key?(:conditions)
+        end
+
+        if update
+          sql << " WHEN MATCHED"
+          _merge_update_sql(sql, update)
+          _merge_when_conditions_sql(sql, update)
+
+          if delete
+            sql << " DELETE"
+            _merge_when_conditions_sql(sql, delete)
+          end
+        end
+
+        if insert
+          sql << " WHEN NOT MATCHED"
+          _merge_insert_sql(sql, insert)
+          _merge_when_conditions_sql(sql, insert)
+        end
+      end
+
+      # Handle Oracle's non-standard MERGE WHEN condition syntax.
+      def _merge_when_conditions_sql(sql, data)
+        if data.has_key?(:conditions)
+          sql << " WHERE "
+          literal_append(sql, _normalize_merge_when_conditions(data[:conditions]))
+        end
+      end
+
       # Allow preparing prepared statements, since determining the prepared sql to use for
       # a prepared statement requires calling prepare on that statement.
       def allow_preparing_prepared_statements?

data/lib/sequel/adapters/shared/postgres.rb

@@ -1527,7 +1527,7 @@ module Sequel
       LOCK_MODES = ['ACCESS SHARE', 'ROW SHARE', 'ROW EXCLUSIVE', 'SHARE UPDATE EXCLUSIVE', 'SHARE', 'SHARE ROW EXCLUSIVE', 'EXCLUSIVE', 'ACCESS EXCLUSIVE'].each(&:freeze).freeze
 
       Dataset.def_sql_method(self, :delete, [['if server_version >= 90100', %w'with delete from using where returning'], ['else', %w'delete from using where returning']])
-      Dataset.def_sql_method(self, :insert, [['if server_version >= 90500', %w'with insert into columns values conflict returning'], ['elsif server_version >= 90100', %w'with insert into columns values returning'], ['else', %w'insert into columns values returning']])
+      Dataset.def_sql_method(self, :insert, [['if server_version >= 90500', %w'with insert into columns override values conflict returning'], ['elsif server_version >= 90100', %w'with insert into columns values returning'], ['else', %w'insert into columns values returning']])
       Dataset.def_sql_method(self, :select, [['if opts[:values]', %w'values order limit'], ['elsif server_version >= 80400', %w'with select distinct columns from join where group having window compounds order limit lock'], ['else', %w'select distinct columns from join where group having compounds order limit lock']])
       Dataset.def_sql_method(self, :update, [['if server_version >= 90100', %w'with update table set from where returning'], ['else', %w'update table set from where returning']])
 
@@ -1760,6 +1760,41 @@ module Sequel
         nil
       end
 
+      # Return a dataset with a WHEN MATCHED THEN DO NOTHING 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_do_nothing_when_matched
+      #   # WHEN MATCHED THEN DO NOTHING
+      #
+      #   merge_do_nothing_when_matched{a > 30}
+      #   # WHEN MATCHED AND (a > 30) THEN DO NOTHING
+      def merge_do_nothing_when_matched(&block)
+        _merge_when(:type=>:matched, &block)
+      end
+
+      # Return a dataset with a WHEN NOT MATCHED THEN DO NOTHING 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_do_nothing_when_not_matched
+      #   # WHEN NOT MATCHED THEN DO NOTHING
+      #
+      #   merge_do_nothing_when_not_matched{a > 30}
+      #   # WHEN NOT MATCHED AND (a > 30) THEN DO NOTHING
+      def merge_do_nothing_when_not_matched(&block)
+        _merge_when(:type=>:not_matched, &block)
+      end
+
+      # Support OVERRIDING USER|SYSTEM VALUE for MERGE INSERT.
+      def merge_insert(*values, &block)
+        h = {:type=>:insert, :values=>values}
+        if override = @opts[:override]
+          h[:override] = insert_override_sql(String.new)
+        end
+        _merge_when(h, &block)
+      end
+    
       # Use OVERRIDING USER VALUE for INSERT statements, so that identity columns
       # always use the user supplied value, and an error is not raised for identity
       # columns that are GENERATED ALWAYS.
@@ -1827,6 +1862,11 @@ module Sequel
         true
       end
 
+      # PostgreSQL 15+ supports MERGE.
+      def supports_merge?
+        server_version >= 150000
+      end
+
       # PostgreSQL supports NOWAIT.
       def supports_nowait?
         true
@@ -1937,6 +1977,22 @@ module Sequel
 
       private
 
+      # Append the INSERT sql used in a MERGE
+      def _merge_insert_sql(sql, data)
+        sql << " THEN INSERT "
+        columns, values = _parse_insert_sql_args(data[:values])
+        _insert_columns_sql(sql, columns)
+        if override = data[:override]
+          sql << override
+        end
+        _insert_values_sql(sql, values)
+      end
+
+      def _merge_matched_sql(sql, data)
+        sql << " THEN DO NOTHING"
+      end
+      alias _merge_not_matched_sql _merge_matched_sql
+
       # Format TRUNCATE statement with PostgreSQL specific options.
       def _truncate_sql(table)
         to = @opts[:truncate_opts] || OPTS
@@ -2013,14 +2069,13 @@ module Sequel
       end
 
       # Support OVERRIDING SYSTEM|USER VALUE in insert statements
-      def insert_values_sql(sql)
+      def insert_override_sql(sql)
         case opts[:override]
         when :system
           sql << " OVERRIDING SYSTEM VALUE"
         when :user
           sql << " OVERRIDING USER VALUE"
         end
-        super
       end
 
       # For multiple table support, PostgreSQL requires at least

data/lib/sequel/dataset/actions.rb

@@ -457,6 +457,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.
     #

data/lib/sequel/dataset/features.rb

@@ -125,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

data/lib/sequel/dataset/query.rb

@@ -678,6 +678,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)
@@ -1287,6 +1337,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

data/lib/sequel/dataset/sql.rb

@@ -24,29 +24,7 @@ module Sequel
 
       check_insert_allowed!
 
-      columns = []
-
-      case values.size
-      when 0
-        return insert_sql(OPTS)
-      when 1
-        case vals = values[0]
-        when Hash
-          values = []
-          vals.each do |k,v| 
-            columns << k
-            values << v
-          end
-        when Dataset, Array, LiteralString
-          values = vals
-        end
-      when 2
-        if (v0 = values[0]).is_a?(Array) && ((v1 = values[1]).is_a?(Array) || v1.is_a?(Dataset) || v1.is_a?(LiteralString))
-          columns, values = v0, v1
-          raise(Error, "Different number of values and columns given to insert_sql") if values.is_a?(Array) and columns.length != values.length
-        end
-      end
-
+      columns, values = _parse_insert_sql_args(values)
       if values.is_a?(Array) && values.empty? && !insert_supports_empty_values? 
         columns, values = insert_empty_columns_values
       elsif values.is_a?(Dataset) && hoist_cte?(values) && supports_cte?(:insert)
@@ -112,6 +90,31 @@ module Sequel
       end
     end
     
+    # The SQL to use for the MERGE statement.
+    def merge_sql
+      raise Error, "This database doesn't support MERGE" unless supports_merge?
+      if sql = opts[:sql]
+        return static_sql(sql)
+      end
+      if sql = cache_get(:_merge_sql)
+        return sql
+      end
+      source, join_condition = @opts[:merge_using]
+      raise Error, "No USING clause for MERGE" unless source
+      sql = @opts[:append_sql] || sql_string_origin
+
+      select_with_sql(sql)
+      sql << "MERGE INTO "
+      source_list_append(sql, @opts[:from])
+      sql << " USING "
+      identifier_append(sql, source)
+      sql << " ON "
+      literal_append(sql, join_condition)
+      _merge_when_sql(sql)
+      cache_set(:_merge_sql, sql) if cache_sql?
+      sql
+    end
+
     # Returns an array of insert statements for inserting multiple records.
     # This method is used by +multi_insert+ to format insert statements and
     # expects a keys array and and an array of value arrays.
@@ -850,6 +853,83 @@ module Sequel
     
     private
 
+    # Append the INSERT sql used in a MERGE
+    def _merge_insert_sql(sql, data)
+      sql << " THEN INSERT"
+      columns, values = _parse_insert_sql_args(data[:values])
+      _insert_columns_sql(sql, columns)
+      _insert_values_sql(sql, values)
+    end
+
+    def _merge_update_sql(sql, data)
+      sql << " THEN UPDATE SET "
+      update_sql_values_hash(sql, data[:values])
+    end
+
+    def _merge_delete_sql(sql, data)
+      sql << " THEN DELETE"
+    end
+
+    # Mapping of merge types to related SQL
+    MERGE_TYPE_SQL = {
+      :insert => ' WHEN NOT MATCHED',
+      :delete => ' WHEN MATCHED',
+      :update => ' WHEN MATCHED',
+      :matched => ' WHEN MATCHED',
+      :not_matched => ' WHEN NOT MATCHED',
+    }.freeze
+    private_constant :MERGE_TYPE_SQL
+
+    # Add the WHEN clauses to the MERGE SQL
+    def _merge_when_sql(sql)
+      raise Error, "no WHEN [NOT] MATCHED clauses provided for MERGE" unless merge_when = @opts[:merge_when]
+      merge_when.each do |data|
+        type = data[:type]
+        sql << MERGE_TYPE_SQL[type]
+        _merge_when_conditions_sql(sql, data)
+        send(:"_merge_#{type}_sql", sql, data)
+      end
+    end
+
+    # Append MERGE WHEN conditions, if there are conditions provided.
+    def _merge_when_conditions_sql(sql, data)
+      if data.has_key?(:conditions)
+        sql << " AND "
+        literal_append(sql, data[:conditions])
+      end
+    end
+
+    # Parse the values passed to insert_sql, returning columns and values
+    # to use for the INSERT.  Returned columns is always an array, but can be empty
+    # for an INSERT without explicit column references. Returned values can be an
+    # array, dataset, or literal string.
+    def _parse_insert_sql_args(values)
+      columns = []
+
+      case values.size
+      when 0
+        values = []
+      when 1
+        case vals = values[0]
+        when Hash
+          values = []
+          vals.each do |k,v| 
+            columns << k
+            values << v
+          end
+        when Dataset, Array, LiteralString
+          values = vals
+        end
+      when 2
+        if (v0 = values[0]).is_a?(Array) && ((v1 = values[1]).is_a?(Array) || v1.is_a?(Dataset) || v1.is_a?(LiteralString))
+          columns, values = v0, v1
+          raise(Error, "Different number of values and columns given to insert_sql") if values.is_a?(Array) and columns.length != values.length
+        end
+      end
+
+      [columns, values]
+    end
+
     # Formats the truncate statement.  Assumes the table given has already been
     # literalized.
     def _truncate_sql(table)
@@ -1165,7 +1245,10 @@ module Sequel
     end
 
     def insert_columns_sql(sql)
-      columns = opts[:columns]
+      _insert_columns_sql(sql, opts[:columns])
+    end
+
+    def _insert_columns_sql(sql, columns)
       if columns && !columns.empty?
         sql << ' ('
         identifier_list_append(sql, columns)
@@ -1184,7 +1267,11 @@ module Sequel
     end
 
     def insert_values_sql(sql)
-      case values = opts[:values]
+      _insert_values_sql(sql, opts[:values])
+    end
+    
+    def _insert_values_sql(sql, values)
+      case values
       when Array
         if values.empty?
           sql << " DEFAULT VALUES"

data/lib/sequel/extensions/pg_hstore.rb

@@ -76,7 +76,7 @@
 #
 # This extension integrates with the pg_array extension.  If you plan
 # to use arrays of hstore types, load the pg_array extension before the
-# pg_interval extension:
+# pg_hstore extension:
 #
 #   DB.extension :pg_array, :pg_hstore
 #

data/lib/sequel/version.rb

@@ -6,7 +6,7 @@ module Sequel
 
   # The minor version of Sequel.  Bumped for every non-patch level
   # release, generally around once a month.
-  MINOR = 57
+  MINOR = 58
 
   # The tiny version of Sequel.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sequel
 version: !ruby/object:Gem::Version
-  version: 5.57.0
+  version: 5.58.0
 platform: ruby
 authors:
 - Jeremy Evans
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-06-01 00:00:00.000000000 Z
+date: 2022-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -52,20 +52,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: minitest-shared_description
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: tzinfo
   requirement: !ruby/object:Gem::Requirement
@@ -202,6 +188,7 @@ extra_rdoc_files:
 - doc/release_notes/5.55.0.txt
 - doc/release_notes/5.56.0.txt
 - doc/release_notes/5.57.0.txt
+- doc/release_notes/5.58.0.txt
 - doc/release_notes/5.6.0.txt
 - doc/release_notes/5.7.0.txt
 - doc/release_notes/5.8.0.txt
@@ -287,6 +274,7 @@ files:
 - doc/release_notes/5.55.0.txt
 - doc/release_notes/5.56.0.txt
 - doc/release_notes/5.57.0.txt
+- doc/release_notes/5.58.0.txt
 - doc/release_notes/5.6.0.txt
 - doc/release_notes/5.7.0.txt
 - doc/release_notes/5.8.0.txt