sequel 3.21.0 → 3.36.0

data/lib/sequel/extensions/pg_hstore_ops.rb

@@ -0,0 +1,259 @@
+# The pg_hstore_ops extension adds support to Sequel's DSL to make
+# it easier to call PostgreSQL hstore functions and operators. The
+# most common usage is taking an object that represents an SQL
+# expression (such as a :symbol), and calling #hstore on it:
+#
+#   h = :hstore_column.hstore
+#
+# This creates a Sequel::Postgres::HStoreOp object that can be used
+# for easier querying:
+#
+#   h - 'a'    # hstore_column - 'a'
+#   h['a']     # hstore_column -> 'a'
+#
+#   h.concat(:other_hstore_column)       # ||
+#   h.has_key?('a')                      # ?
+#   h.contain_all(:array_column)         # ?&
+#   h.contain_any(:array_column)         # ?|
+#   h.contains(:other_hstore_column)     # @> 
+#   h.contained_by(:other_hstore_column) # <@
+#
+#   h.defined        # defined(hstore_column)
+#   h.delete('a')    # delete(hstore_column, 'a')
+#   h.each           # each(hstore_column)
+#   h.keys           # akeys(hstore_column)
+#   h.populate(:a)   # populate_record(a, hstore_column)
+#   h.record_set(:a) # (a #= hstore_column)
+#   h.skeys          # skeys(hstore_column)
+#   h.slice(:a)      # slice(hstore_column, a)
+#   h.svals          # svals(hstore_column)
+#   h.to_array       # hstore_to_array(hstore_column)
+#   h.to_matrix      # hstore_to_matrix(hstore_column)
+#   h.values         # avals(hstore_column)
+#
+# See the PostgreSQL hstore function and operator documentation for more
+# details on what these functions and operators do.
+#
+# If you are also using the pg_hstore extension, you should load it before
+# loading this extension.  Doing so will allow you to use HStore#op to get
+# an HStoreOp, allowing you to perform hstore operations on hstore literals.
+
+module Sequel
+  module Postgres
+    # The HStoreOp class is a simple container for a single object that
+    # defines methods that yield Sequel expression objects representing
+    # PostgreSQL hstore operators and functions.
+    #
+    # In the method documentation examples, assume that:
+    #
+    #   hstore_op = :hstore.hstore
+    class HStoreOp < Sequel::SQL::Wrapper
+      CONCAT = ["(".freeze, " || ".freeze, ")".freeze].freeze
+      CONTAIN_ALL = ["(".freeze, " ?& ".freeze, ")".freeze].freeze
+      CONTAIN_ANY = ["(".freeze, " ?| ".freeze, ")".freeze].freeze
+      CONTAINS = ["(".freeze, " @> ".freeze, ")".freeze].freeze
+      CONTAINED_BY = ["(".freeze, " <@ ".freeze, ")".freeze].freeze
+      HAS_KEY = ["(".freeze, " ? ".freeze, ")".freeze].freeze
+      LOOKUP = ["(".freeze, " -> ".freeze, ")".freeze].freeze
+      RECORD_SET = ["(".freeze, " #= ".freeze, ")".freeze].freeze
+
+      # Delete entries from an hstore using the subtraction operator:
+      #
+      #   hstore_op - 'a' # (hstore - 'a')
+      def -(other)
+        HStoreOp.new(super)
+      end
+
+      # Lookup the value for the given key in an hstore:
+      #
+      #   hstore_op['a'] # (hstore -> 'a')
+      def [](key)
+        Sequel::SQL::StringExpression.new(:NOOP, Sequel::SQL::PlaceholderLiteralString.new(LOOKUP, [value, key]))
+      end
+
+      # Check if the receiver contains all of the keys in the given array:
+      #
+      #   hstore_op.contain_all(:a) # (hstore ?& a)
+      def contain_all(other)
+        bool_op(CONTAIN_ALL, other)
+      end
+
+      # Check if the receiver contains any of the keys in the given array:
+      #
+      #   hstore_op.contain_any(:a) # (hstore ?| a)
+      def contain_any(other)
+        bool_op(CONTAIN_ANY, other)
+      end
+
+      # Check if the receiver contains all entries in the other hstore:
+      #
+      #   hstore_op.contains(:h) # (hstore @> h)
+      def contains(other)
+        bool_op(CONTAINS, other)
+      end
+
+      # Check if the other hstore contains all entries in the receiver:
+      #
+      #   hstore_op.contained_by(:h) # (hstore <@ h)
+      def contained_by(other)
+        bool_op(CONTAINED_BY, other)
+      end
+
+      # Check if the receiver contains a non-NULL value for the given key:
+      #
+      #   hstore_op.defined('a') # defined(hstore, 'a')
+      def defined(key)
+        Sequel::SQL::BooleanExpression.new(:NOOP, function(:defined, key))
+      end
+
+      # Delete the matching entries from the receiver:
+      #
+      #   hstore_op.delete('a') # delete(hstore, 'a')
+      def delete(key)
+        HStoreOp.new(function(:delete, key))
+      end
+
+      # Transform the receiver into a set of keys and values:
+      #
+      #   hstore_op.each # each(hstore)
+      def each
+        function(:each)
+      end
+
+      # Check if the receiver contains the given key:
+      #
+      #   hstore_op.has_key?('a') # (hstore ? 'a')
+      def has_key?(key)
+        bool_op(HAS_KEY, key)
+      end
+      alias include? has_key?
+      alias key? has_key?
+      alias member? has_key?
+      alias exist? has_key?
+
+      # Return the receiver.
+      def hstore
+        self
+      end
+
+      # Return the keys as a PostgreSQL array:
+      #
+      #   hstore_op.keys # akeys(hstore)
+      def keys
+        function(:akeys)
+      end
+      alias akeys keys
+
+      # Merge a given hstore into the receiver:
+      #
+      #   hstore_op.merge(:a) # (hstore || a)
+      def merge(other)
+        HStoreOp.new(Sequel::SQL::PlaceholderLiteralString.new(CONCAT, [self, other]))
+      end
+      alias concat merge
+
+      # Create a new record populated with entries from the receiver:
+      #
+      #   hstore_op.populate(:a) # populate_record(a, hstore)
+      def populate(record)
+        SQL::Function.new(:populate_record, record, self)
+      end
+      
+      # Update the values in a record using entries in the receiver:
+      #
+      #   hstore_op.record_set(:a) # (a #= hstore)
+      def record_set(record)
+        Sequel::SQL::PlaceholderLiteralString.new(RECORD_SET, [record, value])
+      end
+
+      # Return the keys as a PostgreSQL set:
+      #
+      #   hstore_op.skeys # skeys(hstore)
+      def skeys
+        function(:skeys)
+      end
+
+      # Return an hstore with only the keys in the given array:
+      #
+      #   hstore_op.slice(:a) # slice(hstore, a)
+      def slice(keys)
+        HStoreOp.new(function(:slice, keys))
+      end
+
+      # Return the values as a PostgreSQL set:
+      #
+      #   hstore_op.svals # svals(hstore)
+      def svals
+        function(:svals)
+      end
+
+      # Return a flattened array of the receiver with alternating
+      # keys and values:
+      #
+      #   hstore_op.to_array # hstore_to_array(hstore)
+      def to_array
+        function(:hstore_to_array)
+      end
+
+      # Return a nested array of the receiver, with arrays of
+      # 2 element (key/value) arrays:
+      #
+      #   hstore_op.to_matrix # hstore_to_matrix(hstore)
+      def to_matrix
+        function(:hstore_to_matrix)
+      end
+
+      # Return the values as a PostgreSQL array:
+      #
+      #   hstore_op.values # avals(hstore)
+      def values
+        function(:avals)
+      end
+      alias avals values
+
+      private
+
+      # 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 HStoreOpMethods
+      # Wrap the receiver in an HStoreOp so you can easily use the PostgreSQL
+      # hstore functions and operators with it.
+      def hstore
+        HStoreOp.new(self)
+      end
+    end
+
+    if defined?(HStore)
+      class HStore
+        # Wrap the receiver in an HStoreOp so you can easily use the PostgreSQL
+        # hstore functions and operators with it.
+        def op
+          HStoreOp.new(self)
+        end
+      end
+    end
+  end
+
+  class SQL::GenericExpression
+    include Sequel::Postgres::HStoreOpMethods
+  end
+
+  class LiteralString
+    include Sequel::Postgres::HStoreOpMethods
+  end
+end
+
+class Symbol
+  include Sequel::Postgres::HStoreOpMethods
+end

data/lib/sequel/extensions/pg_inet.rb

@@ -0,0 +1,89 @@
+# The pg_inet extension adds support for Sequel to handle
+# PostgreSQL's inet and cidr types using ruby's IPAddr class.
+#
+# This extension integrates with Sequel's native postgres adapter, so
+# that when inet/cidr fields are retrieved, they are returned as
+# IPAddr instances
+#
+# After loading the extension, you should extend your dataset
+# with a module so that it correctly handles the inet/cidr type:
+#
+#   DB.extend Sequel::Postgres::InetDatabaseMethods
+#
+# 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 inet/cidr column(s) on load.
+#
+# This extension does not add special support for the macaddr
+# type.  Ruby doesn't have a stdlib class that represents mac
+# addresses, so these will still be returned as strings.
+
+require 'ipaddr'
+
+module Sequel
+  module Postgres
+    # Methods enabling Database object integration with the inet/cidr types.
+    module InetDatabaseMethods
+
+      # Reset the conversion procs when extending the Database object, so
+      # it will pick up the inet/cidr convertor.  Also, extend the datasets
+      # with support for literalizing the IPAddr types.
+      def self.extended(db)
+        db.reset_conversion_procs if db.respond_to?(:reset_conversion_procs)
+        db.extend_datasets(InetDatasetMethods)
+      end
+
+      # Convert an IPAddr arg to a string.  Probably not necessary, but done
+      # for safety.
+      def bound_variable_arg(arg, conn)
+        case arg
+        when IPAddr
+          "#{arg.to_s}/#{arg.instance_variable_get(:@mask_addr).to_s(2).count('1')}"
+        else
+          super
+        end
+      end
+
+      # Make the column type detection recognize the inet and cidr types.
+      def schema_column_type(db_type)
+        case db_type
+        when 'inet', 'cidr'
+          :ipaddr
+        else
+          super
+        end
+      end
+
+      private
+
+      # Typecast the given value to an IPAddr object.
+      def typecast_value_ipaddr(value)
+        case value
+        when IPAddr
+          value
+        when String
+          IPAddr.new(value)
+        else
+          raise Sequel::InvalidValue, "invalid value for inet/cidr: #{value.inspect}"
+        end
+      end
+    end
+
+    module InetDatasetMethods
+      private
+
+      # Convert IPAddr value to a string and append a literal version
+      # of the string to the sql.
+      def literal_other_append(sql, value)
+        if value.is_a?(IPAddr)
+          literal_string_append(sql, "#{value.to_s}/#{value.instance_variable_get(:@mask_addr).to_s(2).count('1')}")
+        else
+          super
+        end
+      end
+    end
+
+    PG_TYPES = {} unless defined?(PG_TYPES)
+    PG_TYPES[869] = PG_TYPES[650] = IPAddr.method(:new)
+  end
+end

data/lib/sequel/extensions/pg_json.rb

@@ -0,0 +1,178 @@
+# The pg_json extension adds support for Sequel to handle
+# PostgreSQL's json type.  It is slightly more strict than the
+# PostgreSQL json type in that the object returned must be an
+# array or object (PostgreSQL's json type considers plain numbers
+# and strings as valid).  This is because Sequel relies completely
+# on the ruby JSON library for parsing, and ruby's JSON library
+# does not accept the values.
+#
+# This extension integrates with Sequel's native postgres adapter, so
+# that when json fields are retrieved, they are parsed and returned
+# as instances of Sequel::Postgres::JSONArray or
+# Sequel::Postgres::JSONHash.  JSONArray and JSONHash are
+# DelegateClasses of Array and Hash, so they mostly act the same, but
+# not completely (json_array.is_a?(Array) is false).  If you want
+# the actual array for a JSONArray, call JSONArray#to_a.  If you want
+# the actual hash for a JSONHash, call JSONHash#to_hash.
+# This is done so that Sequel does not treat JSONArray and JSONHash
+# like Array and Hash by default, which would cause issues.
+#
+# To turn an existing Array or Hash into a JSONArray or JSONHash:
+#
+#   array.pg_json
+#   hash.pg_json
+#
+# So if you want to insert an array or hash into an json database column:
+#
+#   DB[:table].insert(:column=>[1, 2, 3].pg_json)
+#   DB[:table].insert(:column=>{'a'=>1, 'b'=>2}.pg_json)
+#
+# If you would like to use PostgreSQL json columns in your model
+# objects, you probably want to modify the schema parsing/typecasting
+# so that it recognizes and correctly handles the json type, which
+# you can do by:
+#
+#   DB.extend Sequel::Postgres::JSONDatabaseMethods
+#
+# 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 json column(s) on load.
+#
+# The extension is designed to be used with the json type natively
+# supported by PostgreSQL 9.2+.  There was also a PostgreSQL extension released
+# that allowed the json type to be used on PostgreSQL 9.1.  To make
+# this extension support that type in the native adapter, do the
+# following after loading this extension:
+#
+#   Sequel::Postgres::PG_NAMED_TYPES = {} unless defined?(Sequel::Postgres::PG_NAMED_TYPES)
+#   Sequel::Postgres::PG_NAMED_TYPES[:json] = Sequel::Postgres::PG_TYPES[114]
+#
+# This extension requires both the json and delegate libraries.
+
+require 'delegate'
+require 'json'
+
+module Sequel
+  module Postgres
+    CAST_JSON = '::json'.freeze
+
+    # Class representating PostgreSQL JSON column array values.
+    class JSONArray < DelegateClass(Array)
+      # Convert the array to a string using to_json, append a
+      # literalized version of the string to the sql, and explicitly
+      # cast the string to json.
+      def sql_literal_append(ds, sql)
+        ds.literal_append(sql, to_json)
+        sql << CAST_JSON
+      end
+    end
+
+    # Class representating PostgreSQL JSON column hash/object values.
+    class JSONHash < DelegateClass(Hash)
+      # Convert the array to a string using to_json, append a
+      # literalized version of the string to the sql, and explicitly
+      # cast the string to json.
+      def sql_literal_append(ds, sql)
+        ds.literal_append(sql, to_json)
+        sql << CAST_JSON
+      end
+
+      # Return the object being delegated to.
+      alias to_hash __getobj__
+    end
+
+    # Methods enabling Database object integration with the json type.
+    module JSONDatabaseMethods
+      # Parse the given string as json, returning either a JSONArray
+      # or JSONHash instance, and raising an error if the JSON
+      # parsing does not yield an array or hash.
+      def self.parse_json(s)
+        begin
+          value = JSON.parse(s)
+        rescue JSON::ParserError=>e
+          raise Sequel.convert_exception_class(e, Sequel::InvalidValue)
+        end
+
+        case value
+        when Array
+          JSONArray.new(value)
+        when Hash 
+          JSONHash.new(value)
+        else
+          raise Sequel::InvalidValue, "unhandled json value: #{value.inspect} (from #{s.inspect})"
+        end
+      end
+
+      # Reset the conversion procs when extending the Database object, so
+      # it will pick up the json convertor.  This is only done for the native
+      # postgres adapter.
+      def self.extended(db)
+        db.reset_conversion_procs if db.respond_to?(:reset_conversion_procs)
+      end
+
+      # Handle JSONArray and JSONHash in bound variables
+      def bound_variable_arg(arg, conn)
+        case arg
+        when JSONArray, JSONHash
+          arg.to_json
+        else
+          super
+        end
+      end
+
+      # Make the column type detection recognize the json type.
+      def schema_column_type(db_type)
+        case db_type
+        when 'json'
+          :json
+        else
+          super
+        end
+      end
+
+      private
+
+      # Given a value to typecast to the json column
+      # * If given a JSONArray or JSONHash, just return the value
+      # * If given an Array, return a JSONArray
+      # * If given a Hash, return a JSONHash
+      # * If given a String, parse it as would be done during
+      #   database retrieval.
+      def typecast_value_json(value)
+        case value
+        when JSONArray, JSONHash
+          value
+        when Array
+          JSONArray.new(value)
+        when Hash 
+          JSONHash.new(value)
+        when String
+          JSONDatabaseMethods.parse_json(value)
+        else
+          raise Sequel::InvalidValue, "invalid value for json: #{value.inspect}"
+        end
+      end
+    end
+
+    PG_TYPES = {} unless defined?(PG_TYPES)
+    PG_TYPES[114] = JSONDatabaseMethods.method(:parse_json)
+  end
+end
+
+class Array
+  # Return a Sequel::Postgres::JSONArray proxy to the receiver.
+  # This is mostly useful as a short cut for creating JSONArray
+  # objects that didn't come from the database.
+  def pg_json
+    Sequel::Postgres::JSONArray.new(self)
+  end
+end
+
+class Hash
+  # Return a Sequel::Postgres::JSONHash proxy to the receiver.
+  # This is mostly useful as a short cut for creating JSONHash
+  # objects that didn't come from the database.
+  def pg_json
+    Sequel::Postgres::JSONHash.new(self)
+  end
+end