sequel 4.36.0 → 5.61.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:
 #
@@ -22,10 +23,10 @@
 #  jb = Sequel.pg_jsonb(:jsonb_column)
 #
 # Also, on most Sequel expression objects, you can call the pg_json
-# or pg_jsonb # method:
+# or pg_jsonb method:
 #
-#   j = Sequel.expr(:json_column).pg_json
-#   jb = Sequel.expr(:jsonb_column).pg_jsonb
+#   j = Sequel[:json_column].pg_json
+#   jb = Sequel[:jsonb_column].pg_jsonb
 #
 # If you have loaded the {core_extensions extension}[rdoc-ref:doc/core_extensions.rdoc],
 # or you have loaded the core_refinements extension
@@ -61,16 +62,66 @@
 #
 # There are additional methods are are only supported on JSONBOp instances:
 #
-#   j - 1                  # (jsonb_column - 1)
-#   j.concat(:h)           # (jsonb_column || h)
-#   j.contain_all(:a)      # (jsonb_column ?& a)
-#   j.contain_any(:a)      # (jsonb_column ?| a)
-#   j.contains(:h)         # (jsonb_column @> h)
-#   j.contained_by(:h)     # (jsonb_column <@ h)
-#   j.delete_path(%w'0 a') # (jsonb_column #- ARRAY['0','a'])
-#   j.has_key?('a')        # (jsonb_column ? 'a')
-#   j.pretty               # jsonb_pretty(jsonb_column)
-#   j.set(%w'0 a', :h)     # jsonb_set(jsonb_column, ARRAY['0','a'], h, true)
+#   j - 1                     # (jsonb_column - 1)
+#   j.concat(:h)              # (jsonb_column || h)
+#   j.contain_all(:a)         # (jsonb_column ?& a)
+#   j.contain_any(:a)         # (jsonb_column ?| a)
+#   j.contains(:h)            # (jsonb_column @> h)
+#   j.contained_by(:h)        # (jsonb_column <@ h)
+#   j.delete_path(%w'0 a')    # (jsonb_column #- ARRAY['0','a'])
+#   j.has_key?('a')           # (jsonb_column ? 'a')
+#   j.insert(%w'0 a', 'a'=>1) # jsonb_insert(jsonb_column, ARRAY[0, 'a'], '{"a":1}'::jsonb, false)
+#   j.pretty                  # jsonb_pretty(jsonb_column)
+#   j.set(%w'0 a', :h)        # jsonb_set(jsonb_column, ARRAY['0','a'], h, true)
+#
+#   j.set_lax(%w'0 a', :h, false, 'raise_exception')
+#   # jsonb_set_lax(jsonb_column, ARRAY['0','a'], h, false, 'raise_exception')
+#
+# On PostgreSQL 12+ SQL/JSON path functions and operators are supported:
+#
+#   j.path_exists('$.foo')      # (jsonb_column @? '$.foo')
+#   j.path_match('$.foo')       # (jsonb_column @@ '$.foo')
+#
+#   j.path_exists!('$.foo')     # jsonb_path_exists(jsonb_column, '$.foo')
+#   j.path_match!('$.foo')      # jsonb_path_match(jsonb_column, '$.foo')
+#   j.path_query('$.foo')       # jsonb_path_query(jsonb_column, '$.foo')
+#   j.path_query_array('$.foo') # jsonb_path_query_array(jsonb_column, '$.foo')
+#   j.path_query_first('$.foo') # jsonb_path_query_first(jsonb_column, '$.foo')
+#
+# On PostgreSQL 13+ timezone-aware SQL/JSON path functions and operators are supported:
+#
+#   j.path_exists_tz!('$.foo')     # jsonb_path_exists_tz(jsonb_column, '$.foo')
+#   j.path_match_tz!('$.foo')      # jsonb_path_match_tz(jsonb_column, '$.foo')
+#   j.path_query_tz('$.foo')       # jsonb_path_query_tz(jsonb_column, '$.foo')
+#   j.path_query_array_tz('$.foo') # jsonb_path_query_array_tz(jsonb_column, '$.foo')
+#   j.path_query_first_tz('$.foo') # jsonb_path_query_first_tz(jsonb_column, '$.foo')
+#
+# For the PostgreSQL 12+ SQL/JSON path functions, one argument is required (+path+) and
+# two more arguments are optional (+vars+ and +silent+).  +path+ specifies the JSON path.
+# +vars+ specifies a hash or a string in JSON format of named variables to be
+# 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)
 #
 # 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
@@ -291,6 +342,26 @@ module Sequel
       CONTAINED_BY = ["(".freeze, " <@ ".freeze, ")".freeze].freeze
       DELETE_PATH = ["(".freeze, " #- ".freeze, ")".freeze].freeze
       HAS_KEY = ["(".freeze, " ? ".freeze, ")".freeze].freeze
+      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.
@@ -336,7 +407,7 @@ module Sequel
         bool_op(CONTAINED_BY, wrap_input_jsonb(other))
       end
 
-      # Check if the other jsonb contains all entries in the receiver:
+      # Removes the given path from the receiver.
       #
       #   jsonb_op.delete_path(:h) # (jsonb #- h)
       def delete_path(other)
@@ -351,19 +422,145 @@ module Sequel
       end
       alias include? has_key?
 
+      # Inserts the given jsonb value at the given path in the receiver.
+      # The default is to insert the value before the given path, but
+      # insert_after can be set to true to insert it after the given path.
+      #
+      #   jsonb_op.insert(['a', 'b'], h) # jsonb_insert(jsonb, ARRAY['a', 'b'], h, false)
+      #   jsonb_op.insert(['a', 'b'], h, true) # jsonb_insert(jsonb, ARRAY['a', 'b'], h, true)
+      def insert(path, other, insert_after=false)
+        self.class.new(function(:insert, wrap_input_array(path), wrap_input_jsonb(other), insert_after))
+      end
+
+      # Returns whether the JSON path returns any item for the json object.
+      #
+      #   json_op.path_exists("$.foo") # (json @? '$.foo')
+      def path_exists(path)
+        bool_op(PATH_EXISTS, path)
+      end
+
+      # Returns whether the JSON path returns any item for the json object.
+      #
+      #   json_op.path_exists!("$.foo")
+      #   # jsonb_path_exists(json, '$.foo')
+      #
+      #   json_op.path_exists!("$.foo ? ($ > $x)", x: 2)
+      #   # jsonb_path_exists(json, '$.foo ? ($ > $x)', '{"x":2}')
+      #
+      #   json_op.path_exists!("$.foo ? ($ > $x)", {x: 2}, true)
+      #   # jsonb_path_exists(json, '$.foo ? ($ > $x)', '{"x":2}', true)
+      def path_exists!(path, vars=nil, silent=nil)
+        Sequel::SQL::BooleanExpression.new(:NOOP, _path_function(:jsonb_path_exists, path, vars, silent))
+      end
+
+      # The same as #path_exists!, except that timezone-aware conversions are used for date/time values.
+      def path_exists_tz!(path, vars=nil, silent=nil)
+        Sequel::SQL::BooleanExpression.new(:NOOP, _path_function(:jsonb_path_exists_tz, path, vars, silent))
+      end
+
+      # Returns the first item of the result of JSON path predicate check for the json object.
+      # Returns nil if the first item is not true or false.
+      #
+      #   json_op.path_match("$.foo") # (json @@ '$.foo')
+      def path_match(path)
+        bool_op(PATH_MATCH, path)
+      end
+
+      # Returns the first item of the result of JSON path predicate check for the json object.
+      # Returns nil if the first item is not true or false and silent is true.
+      #
+      #   json_op.path_match!("$.foo")
+      #   # jsonb_path_match(json, '$.foo')
+      #
+      #   json_op.path_match!("$.foo ? ($ > $x)", x: 2)
+      #   # jsonb_path_match(json, '$.foo ? ($ > $x)', '{"x":2}')
+      #
+      #   json_op.path_match!("$.foo ? ($ > $x)", {x: 2}, true)
+      #   # jsonb_path_match(json, '$.foo ? ($ > $x)', '{"x":2}', true)
+      def path_match!(path, vars=nil, silent=nil)
+        Sequel::SQL::BooleanExpression.new(:NOOP, _path_function(:jsonb_path_match, path, vars, silent))
+      end
+
+      # The same as #path_match!, except that timezone-aware conversions are used for date/time values.
+      def path_match_tz!(path, vars=nil, silent=nil)
+        Sequel::SQL::BooleanExpression.new(:NOOP, _path_function(:jsonb_path_match_tz, path, vars, silent))
+      end
+
+      # Returns a set of all jsonb values specified by the JSON path
+      # for the json object.
+      #
+      #   json_op.path_query("$.foo")
+      #   # jsonb_path_query(json, '$.foo')
+      #
+      #   json_op.path_query("$.foo ? ($ > $x)", x: 2)
+      #   # jsonb_path_query(json, '$.foo ? ($ > $x)', '{"x":2}')
+      #
+      #   json_op.path_query("$.foo ? ($ > $x)", {x: 2}, true)
+      #   # jsonb_path_query(json, '$.foo ? ($ > $x)', '{"x":2}', true)
+      def path_query(path, vars=nil, silent=nil)
+        _path_function(:jsonb_path_query, path, vars, silent)
+      end
+
+      # The same as #path_query, except that timezone-aware conversions are used for date/time values.
+      def path_query_tz(path, vars=nil, silent=nil)
+        _path_function(:jsonb_path_query_tz, path, vars, silent)
+      end
+
+      # Returns a jsonb array of all values specified by the JSON path
+      # for the json object.
+      #
+      #   json_op.path_query_array("$.foo")
+      #   # jsonb_path_query_array(json, '$.foo')
+      #
+      #   json_op.path_query_array("$.foo ? ($ > $x)", x: 2)
+      #   # jsonb_path_query_array(json, '$.foo ? ($ > $x)', '{"x":2}')
+      #
+      #   json_op.path_query_array("$.foo ? ($ > $x)", {x: 2}, true)
+      #   # jsonb_path_query_array(json, '$.foo ? ($ > $x)', '{"x":2}', true)
+      def path_query_array(path, vars=nil, silent=nil)
+        JSONBOp.new(_path_function(:jsonb_path_query_array, path, vars, silent))
+      end
+
+      # The same as #path_query_array, except that timezone-aware conversions are used for date/time values.
+      def path_query_array_tz(path, vars=nil, silent=nil)
+        JSONBOp.new(_path_function(:jsonb_path_query_array_tz, path, vars, silent))
+      end
+
+      # Returns the first item of the result specified by the JSON path
+      # for the json object.
+      #
+      #   json_op.path_query_first("$.foo")
+      #   # jsonb_path_query_first(json, '$.foo')
+      #
+      #   json_op.path_query_first("$.foo ? ($ > $x)", x: 2)
+      #   # jsonb_path_query_first(json, '$.foo ? ($ > $x)', '{"x":2}')
+      #
+      #   json_op.path_query_first("$.foo ? ($ > $x)", {x: 2}, true)
+      #   # jsonb_path_query_first(json, '$.foo ? ($ > $x)', '{"x":2}', true)
+      def path_query_first(path, vars=nil, silent=nil)
+        JSONBOp.new(_path_function(:jsonb_path_query_first, path, vars, silent))
+      end
+
+      # The same as #path_query_first, except that timezone-aware conversions are used for date/time values.
+      def path_query_first_tz(path, vars=nil, silent=nil)
+        JSONBOp.new(_path_function(:jsonb_path_query_first_tz, path, vars, silent))
+      end
+
       # Return the receiver, since it is already a JSONBOp.
       def pg_jsonb
         self
       end
 
-      # Returns a json value for the object at the given path.
+      # Return a pretty printed version of the receiver as a string expression.
       #
       #   jsonb_op.pretty # jsonb_pretty(jsonb)
       def pretty
         Sequel::SQL::StringExpression.new(:NOOP, function(:pretty))
       end
 
-      # Returns a json value for the object at the given path.
+      # Set the given jsonb value at the given path in the receiver.
+      # By default, this will create the value if it does not exist, but
+      # create_missing can be set to false to not create a new value.
       #
       #   jsonb_op.set(['a', 'b'], h) # jsonb_set(jsonb, ARRAY['a', 'b'], h, true)
       #   jsonb_op.set(['a', 'b'], h, false) # jsonb_set(jsonb, ARRAY['a', 'b'], h, false)
@@ -371,8 +568,30 @@ module Sequel
         self.class.new(function(:set, wrap_input_array(path), wrap_input_jsonb(other), create_missing))
       end
 
+      # The same as #set, except if +other+ is +nil+, then behaves according to +null_value_treatment+,
+      # which can be one of 'raise_exception', 'use_json_null' (default), 'delete_key', or 'return_target'.
+      def set_lax(path, other, create_missing=true, null_value_treatment='use_json_null')
+        self.class.new(function(:set_lax, wrap_input_array(path), wrap_input_jsonb(other), create_missing, null_value_treatment))
+      end
+
       private
 
+      # Internals of the jsonb SQL/JSON path functions.
+      def _path_function(func, path, vars, silent)
+        args = []
+        if vars
+          if vars.is_a?(Hash)
+            vars = vars.to_json
+          end
+          args << vars
+
+          unless silent.nil?
+            args << silent
+          end
+        end
+        SQL::Function.new(func, self, path, *args)
+      end
+
       # Return a placeholder literal with the given str and args, wrapped
       # in a boolean expression, used by operators that return booleans.
       def bool_op(str, other)
@@ -403,6 +622,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.
@@ -417,7 +667,9 @@ module Sequel
       end
     end
 
+    # :nocov:
     if defined?(JSONArray)
+    # :nocov:
       class JSONArray
         # Wrap the JSONArray instance in an JSONOp, allowing you to easily use
         # the PostgreSQL json functions and operators with literal jsons.
@@ -493,7 +745,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_loose_count.rb

@@ -8,11 +8,13 @@
 #
 # It can also support schema qualified tables:
 #
-#   DB.loose_count(:schema__table) # => 123456
+#   DB.loose_count(Sequel[:schema][:table]) # => 123456
 #
 # How accurate this count is depends on the number of rows
 # added/deleted from the table since the last time it was
-# analyzed.
+# analyzed. If the table has not been vacuumed or analyzed
+# yet, this can return 0 or -1 depending on the PostgreSQL
+# version in use.
 # 
 # To load the extension into the database:
 #