sequel 5.100.0 → 5.102.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1e8ed38ad86fbbbd643eb1a2579b799025ff77400d250abe807f41e19a533d9e
-  data.tar.gz: 2a4e5b271a96b87d1b2e78f073c4d9a3e91d5147297e555a23c75ac0537b918d
+  metadata.gz: 92eed5c337b361dfde5b948323fb6a0a22ad89ecb2473c284d9e5b70a5eed8e2
+  data.tar.gz: dd07fefb9f3d2821479be092a12b87c6e7b92f5d8d8c314ff656741d31e75531
 SHA512:
-  metadata.gz: f1c4b4be8a1b1ce7537799d882e0cde6bd3967a414c8beb60c3ccfff08eb0ed2a84125bca68754510d4c6b80743a49c5c9ca784b1004b3d074e9674760c2e06c
-  data.tar.gz: 4e9386540fa22fd976b2ea915d0536225b0d5d231cd3d820e916c7dcc636bcda5a4fabda8604d3848aa183443d0c84d1f951b5ba0bef94cd79cf69526866c014
+  metadata.gz: ea53c48308a031896491a59e57ca3902a9a3478b8d09d12de6548a927991419054fa8698463c18c18cef9801a9c4629dc299b27df03245272bb2296f79ccdc1c
+  data.tar.gz: adfd92660e225f0d67948dfdc4aa57c2c61c1118265908f8b6a26fe23179573aff4195aec759575abea984e46fa5d1b62701b75caa8ce7e78838f6434e208527

data/lib/sequel/connection_pool/sharded_timed_queue.rb

@@ -71,7 +71,7 @@ class Sequel::ShardedTimedQueueConnectionPool < Sequel::ConnectionPool
       while true
         conn = nil
         begin
-          break unless (conn = queue.pop(timeout: 0)) && !conns[conn]
+          break unless (conn = available(queue, server)) && !conns[conn]
           conns[conn] = true
           yield conn
         ensure
@@ -95,7 +95,7 @@ class Sequel::ShardedTimedQueueConnectionPool < Sequel::ConnectionPool
   def disconnect(opts=OPTS)
     (opts[:server] ? Array(opts[:server]) : sync{@servers.keys}).each do |server|
       raise Sequel::Error, "invalid server" unless queue = sync{@queues[server]}
-      while conn = queue.pop(timeout: 0)
+      while conn = available(queue, server)
         disconnect_pool_connection(conn, server)
       end
       fill_queue(server)
@@ -167,7 +167,7 @@ class Sequel::ShardedTimedQueueConnectionPool < Sequel::ConnectionPool
 
         queue = @queues[server]
 
-        while conn = queue.pop(timeout: 0)
+        while conn = available(queue, server)
           @sizes[server] -= 1
           conns << conn
         end
@@ -225,6 +225,12 @@ class Sequel::ShardedTimedQueueConnectionPool < Sequel::ConnectionPool
     conns.each{|conn| disconnect_connection(conn)}
   end
 
+  # Only for use by extension that need to disconnect a connection inside acquire.
+  # Takes the connection and any arguments accepted by acquire.
+  def disconnect_acquired_connection(conn, _, server)
+    disconnect_pool_connection(conn, server)
+  end
+
   # Decrement the current size of the pool for the server when disconnecting connections.
   #
   # Calling code should not have the mutex when calling this.
@@ -311,7 +317,7 @@ class Sequel::ShardedTimedQueueConnectionPool < Sequel::ConnectionPool
   # Calling code should not have the mutex when calling this.
   def acquire(thread, server)
     queue = sync{@queues[server]}
-    if conn = queue.pop(timeout: 0) || try_make_new(server) || queue.pop(timeout: @timeout)
+    if conn = available(queue, server) || try_make_new(server) || wait_until_available(queue, server)
       sync{@allocated[server][thread] = conn}
     else
       name = db.opts[:name]
@@ -319,6 +325,19 @@ class Sequel::ShardedTimedQueueConnectionPool < Sequel::ConnectionPool
     end
   end
 
+  # Return the next connection in the pool if there is one available. Returns nil
+  # if no connection is currently available.
+  def available(queue, _server)
+    queue.pop(timeout: 0)
+  end
+
+  # Return the next connection in the pool if there is one available. If not, wait
+  # until the timeout for a connection to become available. If there is still no
+  # available connection, return nil.
+  def wait_until_available(queue, _server)
+    queue.pop(timeout: @timeout)
+  end
+
   # Returns the connection owned by the supplied thread for the given server,
   # if any. The calling code should NOT already have the mutex before calling this.
   def owned_connection(thread, server)

data/lib/sequel/connection_pool/timed_queue.rb

@@ -42,7 +42,7 @@ class Sequel::TimedQueueConnectionPool < Sequel::ConnectionPool
       while true
         conn = nil
         begin
-          break unless (conn = @queue.pop(timeout: 0)) && !conns[conn]
+          break unless (conn = available) && !conns[conn]
           conns[conn] = true
           yield conn
         ensure
@@ -59,7 +59,7 @@ class Sequel::TimedQueueConnectionPool < Sequel::ConnectionPool
   # Once a connection is requested using #hold, the connection pool
   # creates new connections to the database.
   def disconnect(opts=OPTS)
-    while conn = @queue.pop(timeout: 0)
+    while conn = available
       disconnect_connection(conn)
     end
     fill_queue
@@ -220,7 +220,7 @@ class Sequel::TimedQueueConnectionPool < Sequel::ConnectionPool
   #
   # Calling code should not have the mutex when calling this.
   def acquire(thread)
-    if conn = @queue.pop(timeout: 0) || try_make_new || @queue.pop(timeout: @timeout)
+    if conn = available || try_make_new || wait_until_available
       sync{@allocated[thread] = conn}
     else
       name = db.opts[:name]
@@ -228,6 +228,19 @@ class Sequel::TimedQueueConnectionPool < Sequel::ConnectionPool
     end
   end
 
+  # Return the next connection in the pool if there is one available. Returns nil
+  # if no connection is currently available.
+  def available
+    @queue.pop(timeout: 0)
+  end
+
+  # Return the next connection in the pool if there is one available. If not, wait
+  # until the timeout for a connection to become available. If there is still no
+  # available connection, return nil.
+  def wait_until_available
+    @queue.pop(timeout: @timeout)
+  end
+
   # Returns the connection owned by the supplied thread,
   # if any. The calling code should NOT already have the mutex before calling this.
   def owned_connection(thread)

data/lib/sequel/connection_pool.rb

@@ -131,6 +131,12 @@ class Sequel::ConnectionPool
     db.disconnect_connection(conn)
   end
 
+  # Only for use by extension that need to disconnect a connection inside acquire.
+  # Takes the connection and any arguments accepted by acquire.
+  def disconnect_acquired_connection(conn, *)
+    disconnect_connection(conn)
+  end
+
   # Whether the given exception is a disconnect exception.
   def disconnect_error?(exception)
     exception.is_a?(Sequel::DatabaseDisconnectError) || db.send(:disconnect_error?, exception, OPTS)

data/lib/sequel/dataset/actions.rb

@@ -372,6 +372,15 @@ module Sequel
     #   DB[:table].import([:x, :y], DB[:table2].select(:a, :b))
     #   # INSERT INTO table (x, y) SELECT a, b FROM table2 
     #
+    # The return value of this method is undefined and should not be used,
+    # except in two cases:
+    #
+    # * When the <tt>return: :primary_key</tt> option is used.
+    # * On PostgreSQL, when the dataset uses RETURNING. In this case, if
+    #   a single value is returned per row, the return value is an array
+    #   of those values. If multiple values are returned per row, the
+    #   return value is an array of hashes.
+    #
     # Options:
     # :commit_every :: Open a new transaction for every given number of
     #                  records. For example, if you provide a value of 50,

data/lib/sequel/extensions/connection_checkout_event_callback.rb

@@ -0,0 +1,151 @@
+# frozen-string-literal: true
+#
+# The connection_checkout_event_callback extension modifies a database's
+# connection pool to allow for a checkout event callback. This callback is
+# called with the following arguments:
+#
+# :immediately_available :: Connection immediately available and returned
+# :not_immediately_available :: Connection not immediately available
+# :new_connection :: New connection created and returned
+# Float :: Number of seconds waiting to acquire a connection
+#
+# This is a low-level extension that allows for building telemetry
+# information. It doesn't implement any telemetry reporting itself. The
+# main reason for recording this information is to use it to determine the
+# appropriate size for the connection pool. Having too large a connection
+# pool can waste resources, while having too small a connection pool can
+# result in substantial time to check out a connection. In general, you
+# want to use as small a pool as possible while keeping the time to
+# checkout a connection low.
+#
+# To use the connection checkout event callback, you must first load the
+# extension:
+#
+#   DB.extension(:connection_checkout_event_callback)
+#
+# By default, an empty proc is used as the callback so that loading the
+# support doesn't break anything. If you are using the extension, you
+# should set the callback at some point during application startup:
+#
+#   DB.pool.on_checkout_event = proc do |event|
+#     # ...
+#   end
+#
+# When using the sharded connection pool, the callback is also
+# passed a second argument, the requested server shard (generally a
+# symbol), allowing for collection of per-shard telemetry:
+#
+#   DB.pool.on_checkout_event = proc do |event, server|
+#     # ...
+#   end
+#
+# Note that the callback may be called currently by multiple threads.
+# You should use some form of concurrency control inside the callback,
+# such as a mutex or queue.
+#
+# Below is a brief example of usage to determine the percentage of
+# connection requests where a connection was immediately available:
+#
+#   mutex = Mutex.new
+#   total = immediates = 0
+#
+#   DB.pool.on_checkout_event = proc do |event|
+#     case event
+#     when :immediately_available
+#       mutex.synchronize do
+#         total += 1
+#         immediates += 1
+#       end
+#     when :not_immediately_available
+#       mutex.synchronize do
+#         total += 1
+#       end
+#     end
+#   end
+#
+#   immediate_percentage = lambda do
+#     mutex.synchronize do
+#       100.0 * immediates / total
+#     end
+#   end
+#   
+# Note that this extension only works with the timed_queue
+# and sharded_timed_queue connection pools (the default
+# connection pools when using Ruby 3.2+).
+#
+# Related modules: Sequel::ConnectionCheckoutEventCallbacks::TimedQueue,
+# Sequel::ConnectionCheckoutEventCallbacks::ShardedTimedQueue
+
+#
+module Sequel
+  module ConnectionCheckoutEventCallbacks
+    module TimedQueue
+      # The callback that is called with connection checkout events.
+      attr_accessor :on_checkout_event
+
+      private
+
+      def available
+        conn = super
+        @on_checkout_event.call(conn ? :immediately_available : :not_immediately_available)
+        conn
+      end
+
+      def try_make_new
+        conn = super
+        @on_checkout_event.call(:new_connection) if conn
+        conn
+      end
+
+      def wait_until_available
+        timer = Sequel.start_timer
+        conn = super
+        @on_checkout_event.call(Sequel.elapsed_seconds_since(timer))
+        conn
+      end
+    end
+
+    module ShardedTimedQueue
+      # The callback that is called with connection checkout events.
+      attr_accessor :on_checkout_event
+
+      private
+
+      def available(queue, server)
+        conn = super
+        @on_checkout_event.call(conn ? :immediately_available : :not_immediately_available, server)
+        conn
+      end
+
+      def try_make_new(server)
+        conn = super
+        @on_checkout_event.call(:new_connection, server) if conn
+        conn
+      end
+
+      def wait_until_available(queue, server)
+        timer = Sequel.start_timer
+        conn = super
+        @on_checkout_event.call(Sequel.elapsed_seconds_since(timer), server)
+        conn
+      end
+    end
+  end
+
+  default_callback = proc{}
+
+  Database.register_extension(:connection_checkout_event_callback) do |db|
+    pool = db.pool
+
+    case pool.pool_type
+    when :timed_queue
+      db.pool.extend(ConnectionCheckoutEventCallbacks::TimedQueue)
+    when :sharded_timed_queue
+      db.pool.extend(ConnectionCheckoutEventCallbacks::ShardedTimedQueue)
+    else
+      raise Error, "the connection_checkout_event_callback extension is only supported when using a timed_queue connection pool"
+    end
+
+    pool.on_checkout_event ||= default_callback
+  end
+end

data/lib/sequel/extensions/connection_expiration.rb

@@ -91,7 +91,7 @@ module Sequel
             sync{@allocated.delete(Sequel.current)}
           end
 
-          disconnect_connection(conn)
+          disconnect_acquired_connection(conn, *a)
           redo
         end
       end

data/lib/sequel/extensions/connection_validator.rb

@@ -118,7 +118,7 @@ module Sequel
                 sync{@allocated.delete(Sequel.current)}
               end
 
-              disconnect_connection(conn)
+              disconnect_acquired_connection(conn, *a)
               redo if valid == false
             end
           end

data/lib/sequel/plugins/detect_unnecessary_association_options.rb

@@ -0,0 +1,164 @@
+# frozen-string-literal: true
+
+module Sequel
+  module Plugins
+    # The detect_unnecessary_association_options plugin can detect unnecessary
+    # association options, and either warn or raise if they are detected.
+    # This allows you to find and remove the unnecessary options.
+    # Association options are considered unnecessary if they specify the same
+    # value as Sequel's defaults.
+    #
+    # To detect unnecessary association options, you should load the plugin
+    # into your model base class (e.g. Sequel::Model) before loading your model
+    # classes. Then, after all models have been loaded, you can call the
+    # detect_unnecessary_association_options on each to check for unnecessary
+    # association options. Additionally, if you are calling finalize_associations,
+    # it will automatically check for unnecessary association options.
+    #
+    # A typical usage would be to combine this with the subclasses plugin:
+    #
+    #   Sequel::Model.plugin :detect_unnecessary_association_options
+    #   Sequel::Model.plugin :subclasses
+    #   # load model classes
+    #
+    #   # implicitly check all subclasses when freezing descendants
+    #   Sequel::Model.freeze_descendants
+    #
+    #   # or, if not freezing all descendants
+    #   Sequel::Model.descendants.each(&:detect_unnecessary_association_options)
+    #
+    # By default, the plugin warns for every unnecessary association option.
+    # To raise an error instead, you can pass the <tt>action: :raise</tt> option when loading the
+    # plugin:
+    #
+    #   Sequel::Model.plugin :detect_unnecessary_association_options, action: :raise
+    #
+    # This plugin only detects the most common unnecessary association options, such as:
+    #
+    # * :class (all associations)
+    # * :key and :primary_key (associations without join tables)
+    # * :join_table, :left_key, :right_key, :left_primary_key, :right_primary_key (single join table associations)
+    # * :left_primary_key, :right_primary_key (*_through_many associations)
+    #
+    # Only association types supported by default or supported by a plugin that
+    # ships with Sequel are supported by this plugin. Other association types are
+    # ignored.
+    module DetectUnnecessaryAssociationOptions
+      def self.configure(model, opts={})
+        model.instance_variable_set(:@detect_unnecessary_association_options_action, opts[:action] || :warn)
+      end
+
+      # Raised if the plugin action is to raise and an unnecessary association option
+      # is detected.
+      class UnnecessaryAssociationOption < Sequel::Error
+      end
+
+      module ClassMethods
+        Plugins.inherited_instance_variables(self, :@detect_unnecessary_association_options_action => nil)
+
+        # Implicitly check for unnecessary association options when finalizing associations.
+        def finalize_associations
+          res = super
+          detect_unnecessary_association_options
+          res
+        end
+
+        # Check for unnecessary association options.
+        def detect_unnecessary_association_options
+          @association_reflections.each_value do |ref|
+            meth = "detect_unnecessary_association_options_#{ref[:type]}"
+            # Expected to call private methods.
+            # Ignore unrecognized association types.
+            # External association types can define the appropriate method to
+            # support their own unnecessary association option checks.
+            if respond_to?(meth, true)
+              # All recognized association types need same class check
+              _detect_unnecessary_association_options_class(ref)
+              send(meth, ref)
+            end
+          end
+
+          nil
+        end
+
+        private
+
+        # Action to take if an unnecessary association option is detected.
+        def unnecessary_association_options_detected(ref, key)
+          if @detect_unnecessary_association_options_action == :raise
+            raise UnnecessaryAssociationOption, "#{ref.inspect} :#{key} option unnecessary"
+          else
+            warn "#{ref.inspect} :#{key} option unnecessary"
+          end
+        end
+
+        # Detect unnecessary :class option.
+        def _detect_unnecessary_association_options_class(ref)
+          return unless ref[:orig_class]
+
+          h = {}
+          name = ref[:name]
+          late_binding_class_option(h, ref.returns_array? ? singularize(name) : name)
+
+          begin
+            default_association_class = constantize(h[:class_name])
+            actual_association_class = ref.associated_class
+          rescue NameError
+            # Do not warn. For the default association class to not be a valid
+            # constant is expected. For the actual association class to not be
+            # a valid constant is not expected and a bug in the association, but
+            # the job of this plugin is not to detect invalid options, only
+            # unnecessary options.
+          else
+            if default_association_class.equal?(actual_association_class)
+              unnecessary_association_options_detected(ref, "class")
+            end
+          end
+        end
+
+        # Detect other unnecessary options. An option is considered unnecessary
+        # if the key was submitted as an association option and the value for
+        # the option is the same as the given value.
+        def _detect_unnecessary_association_options_key_value(ref, key, value)
+          if ref[:orig_opts].has_key?(key) && ref[:orig_opts][key] == value
+            unnecessary_association_options_detected(ref, key)
+          end
+        end
+
+        # Same as _detect_unnecessary_association_options_key_value, but calls
+        # the default_* method on the association reflection to get the default value.
+        def _detect_unnecessary_association_options_key(ref, key)
+          _detect_unnecessary_association_options_key_value(ref, key, ref.send(:"default_#{key}"))
+        end
+
+        def detect_unnecessary_association_options_many_to_one(ref)
+          _detect_unnecessary_association_options_key(ref, :key)
+          _detect_unnecessary_association_options_key_value(ref, :primary_key, ref.associated_class.primary_key)
+        end
+        alias detect_unnecessary_association_options_pg_array_to_many detect_unnecessary_association_options_many_to_one
+
+        def detect_unnecessary_association_options_one_to_many(ref)
+          _detect_unnecessary_association_options_key(ref, :key)
+          _detect_unnecessary_association_options_key_value(ref, :primary_key, primary_key)
+        end
+        alias detect_unnecessary_association_options_one_to_one detect_unnecessary_association_options_one_to_many
+        alias detect_unnecessary_association_options_many_to_pg_array detect_unnecessary_association_options_one_to_many
+
+        def detect_unnecessary_association_options_many_to_many(ref)
+          [:join_table, :left_key, :right_key].each do |key|
+            _detect_unnecessary_association_options_key(ref, key)
+          end
+          _detect_unnecessary_association_options_key_value(ref, :left_primary_key, primary_key)
+          _detect_unnecessary_association_options_key_value(ref, :right_primary_key, ref.associated_class.primary_key)
+        end
+        alias detect_unnecessary_association_options_one_through_one detect_unnecessary_association_options_many_to_many
+
+        def detect_unnecessary_association_options_many_through_many(ref)
+          _detect_unnecessary_association_options_key_value(ref, :left_primary_key, primary_key)
+          _detect_unnecessary_association_options_key_value(ref, :right_primary_key, ref.associated_class.primary_key)
+        end
+        alias detect_unnecessary_association_options_one_through_many detect_unnecessary_association_options_many_through_many
+      end
+    end
+  end
+end

data/lib/sequel/version.rb

@@ -6,7 +6,7 @@ module Sequel
 
   # The minor version of Sequel.  Bumped for every non-patch level
   # release, generally around once a month.
-  MINOR = 100
+  MINOR = 102
 
   # The tiny version of Sequel.  Usually 0, only bumped for bugfix
   # releases that fix regressions from previous versions.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sequel
 version: !ruby/object:Gem::Version
-  version: 5.100.0
+  version: 5.102.0
 platform: ruby
 authors:
 - Jeremy Evans
@@ -212,6 +212,7 @@ files:
 - lib/sequel/extensions/blank.rb
 - lib/sequel/extensions/caller_logging.rb
 - lib/sequel/extensions/columns_introspection.rb
+- lib/sequel/extensions/connection_checkout_event_callback.rb
 - lib/sequel/extensions/connection_expiration.rb
 - lib/sequel/extensions/connection_validator.rb
 - lib/sequel/extensions/constant_sql_override.rb
@@ -344,6 +345,7 @@ files:
 - lib/sequel/plugins/defaults_setter.rb
 - lib/sequel/plugins/delay_add_association.rb
 - lib/sequel/plugins/deprecated_associations.rb
+- lib/sequel/plugins/detect_unnecessary_association_options.rb
 - lib/sequel/plugins/dirty.rb
 - lib/sequel/plugins/eager_each.rb
 - lib/sequel/plugins/eager_graph_eager.rb