sequel 5.45.0 → 5.77.0

data/lib/sequel/extensions/pg_json_ops.rb

@@ -3,7 +3,8 @@
 # The pg_json_ops extension adds support to Sequel's DSL to make
 # it easier to call PostgreSQL JSON functions and operators (added
 # first in PostgreSQL 9.3).  It also supports the JSONB functions
-# and operators added in PostgreSQL 9.4.
+# and operators added in PostgreSQL 9.4, as well as additional
+# functions and operators added in later versions.
 #
 # To load the extension:
 #
@@ -101,6 +102,36 @@
 # substituted in +path+. +silent+ specifies whether errors are suppressed. By default,
 # errors are not suppressed.
 #
+# On PostgreSQL 14+, The JSONB <tt>[]</tt> method will use subscripts instead of being
+# the same as +get+, if the value being wrapped is an identifer:
+#
+#   Sequel.pg_jsonb_op(:jsonb_column)[1]       # jsonb_column[1]
+#   Sequel.pg_jsonb_op(:jsonb_column)[1][2]    # jsonb_column[1][2]
+#   Sequel.pg_jsonb_op(Sequel[:j][:b])[1]      # j.b[1]
+#
+# This support allows you to use JSONB subscripts in UPDATE statements to update only
+# part of a column:
+#
+#   c = Sequel.pg_jsonb_op(:c)
+#   DB[:t].update(c['key1'] => '1', c['key2'] => '"a"')
+#   #  UPDATE "t" SET "c"['key1'] = '1', "c"['key2'] = '"a"'
+#
+# Note that you have to provide the value of a JSONB subscript as a JSONB value, so this
+# will update +key1+ to use the number <tt>1</tt>, and +key2+ to use the string <tt>a</tt>.
+# For this reason it may be simpler to use +to_json+:
+#
+#   c = Sequel.pg_jsonb_op(:c)
+#   DB[:t].update(c['key1'] => 1.to_json, c['key2'] => "a".to_json)
+#
+# On PostgreSQL 16+, the <tt>IS [NOT] JSON</tt> operator is supported:
+#
+#   j.is_json                              # j IS JSON
+#   j.is_json(type: :object)               # j IS JSON OBJECT
+#   j.is_json(type: :object, unique: true) # j IS JSON OBJECT WITH UNIQUE
+#   j.is_not_json                          # j IS NOT JSON
+#   j.is_not_json(type: :array)                # j IS NOT JSON ARRAY
+#   j.is_not_json(unique: true)                # j IS NOT JSON WITH UNIQUE
+#
 # If you are also using the pg_json extension, you should load it before
 # loading this extension.  Doing so will allow you to use the #op method on
 # JSONHash, JSONHarray, JSONBHash, and JSONBArray, allowing you to perform json/jsonb operations
@@ -129,6 +160,18 @@ module Sequel
       GET_PATH = ["(".freeze, " #> ".freeze, ")".freeze].freeze
       GET_PATH_TEXT = ["(".freeze, " #>> ".freeze, ")".freeze].freeze
 
+      IS_JSON = ["(".freeze, " IS JSON".freeze, "".freeze, ")".freeze].freeze
+      IS_NOT_JSON = ["(".freeze, " IS NOT JSON".freeze, "".freeze, ")".freeze].freeze
+      EMPTY_STRING = Sequel::LiteralString.new('').freeze
+      WITH_UNIQUE = Sequel::LiteralString.new(' WITH UNIQUE').freeze
+      IS_JSON_MAP = {
+        nil => EMPTY_STRING,
+        :value => Sequel::LiteralString.new(' VALUE').freeze,
+        :scalar => Sequel::LiteralString.new(' SCALAR').freeze,
+        :object => Sequel::LiteralString.new(' OBJECT').freeze,
+        :array => Sequel::LiteralString.new(' ARRAY').freeze
+      }.freeze
+
       # Get JSON array element or object field as json.  If an array is given,
       # gets the object at the specified path.
       #
@@ -211,6 +254,30 @@ module Sequel
         end
       end
 
+      # Return whether the json object can be parsed as JSON.
+      #
+      # Options:
+      # :type :: Check whether the json object can be parsed as a specific type
+      #          of JSON (:value, :scalar, :object, :array).
+      # :unique :: Check JSON objects for unique keys.
+      #
+      #   json_op.is_json                 # json IS JSON
+      #   json_op.is_json(type: :object)  # json IS JSON OBJECT
+      #   json_op.is_json(unique: true)   # json IS JSON WITH UNIQUE
+      def is_json(opts=OPTS)
+        _is_json(IS_JSON, opts)
+      end
+
+      # Return whether the json object cannot be parsed as JSON. The opposite
+      # of #is_json. See #is_json for options.
+      #
+      #   json_op.is_not_json                 # json IS NOT JSON
+      #   json_op.is_not_json(type: :object)  # json IS NOT JSON OBJECT
+      #   json_op.is_not_json(unique: true)   # json IS NOT JSON WITH UNIQUE
+      def is_not_json(opts=OPTS)
+        _is_json(IS_NOT_JSON, opts)
+      end
+
       # Returns a set of keys AS text in the json object.
       #
       #   json_op.keys # json_object_keys(json)
@@ -264,6 +331,13 @@ module Sequel
 
       private
 
+      # Internals of IS [NOT] JSON support
+      def _is_json(lit_array, opts)
+        raise Error, "invalid is_json :type option: #{opts[:type].inspect}" unless type = IS_JSON_MAP[opts[:type]]
+        unique = opts[:unique] ? WITH_UNIQUE : EMPTY_STRING
+        Sequel::SQL::BooleanExpression.new(:NOOP, Sequel::SQL::PlaceholderLiteralString.new(lit_array, [self, type, unique]))
+      end
+
       # Return a placeholder literal with the given str and args, wrapped
       # in an JSONOp or JSONBOp, used by operators that return json or jsonb.
       def json_op(str, args)
@@ -323,6 +397,24 @@ module Sequel
       PATH_EXISTS = ["(".freeze, " @? ".freeze, ")".freeze].freeze
       PATH_MATCH = ["(".freeze, " @@ ".freeze, ")".freeze].freeze
 
+      # Support subscript syntax for JSONB.
+      def [](key)
+        if is_array?(key)
+          super
+        else
+          case @value
+          when Symbol, SQL::Identifier, SQL::QualifiedIdentifier, JSONBSubscriptOp
+            # Only use subscripts for identifiers.  In other cases, switching from
+            # the -> operator to [] for subscripts causes SQL syntax issues.  You
+            # only need the [] for subscripting when doing assignment, and
+            # assignment is generally done on identifiers.
+            self.class.new(JSONBSubscriptOp.new(self, key))
+          else
+            super
+          end
+        end
+      end
+
       # jsonb expression for deletion of the given argument from the
       # current jsonb.
       #
@@ -582,6 +674,37 @@ module Sequel
       end
     end
 
+    # Represents JSONB subscripts. This is abstracted because the
+    # subscript support depends on the database version.
+    class JSONBSubscriptOp < SQL::Expression
+      SUBSCRIPT = ["".freeze, "[".freeze, "]".freeze].freeze
+
+      # The expression being subscripted
+      attr_reader :expression
+
+      # The subscript to use
+      attr_reader :sub
+
+      # Set the expression and subscript to the given arguments
+      def initialize(expression, sub)
+        @expression = expression
+        @sub = sub
+        freeze
+      end
+
+      # Use subscripts instead of -> operator on PostgreSQL 14+
+      def to_s_append(ds, sql)
+        server_version = ds.db.server_version
+        frag = server_version && server_version >= 140000 ? SUBSCRIPT : JSONOp::GET
+        ds.literal_append(sql, Sequel::SQL::PlaceholderLiteralString.new(frag, [@expression, @sub]))
+      end
+
+      # Support transforming of jsonb subscripts
+      def sequel_ast_transform(transformer)
+        self.class.new(transformer.call(@expression), transformer.call(@sub))
+      end
+    end
+
     module JSONOpMethods
       # Wrap the receiver in an JSONOp so you can easily use the PostgreSQL
       # json functions and operators with it.
@@ -674,7 +797,7 @@ end
 if defined?(Sequel::CoreRefinements)
   module Sequel::CoreRefinements
     refine Symbol do
-      include Sequel::Postgres::JSONOpMethods
+      send INCLUDE_METH, Sequel::Postgres::JSONOpMethods
     end
   end
 end

data/lib/sequel/extensions/pg_multirange.rb

@@ -0,0 +1,367 @@
+# frozen-string-literal: true
+#
+# The pg_multirange extension adds support for the PostgreSQL 14+ multirange
+# types to Sequel.  PostgreSQL multirange types are similar to an array of
+# ranges, where a match against the multirange is a match against any of the
+# ranges in the multirange.
+#
+# When PostgreSQL multirange values are retrieved, they are parsed and returned
+# as instances of Sequel::Postgres::PGMultiRange.  PGMultiRange mostly acts
+# like an array of Sequel::Postgres::PGRange (see the pg_range extension).
+#
+# In addition to the parser, this extension comes with literalizers
+# for PGMultiRanges, so they can be used in queries and as bound variables.
+#
+# To turn an existing array of Ranges into a PGMultiRange, use Sequel.pg_multirange.
+# You must provide the type of multirange when creating the multirange:
+#
+#   Sequel.pg_multirange(array_of_date_ranges, :datemultirange)
+#
+# To use this extension, load it into the Database instance:
+#
+#   DB.extension :pg_multirange
+#
+# See the {schema modification guide}[rdoc-ref:doc/schema_modification.rdoc]
+# for details on using multirange type columns in CREATE/ALTER TABLE statements.
+#
+# This extension makes it easy to add support for other multirange types.  In
+# general, you just need to make sure that the subtype is handled and has the
+# appropriate converter installed.  For user defined
+# types, you can do this via:
+#
+#   DB.add_conversion_proc(subtype_oid){|string| }
+#
+# Then you can call
+# Sequel::Postgres::PGMultiRange::DatabaseMethods#register_multirange_type
+# to automatically set up a handler for the range type.  So if you
+# want to support the timemultirange type (assuming the time type is already
+# supported):
+#
+#   DB.register_multirange_type('timerange')
+#
+# This extension integrates with the pg_array extension.  If you plan
+# to use arrays of multirange types, load the pg_array extension before the
+# pg_multirange extension:
+#
+#   DB.extension :pg_array, :pg_multirange
+#
+# The pg_multirange extension will automatically load the pg_range extension.
+#
+# Related module: Sequel::Postgres::PGMultiRange
+
+require 'delegate'
+require 'strscan'
+
+module Sequel
+  module Postgres
+    class PGMultiRange < DelegateClass(Array)
+      include Sequel::SQL::AliasMethods
+
+      # Converts strings into PGMultiRange instances.
+      class Parser < StringScanner
+        def initialize(source, converter)
+          super(source)
+          @converter = converter 
+        end
+
+        # Parse the multirange type input string into a PGMultiRange value.
+        def parse
+          raise Sequel::Error, "invalid multirange, doesn't start with {" unless get_byte == '{'
+          ranges = []
+
+          unless scan(/\}/)
+            while true
+              raise Sequel::Error, "unfinished multirange" unless range_string = scan_until(/[\]\)]/)
+              ranges << @converter.call(range_string)
+              
+              case sep = get_byte
+              when '}'
+                break
+              when ','
+                # nothing
+              else
+                raise Sequel::Error, "invalid multirange separator: #{sep.inspect}"
+              end
+            end
+          end
+
+          raise Sequel::Error, "invalid multirange, remaining data after }" unless eos?
+          ranges
+        end
+      end
+
+      # Callable object that takes the input string and parses it using Parser.
+      class Creator
+        # The database type to set on the PGMultiRange instances returned.
+        attr_reader :type
+
+        def initialize(type, converter=nil)
+          @type = type
+          @converter = converter
+        end
+
+        # Parse the string using Parser with the appropriate
+        # converter, and return a PGMultiRange with the appropriate database
+        # type.
+        def call(string)
+          PGMultiRange.new(Parser.new(string, @converter).parse, @type)
+        end
+      end
+
+      module DatabaseMethods
+        # Add the default multirange conversion procs to the database
+        def self.extended(db)
+          db.instance_exec do
+            raise Error, "multiranges not supported on this database" unless server_version >= 140000
+
+            extension :pg_range
+            @pg_multirange_schema_types ||= {}
+
+            register_multirange_type('int4multirange', :range_oid=>3904, :oid=>4451)
+            register_multirange_type('nummultirange', :range_oid=>3906, :oid=>4532)
+            register_multirange_type('tsmultirange', :range_oid=>3908, :oid=>4533)
+            register_multirange_type('tstzmultirange', :range_oid=>3910, :oid=>4534)
+            register_multirange_type('datemultirange', :range_oid=>3912, :oid=>4535)
+            register_multirange_type('int8multirange', :range_oid=>3926, :oid=>4536)
+
+            if respond_to?(:register_array_type)
+              register_array_type('int4multirange', :oid=>6150, :scalar_oid=>4451, :scalar_typecast=>:int4multirange)
+              register_array_type('nummultirange', :oid=>6151, :scalar_oid=>4532, :scalar_typecast=>:nummultirange)
+              register_array_type('tsmultirange', :oid=>6152, :scalar_oid=>4533, :scalar_typecast=>:tsmultirange)
+              register_array_type('tstzmultirange', :oid=>6153, :scalar_oid=>4534, :scalar_typecast=>:tstzmultirange)
+              register_array_type('datemultirange', :oid=>6155, :scalar_oid=>4535, :scalar_typecast=>:datemultirange)
+              register_array_type('int8multirange', :oid=>6157, :scalar_oid=>4536, :scalar_typecast=>:int8multirange)
+            end
+
+            [:int4multirange, :nummultirange, :tsmultirange, :tstzmultirange, :datemultirange, :int8multirange].each do |v|
+              @schema_type_classes[v] = PGMultiRange
+            end
+
+            procs = conversion_procs
+            add_conversion_proc(4533, PGMultiRange::Creator.new("tsmultirange", procs[3908]))
+            add_conversion_proc(4534, PGMultiRange::Creator.new("tstzmultirange", procs[3910]))
+
+            if respond_to?(:register_array_type) && defined?(PGArray::Creator)
+              add_conversion_proc(6152, PGArray::Creator.new("tsmultirange", procs[4533]))
+              add_conversion_proc(6153, PGArray::Creator.new("tstzmultirange", procs[4534]))
+            end
+          end
+        end
+
+        # Handle PGMultiRange values in bound variables
+        def bound_variable_arg(arg, conn)
+          case arg
+          when PGMultiRange 
+            arg.unquoted_literal(schema_utility_dataset)
+          else
+            super
+          end
+        end
+
+        # Freeze the pg multirange schema types to prevent adding new ones.
+        def freeze
+          @pg_multirange_schema_types.freeze
+          super
+        end
+
+        # Register a database specific multirange type.  This can be used to support
+        # different multirange types per Database.  Options:
+        #
+        # :converter :: A callable object (e.g. Proc), that is called with the PostgreSQL range string,
+        #               and should return a PGRange instance.
+        # :oid :: The PostgreSQL OID for the multirange type.  This is used by Sequel to set up automatic type
+        #         conversion on retrieval from the database.
+        # :range_oid :: Should be the PostgreSQL OID for the multirange subtype (the range type). If given,
+        #               automatically sets the :converter option by looking for scalar conversion
+        #               proc.
+        #
+        # If a block is given, it is treated as the :converter option.
+        def register_multirange_type(db_type, opts=OPTS, &block)
+          oid = opts[:oid]
+          soid = opts[:range_oid]
+
+          if has_converter = opts.has_key?(:converter)
+            raise Error, "can't provide both a block and :converter option to register_multirange_type" if block
+            converter = opts[:converter]
+          else
+            has_converter = true if block
+            converter = block
+          end
+
+          unless (soid || has_converter) && oid
+            range_oid, subtype_oid = from(:pg_range).join(:pg_type, :oid=>:rngmultitypid).where(:typname=>db_type.to_s).get([:rngmultitypid, :rngtypid])
+            soid ||= subtype_oid unless has_converter
+            oid ||= range_oid
+          end
+
+          db_type = db_type.to_s.dup.freeze
+
+          if soid
+            raise Error, "can't provide both a converter and :range_oid option to register" if has_converter 
+            raise Error, "no conversion proc for :range_oid=>#{soid.inspect} in conversion_procs" unless converter = conversion_procs[soid]
+          end
+
+          raise Error, "cannot add a multirange type without a convertor (use :converter or :range_oid option or pass block)" unless converter
+          creator = Creator.new(db_type, converter)
+          add_conversion_proc(oid, creator)
+
+          @pg_multirange_schema_types[db_type] = db_type.to_sym
+
+          singleton_class.class_eval do
+            meth = :"typecast_value_#{db_type}"
+            scalar_typecast_method = :"typecast_value_#{opts.fetch(:scalar_typecast, db_type.sub('multirange', 'range'))}"
+            define_method(meth){|v| typecast_value_pg_multirange(v, creator, scalar_typecast_method)}
+            private meth
+          end
+
+          @schema_type_classes[db_type] = PGMultiRange
+          nil
+        end
+
+        private
+
+        # Recognize the registered database multirange types.
+        def schema_multirange_type(db_type)
+          @pg_multirange_schema_types[db_type] || super
+        end
+
+        # Set the :ruby_default value if the default value is recognized as a multirange.
+        def schema_post_process(_)
+          super.each do |a|
+            h = a[1]
+            db_type = h[:db_type]
+            if @pg_multirange_schema_types[db_type] && h[:default] =~ /\A#{db_type}\(.*\)\z/
+              h[:ruby_default] = get(Sequel.lit(h[:default])) 
+            end
+          end
+        end
+
+        # Given a value to typecast and the type of PGMultiRange subclass:
+        # * If given a PGMultiRange with a matching type, use it directly.
+        # * If given a PGMultiRange with a different type, return a PGMultiRange
+        #   with the creator's type.
+        # * If given an Array, create a new PGMultiRange instance for it, typecasting
+        #   each instance using the scalar_typecast_method.
+        def typecast_value_pg_multirange(value, creator, scalar_typecast_method=nil)
+          case value
+          when PGMultiRange
+            return value if value.db_type == creator.type
+          when Array
+            # nothing
+          else
+            raise Sequel::InvalidValue, "invalid value for multirange type: #{value.inspect}"
+          end
+
+          if scalar_typecast_method && respond_to?(scalar_typecast_method, true)
+            value = value.map{|v| send(scalar_typecast_method, v)}
+          end
+          PGMultiRange.new(value, creator.type)
+        end
+      end
+
+      # The type of this multirange (e.g. 'int4multirange').
+      attr_accessor :db_type
+
+      # Set the array of ranges to delegate to, and the database type.
+      def initialize(ranges, db_type)
+        super(ranges)
+        @db_type = db_type.to_s
+      end
+
+      # Append the multirange SQL to the given sql string. 
+      def sql_literal_append(ds, sql)
+        sql << db_type << '('
+        joiner = nil
+        conversion_meth = nil
+        each do |range|
+          if joiner
+            sql << joiner
+          else
+            joiner = ', '
+          end
+
+          unless range.is_a?(PGRange)
+            conversion_meth ||= :"typecast_value_#{db_type.sub('multi', '')}"
+            range = ds.db.send(conversion_meth, range)
+          end
+
+          ds.literal_append(sql, range)
+        end
+        sql << ')'
+      end
+
+      # Return whether the value is inside any of the ranges in the multirange.
+      def cover?(value)
+        any?{|range| range.cover?(value)}
+      end
+      alias === cover?
+
+      # Don't consider multiranges with different database types equal.
+      def eql?(other)
+        if PGMultiRange === other
+          return false unless other.db_type == db_type
+          other = other.__getobj__
+        end
+        __getobj__.eql?(other)
+      end
+
+      # Don't consider multiranges with different database types equal.
+      def ==(other)
+        return false if PGMultiRange === other && other.db_type != db_type
+        super
+      end
+
+      # Return a string containing the unescaped version of the multirange.
+      # Separated out for use by the bound argument code.
+      def unquoted_literal(ds)
+        val = String.new
+        val << "{"
+
+        joiner = nil
+        conversion_meth = nil
+        each do |range|
+          if joiner
+            val << joiner
+          else
+            joiner = ', '
+          end
+
+          unless range.is_a?(PGRange)
+            conversion_meth ||= :"typecast_value_#{db_type.sub('multi', '')}"
+            range = ds.db.send(conversion_meth, range)
+          end
+
+          val << range.unquoted_literal(ds)
+        end
+         
+        val << "}"
+      end
+
+      # Allow automatic parameterization.
+      def sequel_auto_param_type(ds)
+        "::#{db_type}"
+      end
+    end
+  end
+
+  module SQL::Builders
+    # Convert the object to a Postgres::PGMultiRange.
+    def pg_multirange(v, db_type)
+      case v
+      when Postgres::PGMultiRange
+        if v.db_type == db_type
+          v
+        else
+          Postgres::PGMultiRange.new(v, db_type)
+        end
+      when Array
+        Postgres::PGMultiRange.new(v, db_type)
+      else
+        # May not be defined unless the pg_range_ops extension is used
+        pg_range_op(v)
+      end
+    end
+  end
+
+  Database.register_extension(:pg_multirange, Postgres::PGMultiRange::DatabaseMethods)
+end

data/lib/sequel/extensions/pg_range.rb

@@ -4,12 +4,9 @@
 # types to Sequel.  PostgreSQL range types are similar to ruby's
 # Range class, representating an array of values.  However, they
 # are more flexible than ruby's ranges, allowing exclusive beginnings
-# and endings (ruby's range only allows exclusive endings), and
-# unbounded beginnings and endings (which ruby's range does not
-# support).
+# and endings (ruby's range only allows exclusive endings).
 #
-# This extension integrates with Sequel's native postgres and jdbc/postgresql adapters, so
-# that when range type values are retrieved, they are parsed and returned
+# When PostgreSQL range values are retreived, they are parsed and returned
 # as instances of Sequel::Postgres::PGRange.  PGRange mostly acts
 # like a Range, but it's not a Range as not all PostgreSQL range
 # type values would be valid ruby ranges.  If the range type value
@@ -19,8 +16,7 @@
 # exception will be raised.
 #
 # In addition to the parser, this extension comes with literalizers
-# for both PGRange and Range that use the standard Sequel literalization
-# callbacks, so they work on all adapters.
+# for PGRange and Range, so they can be used in queries and as bound variables.
 #
 # To turn an existing Range into a PGRange, use Sequel.pg_range:
 #
@@ -237,23 +233,9 @@ module Sequel
 
         private
 
-        # Handle arrays of range types in bound variables.
-        def bound_variable_array(a)
-          case a
-          when PGRange, Range
-            "\"#{bound_variable_arg(a, nil)}\""
-          else
-            super
-          end
-        end
-
         # Recognize the registered database range types.
-        def schema_column_type(db_type)
-          if type = @pg_range_schema_types[db_type]
-            type
-          else
-            super
-          end
+        def schema_range_type(db_type)
+          @pg_range_schema_types[db_type] || super
         end
 
         # Set the :ruby_default value if the default value is recognized as a range.
@@ -290,7 +272,7 @@ module Sequel
           when Range
             PGRange.from_range(value, parser.db_type)
           when String
-            parser.call(value)
+            parser.call(typecast_check_string_length(value, 100))
           else
             raise Sequel::InvalidValue, "invalid value for range type: #{value.inspect}"
           end
@@ -499,6 +481,11 @@ module Sequel
         end
       end
 
+      # Allow automatic parameterization for ranges with types.
+      def sequel_auto_param_type(ds)
+        "::#{db_type}" if db_type
+      end
+
       private
 
       # Escape common range types.  Instead of quoting, just backslash escape all
@@ -507,8 +494,8 @@ module Sequel
         case k
         when nil
           ''
-        when Date, Time
-          ds.literal(k)[1...-1]
+        when Time, Date
+          ds.literal_date_or_time(k, true)
         when Integer, Float
           k.to_s
         when BigDecimal