sequel 3.21.0 → 3.41.0

data/lib/sequel/extensions/pg_array_ops.rb

@@ -0,0 +1,263 @@
+# The pg_array_ops extension adds support to Sequel's DSL to make
+# it easier to call PostgreSQL array functions and operators.
+#
+# To load the extension:
+#
+#   Sequel.extension :pg_array_ops
+#
+# The most common usage is passing an expression to Sequel.pg_array_op:
+#
+#   ia = Sequel.pg_array_op(:int_array_column)
+#
+# If you have also loaded the pg_array extension, you can use
+# Sequel.pg_array as well:
+#
+#   ia = Sequel.pg_array(:int_array_column)
+#
+# Also, on most Sequel expression objects, you can call the pg_array
+# method:
+#
+#   ia = Sequel.expr(:int_array_column).pg_array
+#
+# If you have loaded the {core_extensions extension}[link:files/doc/core_extensions_rdoc.html]),
+# you can also call Symbol#pg_array:
+#
+#   ia = :int_array_column.pg_array
+#
+# This creates a Sequel::Postgres::ArrayOp object that can be used
+# for easier querying:
+#
+#   ia[1]     # int_array_column[1]
+#   ia[1][2]  # int_array_column[1][2]
+#
+#   ia.contains(:other_int_array_column)     # @> 
+#   ia.contained_by(:other_int_array_column) # <@
+#   ia.overlaps(:other_int_array_column)     # &&
+#   ia.concat(:other_int_array_column)       # ||
+#
+#   ia.push(1)         # int_array_column || 1
+#   ia.unshift(1)      # 1 || int_array_column
+#
+#   ia.any             # ANY(int_array_column)
+#   ia.all             # ALL(int_array_column)
+#   ia.dims            # array_dims(int_array_column)
+#   ia.length          # array_length(int_array_column, 1)
+#   ia.length(2)       # array_length(int_array_column, 2)
+#   ia.lower           # array_lower(int_array_column, 1)
+#   ia.lower(2)        # array_lower(int_array_column, 2)
+#   ia.join            # array_to_string(int_array_column, '', NULL)
+#   ia.join(':')       # array_to_string(int_array_column, ':', NULL)
+#   ia.join(':', ' ')  # array_to_string(int_array_column, ':', ' ')
+#   ia.unnest          # unnest(int_array_column)
+# 
+# See the PostgreSQL array function and operator documentation for more
+# details on what these functions and operators do.
+#
+# If you are also using the pg_array extension, you should load it before
+# loading this extension.  Doing so will allow you to use PGArray#op to get
+# an ArrayOp, allowing you to perform array operations on array literals.
+module Sequel
+  module Postgres
+    # The ArrayOp class is a simple container for a single object that
+    # defines methods that yield Sequel expression objects representing
+    # PostgreSQL array operators and functions.
+    #
+    # In the method documentation examples, assume that:
+    #
+    #   array_op = :array.pg_array
+    class ArrayOp < Sequel::SQL::Wrapper
+      CONCAT = ["(".freeze, " || ".freeze, ")".freeze].freeze
+      CONTAINS = ["(".freeze, " @> ".freeze, ")".freeze].freeze
+      CONTAINED_BY = ["(".freeze, " <@ ".freeze, ")".freeze].freeze
+      OVERLAPS = ["(".freeze, " && ".freeze, ")".freeze].freeze
+
+      # Access a member of the array, returns an SQL::Subscript instance:
+      #
+      #   array_op[1] # array[1]
+      def [](key)
+        Sequel::SQL::Subscript.new(self, [key])
+      end
+
+      # Call the ALL function:
+      #
+      #   array_op.all # ALL(array)
+      #
+      # Usually used like:
+      #
+      #   dataset.where(1=>array_op.all)
+      #   # WHERE (1 = ALL(array))
+      def all
+        function(:ALL)
+      end
+
+      # Call the ANY function:
+      #
+      #   array_op.all # ANY(array)
+      #
+      # Usually used like:
+      #
+      #   dataset.where(1=>array_op.any)
+      #   # WHERE (1 = ANY(array))
+      def any
+        function(:ANY)
+      end
+
+      # Use the contains (@>) operator:
+      #
+      #   array_op.contains(:a) # (array @> a)
+      def contains(other)
+        bool_op(CONTAINS, wrap_array(other))
+      end
+
+      # Use the contained by (<@) operator:
+      #
+      #   array_op.contained_by(:a) # (array <@ a)
+      def contained_by(other)
+        bool_op(CONTAINED_BY, wrap_array(other))
+      end
+
+      # Call the array_dims method:
+      #
+      #   array_op.dims # array_dims(array)
+      def dims
+        function(:array_dims)
+      end
+
+      # Call the array_length method:
+      #
+      #   array_op.length    # array_length(array, 1)
+      #   array_op.length(2) # array_length(array, 2)
+      def length(dimension = 1)
+        function(:array_length, dimension)
+      end
+      
+      # Call the array_lower method:
+      #
+      #   array_op.lower    # array_lower(array, 1)
+      #   array_op.lower(2) # array_lower(array, 2)
+      def lower(dimension = 1)
+        function(:array_lower, dimension)
+      end
+      
+      # Use the overlaps (&&) operator:
+      #
+      #   array_op.overlaps(:a) # (array && a)
+      def overlaps(other)
+        bool_op(OVERLAPS, wrap_array(other))
+      end
+
+      # Use the concatentation (||) operator:
+      #
+      #   array_op.push(:a) # (array || a)
+      #   array_op.concat(:a) # (array || a)
+      def push(other)
+        array_op(CONCAT, [self, wrap_array(other)])
+      end
+      alias concat push
+
+      # Return the receiver.
+      def pg_array
+        self
+      end
+
+      # Call the array_to_string method:
+      #
+      #   array_op.join           # array_to_string(array, '', NULL)
+      #   array_op.to_string      # array_to_string(array, '', NULL)
+      #   array_op.join(":")      # array_to_string(array, ':', NULL)
+      #   array_op.join(":", "*") # array_to_string(array, ':', '*')
+      def to_string(joiner="", null=nil)
+        function(:array_to_string, joiner, null)
+      end
+      alias join to_string
+      
+      # Call the unnest method:
+      #
+      #   array_op.unnest # unnest(array)
+      def unnest
+        function(:unnest)
+      end
+      
+      # Use the concatentation (||) operator, reversing the order:
+      #
+      #   array_op.unshift(:a) # (a || array)
+      def unshift(other)
+        array_op(CONCAT, [wrap_array(other), self])
+      end
+
+      private
+
+      # Return a placeholder literal with the given str and args, wrapped
+      # in an ArrayOp, used by operators that return arrays.
+      def array_op(str, args)
+        ArrayOp.new(Sequel::SQL::PlaceholderLiteralString.new(str, 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)
+        Sequel::SQL::BooleanExpression.new(:NOOP, Sequel::SQL::PlaceholderLiteralString.new(str, [value, other]))
+      end
+
+      # Return a function with the given name, and the receiver as the first
+      # argument, with any additional arguments given.
+      def function(name, *args)
+        SQL::Function.new(name, self, *args)
+      end
+
+      # Automatically wrap argument in a PGArray if it is a plain Array.
+      # Requires that the pg_array extension has been loaded to work.
+      def wrap_array(arg)
+        if arg.instance_of?(Array)
+          Sequel.pg_array(arg)
+        else
+          arg
+        end
+      end
+    end
+
+    module ArrayOpMethods
+      # Wrap the receiver in an ArrayOp so you can easily use the PostgreSQL
+      # array functions and operators with it.
+      def pg_array
+        ArrayOp.new(self)
+      end
+    end
+
+    if defined?(PGArray)
+      class PGArray
+        # Wrap the PGArray instance in an ArrayOp, allowing you to easily use
+        # the PostgreSQL array functions and operators with literal arrays.
+        def op
+          ArrayOp.new(self)
+        end
+      end
+    end
+  end
+
+  module SQL::Builders
+    # Return the object wrapped in an Postgres::ArrayOp.
+    def pg_array_op(v)
+      case v
+      when Postgres::ArrayOp
+        v
+      else
+        Postgres::ArrayOp.new(v)
+      end
+    end
+  end
+
+  class SQL::GenericExpression
+    include Sequel::Postgres::ArrayOpMethods
+  end
+
+  class LiteralString
+    include Sequel::Postgres::ArrayOpMethods
+  end
+end
+
+if Sequel.core_extensions?
+  class Symbol
+    include Sequel::Postgres::ArrayOpMethods
+  end
+end

data/lib/sequel/extensions/pg_auto_parameterize.rb

@@ -0,0 +1,175 @@
+# This extension allows Sequel's postgres adapter to automatically
+# parameterize all common queries.  Sequel's default behavior has always
+# been to literalize all arguments unless specifically using
+# parameters (via :$arg placeholders and the prepare/call methods).
+# This extension makes Sequel take all string, numeric, date, and
+# time types and automatically turn them into parameters. Example:
+#
+#   # Default
+#   DB[:test].where(:a=>1)
+#   # SQL: SELECT * FROM test WHERE a = 1
+#
+#   DB.extension :pg_auto_parameterize
+#   DB[:test].where(:a=>1)
+#   # SQL: SELECT * FROM test WHERE a = $1 (args: [1])
+#
+# This extension is not necessarily faster or more safe than the
+# default behavior.  In some cases it is faster, such as when using
+# large strings.  However, there are also some known issues with
+# this approach:
+#
+# 1. Because of the way it operates, it has no context to make a
+#    determination about whether to literalize an object or not.
+#    For example, if it comes across an integer, it will turn it
+#    into a parameter.  That breaks code such as:
+#
+#      DB[:table].select(:a, :b).order(2, 1)
+#
+#    Since it will use the following SQL (which isn't valid):
+#
+#      SELECT a, b FROM table ORDER BY $1, $2
+#     
+#    To work around this, you can either specify the columns
+#    manually or use a literal string:
+#
+#      DB[:table].select(:a, :b).order(:b, :a)
+#      DB[:table].select(:a, :b).order(Sequel.lit('2, 1'))
+#
+# 2. In order to avoid many type errors, it attempts to guess the
+#    appropriate type and automatically casts all placeholders.
+#    Unfortunately, if the type guess is incorrect, the query will
+#    be rejected.  For example, the following works without
+#    automatic parameterization, but fails with it:
+#
+#      DB[:table].insert(:interval=>'1 day')
+#
+#    To work around this, you can just add the necessary casts
+#    manually:
+#
+#      DB[:table].insert(:interval=>'1 day'.cast(:interval))
+#
+# You can also work around any issues that come up by disabling automatic
+# parameterization by calling the no_auto_parameterize method on the
+# dataset (which returns a clone of the dataset).
+#
+# It is likely there are other corner cases I am not yet aware of
+# when using this extension, so use this extension with caution.
+#
+# This extension is only compatible when using the pg driver, not
+# when using the old postgres driver or the postgres-pr driver.
+
+module Sequel
+  module Postgres
+    # Enable automatically parameterizing queries by hijacking the
+    # SQL query string that Sequel builds to also hold the array
+    # of parameters.
+    module AutoParameterize
+      # String that holds an array of parameters
+      class StringWithArray < ::String
+        PLACEHOLDER = '$'.freeze
+        CAST = '::'.freeze
+
+        # The array of parameters used by this query.
+        attr_reader :args
+
+        # Add a new parameter to this query, which adds
+        # the parameter to the array of parameters, and an
+        # SQL placeholder to the query itself.
+        def add_arg(s, type=nil)
+          @args ||= []
+          @args << s
+          self << PLACEHOLDER << @args.length.to_s
+          self << CAST << type.to_s if type
+        end
+
+        # Show args when the string is inspected
+        def inspect
+          @args ? "#{self}; #{@args.inspect}".inspect : super
+        end
+      end
+
+      module DatabaseMethods
+        # Extend the database's datasets with the necessary code.
+        def self.extended(db)
+          db.extend_datasets(DatasetMethods)
+        end
+
+        # If the sql string has an embedded parameter array,
+        # extract the arguments from that.
+        def execute(sql, opts={})
+          if sql.is_a?(StringWithArray) && (args = sql.args)
+            opts = opts.merge(:arguments=>args)
+          end
+          super
+        end
+      end
+
+      module DatasetMethods
+        # Return a clone of the dataset that will not do
+        # automatic parameterization.
+        def no_auto_parameterize
+          clone(:no_auto_parameterize=>true)
+        end
+
+        # For strings, numeric arguments, and date/time arguments, add
+        # them as parameters to the query instead of literalizing them
+        # into the SQL.
+        def literal_append(sql, v)
+          if sql.is_a?(StringWithArray)
+            case v
+            when String
+              case v
+              when LiteralString
+                super
+              when Sequel::SQL::Blob
+                sql.add_arg(v, :bytea)
+              else
+                sql.add_arg(v)
+              end
+            when Bignum
+              sql.add_arg(v, :int8)
+            when Fixnum
+              sql.add_arg(v, :int4)
+            when Float
+              sql.add_arg(v, :"double precision")
+            when BigDecimal
+              sql.add_arg(v, :numeric)
+            when Sequel::SQLTime
+              sql.add_arg(v, :time)
+            when Time, DateTime
+              sql.add_arg(v, :timestamp)
+            when Date
+              sql.add_arg(v, :date)
+            else
+              super
+            end
+          else
+            super
+          end
+        end
+
+        def use_cursor(*)
+          super.no_auto_parameterize
+        end
+
+        protected
+
+        # Disable automatic parameterization for prepared statements,
+        # since they will use manual parameterization.
+        def to_prepared_statement(*a)
+          opts[:no_auto_parameterize] ? super : no_auto_parameterize.to_prepared_statement(*a)
+        end
+
+        private
+
+        # Unless auto parameterization is turned off, use a string that
+        # can store the parameterized arguments.
+        def sql_string_origin
+          opts[:no_auto_parameterize] ? super : StringWithArray.new
+        end
+      end
+    end
+  end
+
+  Database.register_extension(:pg_auto_parameterize, Postgres::AutoParameterize::DatabaseMethods)
+end