sequel 3.33.0 → 3.34.0

data/lib/sequel/extensions/pg_array_ops.rb

@@ -0,0 +1,220 @@
+# The pg_array_ops extension adds support to Sequel's DSL to make
+# it easier to call PostgreSQL array functions and operators. The
+# most common usage is taking an object that represents an SQL
+# identifier (such as a :symbol), and calling #pg_array on it:
+#
+#   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, other)
+      end
+
+      # Use the contained by (<@) operator:
+      #
+      #   array_op.contained_by(:a) # (array <@ a)
+      def contained_by(other)
+        bool_op(CONTAINED_BY, 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, 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, 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, [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
+    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
+
+  class SQL::GenericExpression
+    include Sequel::Postgres::ArrayOpMethods
+  end
+
+  class LiteralString
+    include Sequel::Postgres::ArrayOpMethods
+  end
+end
+
+class Symbol
+  include Sequel::Postgres::ArrayOpMethods
+end

data/lib/sequel/extensions/pg_auto_parameterize.rb

@@ -0,0 +1,174 @@
+# 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.extend Sequel::Postgres::AutoParameterize::DatabaseMethods
+#   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('2, 1'.lit)
+#
+# 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
+        # 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)
+          @args ||= []
+          @args << s
+          self << "$#{@args.length}::#{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
+        
+        # If the sql string has an embedded parameter array,
+        # extract the arguments from that.
+        def execute_insert(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, :text)
+              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
+
+        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
+end

data/lib/sequel/extensions/pg_hstore.rb

@@ -0,0 +1,296 @@
+# The pg_hstore extension adds support for the PostgreSQL hstore type
+# to Sequel.  hstore is an extension that ships with PostgreSQL, and
+# the hstore type stores an arbitrary key-value table, where the keys
+# are strings and the values are strings or NULL.
+#
+# This extension integrates with Sequel's native postgres adapter, so
+# that when hstore fields are retrieved, they are parsed and returned
+# as instances of Sequel::Postgres::HStore.  HStore is
+# a DelegateClass of Hash, so it mostly acts like a hash, but not
+# completely (is_a?(Hash) is false).  If you want the actual hash,
+# you can call Hstore#to_hash.  This is done so that Sequel does not
+# treat a HStore like a Hash by default, which would cause issues.
+#
+# In addition to the parsers, this extension comes with literalizers
+# for HStore using the standard Sequel literalization callbacks, so
+# they work with on all adapters.
+#
+# To turn an existing Hash into an HStore:
+#
+#   hash.hstore
+#
+# Since the hstore type only supports strings, non string keys and
+# values are converted to strings
+#
+#   {:foo=>1}.hstore.to_hash # {'foo'=>'1'}
+#   v = {}.hstore
+#   v[:foo] = 1
+#   v # {'foo'=>'1'}
+#
+# However, to make life easier, lookups by key are converted to
+# strings (even when accessing the underlying hash directly):
+#
+#   {'foo'=>'bar'}.hstore[:foo] # 'bar'
+#   {'foo'=>'bar'}.hstore.to_hash[:foo] # 'bar'
+# 
+# HStore instances mostly just delegate to the underlying hash
+# instance, so Hash methods that modify the receiver or returned
+# modified copies of the receiver may not do string conversion.
+# The following methods will handle string conversion, and more
+# can be added later if desired:
+#
+# * \[\]
+# * \[\]=
+# * assoc (ruby 1.9 only)
+# * delete
+# * fetch
+# * has_key?
+# * has_value?
+# * include?
+# * key (ruby 1.9 only)
+# * key?
+# * member?
+# * merge
+# * merge!
+# * rassoc (ruby 1.9 only)
+# * replace
+# * store
+# * update
+# * value?
+#
+# If you want to insert a hash into an hstore database column:
+#
+#   DB[:table].insert(:column=>{'foo'=>'bar'}.hstore)
+#
+# If you would like to use hstore columns in your model objects, you
+# probably want to modify the schema parsing/typecasting so that it
+# recognizes and correctly handles the hstore columns, which you can
+# do by:
+#
+#   DB.extend Sequel::Postgres::HStore::DatabaseMethods
+#
+# If you are not using the native postgres adapter, you probably
+# also want to use the typecast_on_load plugin in the model, and
+# set it to typecast the hstore column(s) on load.
+#
+# This extension requires the delegate and strscan libraries.
+
+require 'delegate'
+require 'strscan'
+
+module Sequel
+  module Postgres
+    class HStore < DelegateClass(Hash)
+      # Parser for PostgreSQL hstore output format.
+      class Parser < StringScanner
+        QUOTE_RE = /"/.freeze
+        KV_SEP_RE = /"\s*=>\s*/.freeze
+        NULL_RE = /NULL/.freeze
+        SEP_RE = /,\s*/.freeze
+        QUOTED_RE = /(\\"|[^"])*/.freeze
+        REPLACE_RE = /\\(.)/.freeze
+        REPLACE_WITH = '\1'.freeze
+
+        # Parse the output format that PostgreSQL uses for hstore
+        # columns.  Note that this does not attempt to parse all
+        # input formats that PostgreSQL will accept.  For instance,
+        # it expects all keys and non-NULL values to be quoted.
+        #
+        # Return the resulting hash of objects.  This can be called
+        # multiple times, it will cache the parsed hash on the first
+        # call and use it for subsequent calls.
+        def parse
+          return @result if @result
+          hash = {}
+          while !eos?
+            skip(QUOTE_RE)
+            k = parse_quoted
+            skip(KV_SEP_RE)
+            if skip(QUOTE_RE)
+              v = parse_quoted
+              skip(QUOTE_RE)
+            else
+              scan(NULL_RE)
+              v = nil
+            end
+            skip(SEP_RE)
+            hash[k] = v
+          end
+          @result = hash
+        end
+          
+        private
+
+        # Parse and unescape a quoted key/value.
+        def parse_quoted
+          scan(QUOTED_RE).gsub(REPLACE_RE, REPLACE_WITH)
+        end
+      end
+
+      module DatabaseMethods
+        # Reset the conversion procs if using the native postgres adapter.
+        def self.extended(db)
+          db.reset_conversion_procs if db.respond_to?(:reset_conversion_procs)
+        end
+
+        # Handle hstores in bound variables
+        def bound_variable_arg(arg, conn)
+          case arg
+          when HStore
+            arg.unquoted_literal
+          when Hash
+            HStore.new(arg).unquoted_literal
+          else
+            super
+          end
+        end
+
+        private
+
+        # Recognize the hstore database type.
+        def schema_column_type(db_type)
+          db_type == 'hstore' ? :hstore : super
+        end
+
+        # Typecast value correctly to HStore.  If already an
+        # HStore instance, return as is.  If a hash, return
+        # an HStore version of it.  If a string, assume it is
+        # in PostgreSQL output format and parse it using the
+        # parser.
+        def typecast_value_hstore(value)
+          case value
+          when HStore
+            value
+          when Hash
+            HStore.new(value)
+          when String
+            HStore.parse(value)
+          else
+            raise Sequel::InvalidValue, "invalid value for hstore: #{value.inspect}"
+          end
+        end
+      end
+
+      # Default proc used for all underlying HStore hashes, so that even
+      # if you grab the underlying hash, it will still convert non-string
+      # keys to strings during lookup.
+      DEFAULT_PROC = lambda{|h, k| h[k.to_s] unless k.is_a?(String)}
+
+      QUOTE = '"'.freeze
+      COMMA = ",".freeze
+      KV_SEP = "=>".freeze
+      NULL = "NULL".freeze
+      ESCAPE_RE = /("|\\)/.freeze
+      ESCAPE_REPLACE = '\\\\\1'.freeze
+      HSTORE_CAST = '::hstore'.freeze
+
+      # Parse the given string into an HStore, assuming the str is in PostgreSQL
+      # hstore output format.
+      def self.parse(str)
+        new(Parser.new(str).parse)
+      end
+
+      # Override methods that accept key argument to convert to string.
+      (%w'[] delete has_key? include? key? member?' + Array((%w'assoc' if RUBY_VERSION >= '1.9.0'))).each do |m|
+        class_eval("def #{m}(k) super(k.to_s) end", __FILE__, __LINE__)
+      end
+
+      # Override methods that accept value argument to convert to string unless nil.
+      (%w'has_value? value?' + Array((%w'key rassoc' if RUBY_VERSION >= '1.9.0'))).each do |m|
+        class_eval("def #{m}(v) super(convert_value(v)) end", __FILE__, __LINE__)
+      end
+
+      # Override methods that accept key and value arguments to convert to string appropriately.
+      %w'[]= store'.each do |m|
+        class_eval("def #{m}(k, v) super(k.to_s, convert_value(v)) end", __FILE__, __LINE__)
+      end
+
+      # Override methods that take hashes to convert the hashes to using strings for keys and
+      # values before using them.
+      %w'initialize merge! update replace'.each do |m|
+        class_eval("def #{m}(h, &block) super(convert_hash(h), &block) end", __FILE__, __LINE__)
+      end
+
+      # Override to force the key argument to a string.
+      def fetch(key, *args, &block)
+        super(key.to_s, *args, &block)
+      end
+
+      # Convert the input hash to string keys and values before merging,
+      # and return a new HStore instance with the merged hash.
+      def merge(hash, &block)
+        self.class.new(super(convert_hash(hash), &block))
+      end
+
+      # Return the underlying hash used by this HStore instance.
+      alias to_hash __getobj__
+
+      # Append a literalize version of the hstore to the sql.
+      def sql_literal_append(ds, sql)
+        ds.literal_append(sql, unquoted_literal)
+        sql << HSTORE_CAST
+      end
+
+      # Return a string containing the unquoted, unstring-escaped
+      # literal version of the hstore.  Separated out for use by
+      # the bound argument code.
+      def unquoted_literal
+        str = ''
+        comma = false
+        commas = COMMA
+        quote = QUOTE
+        kv_sep = KV_SEP
+        null = NULL
+        each do |k, v|
+          str << commas if comma
+          str << quote << escape_value(k) << quote
+          str << kv_sep
+          if v.nil?
+            str << null
+          else
+            str << quote << escape_value(v) << quote
+          end
+          comma = true
+        end
+        str
+      end
+
+      private
+
+      # Return a new hash based on the input hash with string
+      # keys and string or nil values.
+      def convert_hash(h)
+        hash = Hash.new(&DEFAULT_PROC)
+        h.each{|k,v| hash[k.to_s] = convert_value(v)}
+        hash
+      end
+
+      # Return value v as a string unless it is already nil.
+      def convert_value(v)
+        v.to_s unless v.nil?
+      end
+
+      # Escape key/value strings when literalizing to
+      # correctly handle backslash and quote characters.
+      def escape_value(k)
+        k.to_s.gsub(ESCAPE_RE, ESCAPE_REPLACE)
+      end
+    end
+
+    PG_NAMED_TYPES = {} unless defined?(PG_NAMED_TYPES)
+    # Associate the named types by default.
+    PG_NAMED_TYPES[:hstore] = HStore.method(:parse)
+  end
+end
+
+class Hash
+  # Create a new HStore using the receiver as the input
+  # hash.  Note that the HStore created will not use the
+  # receiver as the backing store, since it has to
+  # modify the hash.  To get the new backing store, use:
+  #
+  #   hash.hstore.to_hash
+  def hstore
+    Sequel::Postgres::HStore.new(self)
+  end
+end