sequel 5.83.0 → 5.106.0

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

@@ -48,7 +48,7 @@ module Sequel
     TYPE_TRANSLATOR_DATE = date.freeze
     bytea = Object.new
     def bytea.call(str)
-      str = if str =~ /\A\\x/
+      str = if str.start_with?('\\x')
         # PostgreSQL 9.0+ bytea hex format
         str[2..-1].gsub(/(..)/){|s| s.to_i(16).chr}
       else
@@ -101,7 +101,7 @@ module Sequel
 
     def self.mock_adapter_setup(db)
       db.instance_exec do
-        @server_version = 150000
+        @server_version = 170000
         initialize_postgres_adapter
         extend(MockAdapterDatabaseMethods)
       end
@@ -124,6 +124,8 @@ module Sequel
       #
       # Options supported:
       #
+      # :include :: Include additional columns in the underlying index, to
+      #             allow for index-only scans in more cases (PostgreSQL 11+).
       # :name :: Name the constraint with the given name (useful if you may
       #          need to drop the constraint later)
       # :using :: Override the index_method for the exclusion constraint (defaults to gist).
@@ -141,6 +143,22 @@ module Sequel
         @operations << {:op => :add_constraint, :type => :exclude, :elements => elements}.merge!(opts)
       end
 
+      # Alter an existing constraint.  Options:
+      # :deferrable :: Modify deferrable setting for constraint (PostgreSQL 9.4+):
+      #                true :: DEFERRABLE INITIALLY DEFERRED
+      #                false :: NOT DEFERRABLE
+      #                :immediate :: DEFERRABLE INITIALLY IMMEDIATE
+      # :enforced :: Set true to use ENFORCED, or false to use NOT ENFORCED (PostgreSQL 18+)
+      # :inherit :: Set true to use INHERIT, or false to use NO INHERIT (PostgreSQL 18+)
+      def alter_constraint(name, opts=OPTS)
+        @operations << {:op => :alter_constraint, :name => name}.merge!(opts)
+      end
+
+      # :inherit :: Set true to use INHERIT, or false to use NO INHERIT (PostgreSQL 18+)
+      def rename_constraint(name, new_name)
+        @operations << {:op => :rename_constraint, :name => name, :new_name => new_name}
+      end
+
       # Validate the constraint with the given name, which should have
       # been added previously with NOT VALID.
       def validate_constraint(name)
@@ -321,7 +339,7 @@ module Sequel
       end
 
       def commit_prepared_transaction(transaction_id, opts=OPTS)
-        run("COMMIT PREPARED #{literal(transaction_id)}", opts)
+        run("COMMIT PREPARED #{literal(transaction_id)}".freeze, opts)
       end
 
       # A hash of metadata for CHECK constraints on the table.
@@ -335,7 +353,7 @@ module Sequel
         hash = {}
         _check_constraints_ds.where_each(:conrelid=>regclass_oid(table)) do |row|
           constraint = m.call(row[:constraint])
-          entry = hash[constraint] ||= {:definition=>row[:definition], :columns=>[]}
+          entry = hash[constraint] ||= {:definition=>row[:definition], :columns=>[], :validated=>row[:validated], :enforced=>row[:enforced]}
           entry[:columns] << m.call(row[:column]) if row[:column]
         end
         
@@ -398,7 +416,7 @@ module Sequel
         return if already_identity
 
         transaction(server_hash) do
-          run("ALTER TABLE #{quote_schema_table(table)} ALTER COLUMN #{quote_identifier(column)} DROP DEFAULT", server_hash)
+          run("ALTER TABLE #{quote_schema_table(table)} ALTER COLUMN #{quote_identifier(column)} DROP DEFAULT".freeze, server_hash)
 
           ds.from(:pg_depend).
             where(:classid=>pg_class, :objid=>seq_oid, :objsubid=>0, :deptype=>'a').
@@ -435,7 +453,7 @@ module Sequel
       #                 often used here if :security_definer is used.
       #         :strict :: Makes the function return NULL when any argument is NULL.
       def create_function(name, definition, opts=OPTS)
-        self << create_function_sql(name, definition, opts)
+        self << create_function_sql(name, definition, opts).freeze
       end
 
       # Create the procedural language in the database. Arguments:
@@ -446,7 +464,7 @@ module Sequel
       #         :trusted :: Marks the language being created as trusted, allowing unprivileged users to create functions using this language.
       #         :validator :: The name of previously registered function used as a validator of functions defined in this language.
       def create_language(name, opts=OPTS)
-        self << create_language_sql(name, opts)
+        self << create_language_sql(name, opts).freeze
       end
 
       # Create a schema in the database. Arguments:
@@ -455,7 +473,7 @@ module Sequel
       #         :if_not_exists :: Don't raise an error if the schema already exists (PostgreSQL 9.3+)
       #         :owner :: The owner to set for the schema (defaults to current user if not specified)
       def create_schema(name, opts=OPTS)
-        self << create_schema_sql(name, opts)
+        self << create_schema_sql(name, opts).freeze
       end
 
       # Support partitions of tables using the :partition_of option.
@@ -491,7 +509,7 @@ module Sequel
       #         :replace :: Replace the trigger with the same name if it already exists (PostgreSQL 14+).
       #         :when :: A filter to use for the trigger
       def create_trigger(table, name, function, opts=OPTS)
-        self << create_trigger_sql(table, name, function, opts)
+        self << create_trigger_sql(table, name, function, opts).freeze
       end
 
       def database_type
@@ -524,7 +542,7 @@ module Sequel
       #              default is plpgsql.  Can be specified as a string or a symbol.
       def do(code, opts=OPTS)
         language = opts[:language]
-        run "DO #{"LANGUAGE #{literal(language.to_s)} " if language}#{literal(code)}"
+        run "DO #{"LANGUAGE #{literal(language.to_s)} " if language}#{literal(code)}".freeze
       end
 
       # Drops the function from the database. Arguments:
@@ -534,7 +552,7 @@ module Sequel
       #         :cascade :: Drop other objects depending on this function.
       #         :if_exists :: Don't raise an error if the function doesn't exist.
       def drop_function(name, opts=OPTS)
-        self << drop_function_sql(name, opts)
+        self << drop_function_sql(name, opts).freeze
       end
 
       # Drops a procedural language from the database.  Arguments:
@@ -543,7 +561,7 @@ module Sequel
       #         :cascade :: Drop other objects depending on this function.
       #         :if_exists :: Don't raise an error if the function doesn't exist.
       def drop_language(name, opts=OPTS)
-        self << drop_language_sql(name, opts)
+        self << drop_language_sql(name, opts).freeze
       end
 
       # Drops a schema from the database.  Arguments:
@@ -552,7 +570,8 @@ module Sequel
       #         :cascade :: Drop all objects in this schema.
       #         :if_exists :: Don't raise an error if the schema doesn't exist.
       def drop_schema(name, opts=OPTS)
-        self << drop_schema_sql(name, opts)
+        self << drop_schema_sql(name, opts).freeze
+        remove_all_cached_schemas
       end
 
       # Drops a trigger from the database.  Arguments:
@@ -562,7 +581,7 @@ module Sequel
       #         :cascade :: Drop other objects depending on this function.
       #         :if_exists :: Don't raise an error if the function doesn't exist.
       def drop_trigger(table, name, opts=OPTS)
-        self << drop_trigger_sql(table, name, opts)
+        self << drop_trigger_sql(table, name, opts).freeze
       end
 
       # Return full foreign key information using the pg system tables, including
@@ -601,6 +620,8 @@ module Sequel
               :on_update=>fklod_map[row[:on_update]],
               :on_delete=>fklod_map[row[:on_delete]],
               :deferrable=>row[:deferrable],
+              :validated=>row[:validated],
+              :enforced=>row[:enforced],
               :table=>schema ? SQL::QualifiedIdentifier.new(m.call(row[:schema]), m.call(row[:table])) : m.call(row[:table]),
             }
 
@@ -648,12 +669,26 @@ module Sequel
         _set_constraints(' IMMEDIATE', opts)
       end
 
-      # Use the pg_* system tables to determine indexes on a table
+      # Use the pg_* system tables to determine indexes on a table. Options:
+      #
+      # :include_partial :: Set to true to include partial indexes
+      # :invalid :: Set to true or :only to only return invalid indexes.
+      #             Set to :include to also return both valid and invalid indexes.
+      #             When not set or other value given, does not return invalid indexes.
       def indexes(table, opts=OPTS)
         m = output_identifier_meth
         cond = {Sequel[:tab][:oid]=>regclass_oid(table, opts)}
         cond[:indpred] = nil unless opts[:include_partial]
 
+        case opts[:invalid]
+        when true, :only
+          cond[:indisvalid] = false
+        when :include
+          # nothing
+        else
+          cond[:indisvalid] = true
+        end
+
         indexes = {}
         _indexes_ds.where_each(cond) do |r|
           i = indexes[m.call(r[:name])] ||= {:columns=>[], :unique=>r[:unique], :deferrable=>r[:deferrable]}
@@ -706,6 +741,14 @@ module Sequel
         Sequel.synchronize{@primary_key_sequences[quoted_table] = value} if value
       end
 
+      # Rename a schema in the database. Arguments:
+      # name :: Current name of the schema
+      # opts :: New name for the schema
+      def rename_schema(name, new_name)
+        self << rename_schema_sql(name, new_name).freeze
+        remove_all_cached_schemas
+      end
+
       # Refresh the materialized view with the given name.
       # 
       #   DB.refresh_view(:items_view)
@@ -713,7 +756,7 @@ module Sequel
       #   DB.refresh_view(:items_view, concurrently: true)
       #   # REFRESH MATERIALIZED VIEW CONCURRENTLY items_view
       def refresh_view(name, opts=OPTS)
-        run "REFRESH MATERIALIZED VIEW#{' CONCURRENTLY' if opts[:concurrently]} #{quote_schema_table(name)}"
+        run "REFRESH MATERIALIZED VIEW#{' CONCURRENTLY' if opts[:concurrently]} #{quote_schema_table(name)}".freeze
       end
       
       # Reset the primary key sequence for the given table, basing it on the
@@ -726,7 +769,7 @@ module Sequel
         table = Sequel.qualify(s, t) if s
 
         if server_version >= 100000
-          seq_ds = metadata_dataset.from(:pg_sequence).where(:seqrelid=>regclass_oid(LiteralString.new(seq)))
+          seq_ds = metadata_dataset.from(:pg_sequence).where(:seqrelid=>regclass_oid(LiteralString.new(seq.freeze)))
           increment_by = :seqincrement
           min_value = :seqmin
         # :nocov:
@@ -741,7 +784,7 @@ module Sequel
       end
 
       def rollback_prepared_transaction(transaction_id, opts=OPTS)
-        run("ROLLBACK PREPARED #{literal(transaction_id)}", opts)
+        run("ROLLBACK PREPARED #{literal(transaction_id)}".freeze, opts)
       end
 
       # PostgreSQL uses SERIAL psuedo-type instead of AUTOINCREMENT for
@@ -898,11 +941,15 @@ module Sequel
 
       # Dataset used to retrieve CHECK constraint information
       def _check_constraints_ds
-        @_check_constraints_ds ||= metadata_dataset.
-          from{pg_constraint.as(:co)}.
-          left_join(Sequel[:pg_attribute].as(:att), :attrelid=>:conrelid, :attnum=>SQL::Function.new(:ANY, Sequel[:co][:conkey])).
-          where(:contype=>'c').
-          select{[co[:conname].as(:constraint), att[:attname].as(:column), pg_get_constraintdef(co[:oid]).as(:definition)]}
+        @_check_constraints_ds ||= begin
+          ds = metadata_dataset.
+            from{pg_constraint.as(:co)}.
+            left_join(Sequel[:pg_attribute].as(:att), :attrelid=>:conrelid, :attnum=>SQL::Function.new(:ANY, Sequel[:co][:conkey])).
+            where(:contype=>'c').
+            select{[co[:conname].as(:constraint), att[:attname].as(:column), pg_get_constraintdef(co[:oid]).as(:definition)]}
+
+          _add_validated_enforced_constraint_columns(ds)
+        end
       end
 
       # Dataset used to retrieve foreign keys referenced by a table
@@ -968,6 +1015,28 @@ module Sequel
           ds = ds.order_append(Sequel[:nsp][:nspname], Sequel[:cl2][:relname])
         end
 
+        _add_validated_enforced_constraint_columns(ds)
+      end
+
+      def _add_validated_enforced_constraint_columns(ds)
+        validated_cond = if server_version >= 90100
+          Sequel[:convalidated]
+        # :nocov:
+        else
+          Sequel.cast(true, TrueClass)
+        # :nocov:
+        end
+        ds = ds.select_append(validated_cond.as(:validated))
+
+        enforced_cond = if server_version >= 180000
+          Sequel[:conenforced]
+        # :nocov:
+        else
+          Sequel.cast(true, TrueClass)
+        # :nocov:
+        end
+        ds = ds.select_append(enforced_cond.as(:enforced))
+
         ds
       end
 
@@ -994,8 +1063,7 @@ module Sequel
             where{{
               indc[:relkind]=>%w'i I',
               ind[:indisprimary]=>false,
-              :indexprs=>nil,
-              :indisvalid=>true}}.
+              :indexprs=>nil}}.
             order(*order).
             select{[indc[:relname].as(:name), ind[:indisunique].as(:unique), att[:attname].as(:column), con[:condeferrable].as(:deferrable)]}
 
@@ -1075,6 +1143,7 @@ module Sequel
               pg_attribute[:attname].as(:name),
               SQL::Cast.new(pg_attribute[:atttypid], :integer).as(:oid),
               SQL::Cast.new(basetype[:oid], :integer).as(:base_oid),
+              SQL::Function.new(:col_description, pg_class[:oid], pg_attribute[:attnum]).as(:comment),
               SQL::Function.new(:format_type, basetype[:oid], pg_type[:typtypmod]).as(:db_base_type),
               SQL::Function.new(:format_type, pg_type[:oid], pg_attribute[:atttypmod]).as(:db_type),
               SQL::Function.new(:pg_get_expr, pg_attrdef[:adbin], pg_class[:oid]).as(:default),
@@ -1139,10 +1208,39 @@ module Sequel
         "ADD COLUMN#{' IF NOT EXISTS' if op[:if_not_exists]} #{column_definition_sql(op)}"
       end
 
+      def alter_table_alter_constraint_sql(table, op)
+        sql = String.new
+        sql << "ALTER CONSTRAINT #{quote_identifier(op[:name])}"
+        
+        constraint_deferrable_sql_append(sql, op[:deferrable])
+
+        case op[:enforced]
+        when nil
+        when false
+          sql << " NOT ENFORCED"
+        else
+          sql << " ENFORCED"
+        end
+
+        case op[:inherit]
+        when nil
+        when false
+          sql << " NO INHERIT"
+        else
+          sql << " INHERIT"
+        end
+
+        sql
+      end
+
       def alter_table_generator_class
         Postgres::AlterTableGenerator
       end
     
+      def alter_table_rename_constraint_sql(table, op)
+        "RENAME CONSTRAINT #{quote_identifier(op[:name])} TO #{quote_identifier(op[:new_name])}"
+      end
+
       def alter_table_set_column_type_sql(table, op)
         s = super
         if using = op[:using]
@@ -1189,6 +1287,22 @@ module Sequel
         end
       end
 
+      def column_definition_append_include_sql(sql, constraint)
+        if include_cols = constraint[:include]
+          sql << " INCLUDE " << literal(Array(include_cols))
+        end
+      end
+    
+      def column_definition_append_primary_key_sql(sql, constraint)
+        super
+        column_definition_append_include_sql(sql, constraint)
+      end
+
+      def column_definition_append_unique_sql(sql, constraint)
+        super
+        column_definition_append_include_sql(sql, constraint)
+      end
+
       # Literalize non-String collate options. This is because unquoted collatations
       # are folded to lowercase, and PostgreSQL used mixed case or capitalized collations.
       def column_definition_collate_sql(sql, column)
@@ -1208,7 +1322,7 @@ module Sequel
             sql << (identity == :always ? "ALWAYS" : "BY DEFAULT")
             sql << " AS IDENTITY"
           elsif (generated = column[:generated_always_as])
-            sql << " GENERATED ALWAYS AS (#{literal(generated)}) STORED"
+            sql << " GENERATED ALWAYS AS (#{literal(generated)}) #{column[:virtual] ? 'VIRTUAL' : 'STORED'}"
           end
         end
       end
@@ -1232,9 +1346,9 @@ module Sequel
       end
 
       # PostgreSQL can't combine rename_column operations, and it can combine
-      # the custom validate_constraint operation.
+      # validate_constraint and alter_constraint operations.
       def combinable_alter_table_op?(op)
-        (super || op[:op] == :validate_constraint) && op[:op] != :rename_column
+        (super || op[:op] == :validate_constraint || op[:op] == :alter_constraint) && op[:op] != :rename_column
       end
 
       VALID_CLIENT_MIN_MESSAGES = %w'DEBUG5 DEBUG4 DEBUG3 DEBUG2 DEBUG1 LOG NOTICE WARNING ERROR FATAL PANIC'.freeze.each(&:freeze)
@@ -1268,26 +1382,97 @@ module Sequel
         sqls
       end
 
-      # Handle exclusion constraints.
+      # Handle PostgreSQL-specific constraint features.
       def constraint_definition_sql(constraint)
-        case constraint[:type]
+        case type = constraint[:type]
         when :exclude
           elements = constraint[:elements].map{|c, op| "#{literal(c)} WITH #{op}"}.join(', ')
           sql = String.new
-          sql << "#{"CONSTRAINT #{quote_identifier(constraint[:name])} " if constraint[:name]}EXCLUDE USING #{constraint[:using]||'gist'} (#{elements})#{" WHERE #{filter_expr(constraint[:where])}" if constraint[:where]}"
+          sql << "CONSTRAINT #{quote_identifier(constraint[:name])} " if constraint[:name]
+          sql << "EXCLUDE USING #{constraint[:using]||'gist'} (#{elements})"
+          column_definition_append_include_sql(sql, constraint)
+          sql << " WHERE #{filter_expr(constraint[:where])}" if constraint[:where]
+          constraint_deferrable_sql_append(sql, constraint[:deferrable])
+          sql
+        when :primary_key, :unique
+          sql = String.new
+          sql << "CONSTRAINT #{quote_identifier(constraint[:name])} " if constraint[:name]
+
+          if type == :primary_key
+            sql << primary_key_constraint_sql_fragment(constraint)
+          else
+            sql << unique_constraint_sql_fragment(constraint)
+          end
+
+          if using_index = constraint[:using_index]
+            sql << " USING INDEX " << quote_identifier(using_index)
+          else
+            cols = literal(constraint[:columns])
+            cols.insert(-2, " WITHOUT OVERLAPS") if constraint[:without_overlaps]
+            sql << " " << cols
+
+            if include_cols = constraint[:include]
+              sql << " INCLUDE " << literal(Array(include_cols))
+            end
+          end
+
           constraint_deferrable_sql_append(sql, constraint[:deferrable])
           sql
-        when :foreign_key, :check
+        else # when :foreign_key, :check
           sql = super
+          if constraint[:no_inherit]
+            sql << " NO INHERIT"
+          end
+          if constraint[:not_enforced]
+            sql << " NOT ENFORCED"
+          end
           if constraint[:not_valid]
             sql << " NOT VALID"
           end
           sql
-        else
-          super
         end
       end
 
+      def column_definition_add_references_sql(sql, column)
+        super
+        if column[:not_enforced]
+          sql << " NOT ENFORCED"
+        end
+      end
+
+      def column_definition_null_sql(sql, column)
+        constraint = column[:not_null]
+        constraint = nil unless constraint.is_a?(Hash)
+        if constraint && (name = constraint[:name])
+          sql << " CONSTRAINT #{quote_identifier(name)}"
+        end
+        super
+        if constraint && constraint[:no_inherit]
+          sql << " NO INHERIT"
+        end
+      end
+
+      # Handle :period option
+      def column_references_table_constraint_sql(constraint)
+        sql = String.new
+        sql << "FOREIGN KEY "
+        cols = constraint[:columns]
+        cols = column_references_add_period(cols) if constraint[:period]
+        sql << literal(cols) << column_references_sql(constraint)
+      end
+
+      def column_references_append_key_sql(sql, column)
+        cols = Array(column[:key])
+        cols = column_references_add_period(cols) if column[:period]
+        sql << "(#{cols.map{|x| quote_identifier(x)}.join(', ')})"
+      end
+
+      def column_references_add_period(cols)
+        cols= cols.dup
+        cols[-1] = Sequel.lit("PERIOD #{quote_identifier(cols[-1])}".freeze)
+        cols
+      end
+  
       def database_specific_error_class_from_sqlstate(sqlstate)
         if sqlstate == '23P01'
           ExclusionConstraintViolation
@@ -1357,7 +1542,8 @@ module Sequel
       # SQL statement to create database function.
       def create_function_sql(name, definition, opts=OPTS)
         args = opts[:args]
-        if !opts[:args].is_a?(Array) || !opts[:args].any?{|a| Array(a).length == 3 and %w'OUT INOUT'.include?(a[2].to_s)}
+        in_out = %w'OUT INOUT'
+        if (!opts[:args].is_a?(Array) || !opts[:args].any?{|a| Array(a).length == 3 && in_out.include?(a[2].to_s)})
           returns = opts[:returns] || 'void'
         end
         language = opts[:language] || 'SQL'
@@ -1584,7 +1770,7 @@ module Sequel
           index_type = :gist
         end
 
-        "CREATE #{unique}INDEX#{' CONCURRENTLY' if index[:concurrently]}#{if_not_exists} #{quote_identifier(index_name)} ON #{quote_schema_table(table_name)} #{"USING #{index_type} " if index_type}#{expr}#{" INCLUDE #{literal(Array(index[:include]))}" if index[:include]}#{nulls_distinct}#{" TABLESPACE #{quote_identifier(index[:tablespace])}" if index[:tablespace]}#{filter}"
+        "CREATE #{unique}INDEX#{' CONCURRENTLY' if index[:concurrently]}#{if_not_exists} #{quote_identifier(index_name)} ON#{' ONLY' if index[:only]} #{quote_schema_table(table_name)} #{"USING #{index_type} " if index_type}#{expr}#{" INCLUDE #{literal(Array(index[:include]))}" if index[:include]}#{nulls_distinct}#{" TABLESPACE #{quote_identifier(index[:tablespace])}" if index[:tablespace]}#{filter}"
       end
 
       # Setup datastructures shared by all postgres adapters.
@@ -1642,6 +1828,18 @@ module Sequel
         super
       end
 
+      # Clear all cached schema information
+      def remove_all_cached_schemas
+        @primary_keys.clear
+        @primary_key_sequences.clear
+        @schemas.clear
+      end
+
+      # SQL for renaming a schema.
+      def rename_schema_sql(name, new_name)
+        "ALTER SCHEMA #{quote_identifier(name)} RENAME TO #{quote_identifier(new_name)}"
+      end
+
       # SQL DDL statement for renaming a table. PostgreSQL doesn't allow you to change a table's schema in
       # a rename table operation, so specifying a new schema in new_name will not have an effect.
       def rename_table_sql(name, new_name)
@@ -1651,9 +1849,9 @@ module Sequel
       # Handle interval and citext types.
       def schema_column_type(db_type)
         case db_type
-        when /\Ainterval\z/io
+        when /\Ainterval\z/i
           :interval
-        when /\Acitext\z/io
+        when /\Acitext\z/i
           :string
         else
           super
@@ -1804,6 +2002,15 @@ module Sequel
         end
       end
 
+      # Support :nulls_not_distinct option.
+      def unique_constraint_sql_fragment(constraint)
+        if constraint[:nulls_not_distinct]
+          'UNIQUE NULLS NOT DISTINCT'
+        else
+          'UNIQUE'
+        end
+      end
+    
       # PostgreSQL 9.4+ supports views with check option.
       def view_with_check_option_support
         # :nocov:
@@ -1876,14 +2083,86 @@ module Sequel
         super
       end
 
-      # Return the results of an EXPLAIN query as a string
+      # Return the results of an EXPLAIN query.  Boolean options:
+      #
+      # :analyze :: Use the ANALYZE option.
+      # :buffers :: Use the BUFFERS option.
+      # :costs :: Use the COSTS option.
+      # :generic_plan :: Use the GENERIC_PLAN option.
+      # :memory :: Use the MEMORY option.
+      # :settings :: Use the SETTINGS option.
+      # :summary :: Use the SUMMARY option.
+      # :timing :: Use the TIMING option.
+      # :verbose :: Use the VERBOSE option.
+      # :wal :: Use the WAL option.
+      #
+      # Non boolean options:
+      #
+      # :format :: Use the FORMAT option to change the format of the
+      #            returned value.  Values can be :text, :xml, :json,
+      #            or :yaml.
+      # :serialize :: Use the SERIALIZE option to get timing on
+      #               serialization.  Values can be :none, :text, or
+      #               :binary.
+      #
+      # See the PostgreSQL EXPLAIN documentation for an explanation of
+      # what each option does.
+      #
+      # In most cases, the return value is a single string.  However,
+      # using the <tt>format: :json</tt> option can result in the return
+      # value being an array containing a hash.
       def explain(opts=OPTS)
-        with_sql((opts[:analyze] ? 'EXPLAIN ANALYZE ' : 'EXPLAIN ') + select_sql).map(:'QUERY PLAN').join("\r\n")
+        rows = clone(:append_sql=>explain_sql_string_origin(opts)).map(:'QUERY PLAN')
+
+        if rows.length == 1
+          rows[0]
+        elsif rows.all?{|row| String === row}
+          rows.join("\r\n") 
+        # :nocov:
+        else
+          # This branch is unreachable in tests, but it seems better to just return
+          # all rows than throw in error if this case actually happens.
+          rows
+        # :nocov:
+        end
+      end
+
+      # Return a cloned dataset which will use FOR KEY SHARE to lock returned rows.
+      # Supported on PostgreSQL 9.3+.
+      def for_key_share
+        cached_lock_style_dataset(:_for_key_share_ds, :key_share)
+      end
+
+      # Set FOR PORTION OF clause for UPDATE and DELETE statements.
+      # The first argument is the range or multirange column. If two arguments
+      # are provided, the second argument is an expression with the same
+      # database type as the first argument. If three arguments are provided,
+      # the second specifies the inclusive start of the portion to update and the third
+      # specifies the exclusive end of portion to update. When using the three argument
+      # form, nil can be provided as the second or third argument to have the start or
+      # end of the portion be unbounded.  Supported on PostgreSQL 19+.
+      # Example:
+      #
+      #   DB[:t].for_portion_of(:rc, Sequel.function(:int4range, 1, 2)).update(c: 3)
+      #   # UPDATE t FOR PORTION OF rc (int4range(1, 2)) SET c = 3
+      #   
+      #   DB[:t].for_portion_of(:rc, 1, 2).update(c: 3)
+      #   # UPDATE t FOR PORTION OF rc FROM 1 TO 2 SET c = 3
+      def for_portion_of(column, range, to=(arg_not_given=true))
+        range = [range, to].freeze unless arg_not_given
+        clone(:for_portion_of => [column, range].freeze)
+      end
+
+      # Return a cloned dataset which will use FOR NO KEY UPDATE to lock returned rows.
+      # This is generally a better choice than using for_update on PostgreSQL, unless
+      # you will be deleting the row or modifying a key column. Supported on PostgreSQL 9.3+.
+      def for_no_key_update
+        cached_lock_style_dataset(:_for_no_key_update_ds, :no_key_update)
       end
 
       # Return a cloned dataset which will use FOR SHARE to lock returned rows.
       def for_share
-        lock_style(:share)
+        cached_lock_style_dataset(:_for_share_ds, :share)
       end
 
       # Run a full text search on PostgreSQL.  By default, searching for the inclusion
@@ -1914,7 +2193,7 @@ module Sequel
         end
 
         unless opts[:tsquery]
-          phrase_terms = terms.is_a?(Array) ? terms.join(' | ') : terms
+          phrase_terms = terms.is_a?(Array) || terms.is_a?(Set) ? Sequel.array_or_set_join(terms, ' | ') : terms
 
           query_func = case to_tsquery = opts[:to_tsquery]
           when :phrase, :plain
@@ -2376,10 +2655,11 @@ module Sequel
         "'%Y-%m-%d %H:%M:%S.%6N%z'"
       end
 
-      # Only include the primary table in the main delete clause
+      # Only include the primary table in the main delete clause.
+      # Support FOR PORTION OF.
       def delete_from_sql(sql)
         sql << ' FROM '
-        source_list_append(sql, @opts[:from][0..0])
+        table_for_portion_of_sql_append(sql)
       end
 
       # Use USING to specify additional tables in a delete query
@@ -2387,6 +2667,109 @@ module Sequel
         join_from_sql(:USING, sql)
       end
 
+      # Handle column aliases containing data types, useful for selecting from functions
+      # that return the record data type.
+      def derived_column_list_sql_append(sql, column_aliases)
+        c = false
+        comma = ', '
+        column_aliases.each do |a|
+          sql << comma if c
+          if a.is_a?(Array)
+            raise Error, "column aliases specified as arrays must have only 2 elements, the first is alias name and the second is data type" unless a.length == 2
+            a, type = a
+            identifier_append(sql, a)
+            sql << " " << db.cast_type_literal(type).to_s
+          else
+            identifier_append(sql, a)
+          end
+          c ||= true
+        end
+      end
+
+      EXPLAIN_BOOLEAN_OPTIONS = {}
+      %w[analyze verbose costs settings generic_plan buffers wal timing summary memory].each do |str|
+        EXPLAIN_BOOLEAN_OPTIONS[str.to_sym] = str.upcase.freeze
+      end
+      EXPLAIN_BOOLEAN_OPTIONS.freeze
+
+      EXPLAIN_NONBOOLEAN_OPTIONS = {
+        :serialize => {:none=>"SERIALIZE NONE", :text=>"SERIALIZE TEXT", :binary=>"SERIALIZE BINARY"}.freeze,
+        :format => {:text=>"FORMAT TEXT", :xml=>"FORMAT XML", :json=>"FORMAT JSON", :yaml=>"FORMAT YAML"}.freeze
+      }.freeze
+    
+      # A mutable string used as the prefix when explaining a query.
+      def explain_sql_string_origin(opts)
+        origin = String.new
+        origin << 'EXPLAIN '
+
+        # :nocov:
+        if server_version < 90000
+          if opts[:analyze]
+            origin << 'ANALYZE '
+          end
+
+          return origin
+        end
+        # :nocov:
+
+        comma = nil
+        paren = "("
+
+        add_opt = lambda do |str, value|
+          origin << paren if paren
+          origin << comma if comma
+          origin << str
+          origin << " FALSE" unless value
+          comma ||= ', '
+          paren &&= nil
+        end
+
+        EXPLAIN_BOOLEAN_OPTIONS.each do |key, str|
+          unless (value = opts[key]).nil?
+            add_opt.call(str, value)
+          end
+        end
+
+        EXPLAIN_NONBOOLEAN_OPTIONS.each do |key, e_opts|
+          if value = opts[key]
+            if str = e_opts[value]
+              add_opt.call(str, true)
+            else
+              raise Sequel::Error, "unrecognized value for Dataset#explain #{key.inspect} option: #{value.inspect}"
+            end
+          end
+        end
+
+        origin << ') ' unless paren
+        origin
+      end
+
+      # Add FOR PORTION OF SQL if the dataset uses it.
+      def table_for_portion_of_sql_append(sql)
+        fpo_column, fpo_range = @opts[:for_portion_of]
+        if fpo_column
+          table, aliaz = split_alias(@opts[:from].first)
+          source_list_append(sql, [table])
+          sql << ' FOR PORTION OF '
+          literal_append(sql, fpo_column)
+
+          if fpo_range.is_a?(Array)
+            fpo_start, fpo_end = fpo_range
+            sql << ' FROM '
+            literal_append(sql, fpo_start)
+            sql << ' TO '
+            literal_append(sql, fpo_end)
+          else
+            sql << ' ('
+            literal_append(sql, fpo_range)
+            sql << ')'
+          end
+          as_sql_append(sql, aliaz) if aliaz
+        else
+          source_list_append(sql, @opts[:from][0..0])
+        end
+      end
+
       # Add ON CONFLICT clause if it should be used
       def insert_conflict_sql(sql)
         if opts = @opts[:insert_conflict]
@@ -2430,6 +2813,9 @@ module Sequel
       # Return the primary key to use for RETURNING in an INSERT statement
       def insert_pk
         (f = opts[:from]) && !f.empty? && (t = f.first)
+
+        t = t.call(self) if t.is_a? Sequel::SQL::DelayedEvaluation
+
         case t
         when Symbol, String, SQL::Identifier, SQL::QualifiedIdentifier
           if pk = db.primary_key(t)
@@ -2579,8 +2965,13 @@ module Sequel
       # Use SKIP LOCKED if skipping locked rows.
       def select_lock_sql(sql)
         lock = @opts[:lock]
-        if lock == :share
+        case lock
+        when :share
           sql << ' FOR SHARE'
+        when :no_key_update
+          sql << ' FOR NO KEY UPDATE'
+        when :key_share
+          sql << ' FOR KEY SHARE'
         else
           super
         end
@@ -2668,10 +3059,10 @@ module Sequel
         join_from_sql(:FROM, sql)
       end
 
-      # Only include the primary table in the main update clause
+      # Support FOR PORTION OF.
       def update_table_sql(sql)
         sql << ' '
-        source_list_append(sql, @opts[:from][0..0])
+        table_for_portion_of_sql_append(sql)
       end
     end
   end