sequel 5.101.0 → 5.102.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9de2d20e1483de5f15a285b695d5eab98601c26f1e711e378de1a03331f197a1
-  data.tar.gz: 4d7df1811d7242dad22f6c9968fb43feecb5a86fd814aa2ba7434bdb44369cb8
+  metadata.gz: 92eed5c337b361dfde5b948323fb6a0a22ad89ecb2473c284d9e5b70a5eed8e2
+  data.tar.gz: dd07fefb9f3d2821479be092a12b87c6e7b92f5d8d8c314ff656741d31e75531
 SHA512:
-  metadata.gz: a9aa7a3bd15f4f35457aace92b68b4734d367273996dc605d80adbe87bca1c945fc484571cad90149e69807980eea2f8b2a6a6fea85a4a0670c10a082a056a03
-  data.tar.gz: ca5c1eb34d71d16660a0b5eb2b9e5b4c784f06d6e4f89b036f00a62f31b57d564f071b8346bdcb9ebd9cced7bcfbe429e2c50bcda1b8b150d723b1e59105c474
+  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/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/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 = 101
+  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.101.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