pgtk 0.31.8 → 0.31.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10ac49e5f5fa5ac3792edf7e62961f8d37f8937a645a878de4e15b3ced01e575
-  data.tar.gz: 51b1c1927f57ea50b181cda95dc6f0471237c4873a7e99482b35f980fd8294dd
+  metadata.gz: 52f06b5f116d87eb7229752520f8cfff19e5c97d53c94a5acac935ad5f5d74e7
+  data.tar.gz: 83f18d647dbcd7ab1e503ac14da13d3abf77353f70acc2937090b237bcf28af7
 SHA512:
-  metadata.gz: 9d1f4a4d1247426d01caea364c9082e6dc9b81eb7428fb2da3f11764d9542ad7c99b35b1f0a1ed25c033e203d9ef253b48b061ce29eee07ca2048f9f82aa8f50
-  data.tar.gz: f713deaf5f0b8c2ba45a0d6fd8d6c46fb88f8ba153b1f1096aa69c351655cd7ce1daefb7d6e0e730609eb96b713c90ad5b3a50ccb08914a10ee4011b4ba3ef2b
+  metadata.gz: 4f70d7c3755cee075cd586b4ed3830cc2c932bc4a0213e36fe18104e9b4c4c6ac74fcb00e985aeda37766c62b399ffd829a537f59582be7cb2be31a7eacfaac6
+  data.tar.gz: 9cf6517ef4f27aaf6403fd3dbc522b11c69853a7ccc704f009126f29d7b1aedbcf852522f3d90ff242b3bf482f51634f33c9c2373a88c880e8281b20a731403e

data/README.md

@@ -202,12 +202,20 @@ You can exclude specific queries from timeout enforcement using regex patterns:
 impatient = Pgtk::Impatient.new(pool, 2, /^SELECT/, /^VACUUM/)
 ```
 
+The timeout is enforced on the server side: each query is wrapped in a tiny
+transaction that issues `SET LOCAL statement_timeout`, and PostgreSQL itself
+terminates the query at the deadline. This guarantees the server-side
+connection slot is freed even when the client cannot deliver a cancellation
+request — for example, behind a transaction-pool PgBouncer that does not
+forward client disconnects to in-flight server queries.
+
 Key features:
 
 1. Configurable timeout in seconds for each query
-2. Raises `Pgtk::Impatient::TooSlow` exception when timeout is exceeded
-3. Can exclude queries matching specific patterns from timeout checks
-4. Also sets PostgreSQL's `statement_timeout` for transactions
+1. Raises `Pgtk::Impatient::TooSlow` exception when timeout is exceeded
+1. Can exclude queries matching specific patterns from timeout checks
+1. Sets PostgreSQL's `statement_timeout` per query and per transaction,
+   so timeouts are enforced server-side and orphan backends do not pile up
 
 ## Query Caching with `Pgtk::Stash`
 
@@ -253,9 +261,9 @@ Note that the caching implementation is basic and only suitable
 for simple queries:
 
 1. Queries must reference tables (using `FROM` or `JOIN`)
-2. Cache is invalidated by table, not by specific rows
-3. Write operations (`INSERT`, `UPDATE`, `DELETE`) bypass
-the cache and invalidate all cached queries for affected tables
+1. Cache is invalidated by table, not by specific rows
+1. Write operations (`INSERT`, `UPDATE`, `DELETE`) bypass
+   the cache and invalidate all cached queries for affected tables
 
 ## Automatic Retries with `Pgtk::Retry`
 
@@ -284,11 +292,11 @@ retry_pool.exec('INSERT INTO logs (message) VALUES ($1)', ['User logged in'])
 Key features:
 
 1. Only `SELECT` queries are retried (to prevent duplicate data modifications)
-2. Retries happen immediately, except on `PG::ConnectionBad`,
+1. Retries happen immediately, except on `PG::ConnectionBad`,
    where an exponential backoff (50ms, 200ms, 1s) is applied
    between attempts to avoid amplifying upstream login storms
-3. The original error is raised after all retry attempts are exhausted
-4. Works seamlessly with other decorators like `Pgtk::Spy` and `Pgtk::Impatient`
+1. The original error is raised after all retry attempts are exhausted
+1. Works seamlessly with other decorators like `Pgtk::Spy` and `Pgtk::Impatient`
 
 ## Some Examples
 

data/lib/pgtk/impatient.rb

@@ -4,18 +4,21 @@
 # SPDX-License-Identifier: MIT
 
 require 'ellipsized'
-require 'securerandom'
+require 'pg'
 require 'tago'
-require 'timeout'
 require_relative '../pgtk'
 
 # Impatient is a decorator for Pool that enforces timeouts on all database operations.
 # It ensures that SQL queries don't run indefinitely, which helps prevent application
 # hangs and resource exhaustion when database operations are slow or stalled.
 #
-# This class implements the same interface as Pool but wraps each database operation
-# in a timeout block. If a query exceeds the specified timeout, it raises a Timeout::Error
-# exception, allowing the application to handle slow queries gracefully.
+# This class implements the same interface as Pool but enforces the timeout on the
+# server side, by wrapping each query in a tiny transaction that issues
+# +SET LOCAL statement_timeout+. PostgreSQL itself terminates the query at the
+# deadline, which guarantees that the server-side connection slot is freed even
+# when the client cannot deliver a cancellation request (for example, behind a
+# transaction-pool PgBouncer that does not forward client disconnects to in-flight
+# server queries). On timeout, +TooSlow+ is raised.
 #
 # Basic usage:
 #
@@ -29,7 +32,7 @@ require_relative '../pgtk'
 #   # Execute queries with automatic timeout enforcement
 #   begin
 #     impatient.exec('SELECT * FROM large_table WHERE complex_condition')
-#   rescue Timeout::Error
+#   rescue Pgtk::Impatient::TooSlow
 #     puts "Query timed out after 2 seconds"
 #   end
 #
@@ -39,7 +42,7 @@ require_relative '../pgtk'
 #       t.exec('UPDATE large_table SET processed = true')
 #       t.exec('DELETE FROM queue WHERE processed = true')
 #     end
-#   rescue Timeout::Error
+#   rescue PG::QueryCanceled
 #     puts "Transaction timed out"
 #   end
 #
@@ -91,23 +94,30 @@ class Pgtk::Impatient
     ].join("\n")
   end
 
-  # Execute a SQL query with a timeout.
+  # Execute a SQL query with a server-side timeout.
+  #
+  # The query is wrapped in a tiny transaction that issues
+  # +SET LOCAL statement_timeout+, so PostgreSQL itself terminates the query
+  # at the deadline. This guarantees the server-side connection slot is freed
+  # even when the client cannot deliver a cancellation request (for example,
+  # behind a transaction-pool PgBouncer). When the deadline fires, the
+  # underlying +PG::QueryCanceled+ is translated to +TooSlow+.
   #
   # @param [String, Array] query The SQL query with params inside (possibly)
   # @param [Array] args List of arguments
   # @return [Array] Result rows
-  # @raise [Timeout::Error] If the query takes too long
+  # @raise [TooSlow] If the query takes too long
   def exec(query, *args)
     sql = query.is_a?(Array) ? query.join(' ') : query
     return @pool.exec(sql, *args) if @off.any? { |re| re.match?(sql) }
     start = Time.now
-    token = SecureRandom.uuid
+    ms = [Integer(@timeout * 1000), 1].max
     begin
-      Timeout.timeout(@timeout, Timeout::Error, token) do
-        @pool.exec(sql, *args)
+      @pool.transaction do |t|
+        t.exec("SET LOCAL statement_timeout = #{ms}")
+        t.exec(sql, *args)
       end
-    rescue Timeout::Error => e
-      raise(e) unless e.message == token
+    rescue PG::QueryCanceled
       raise(TooSlow, [
         'SQL query',
         ("with #{args.count} argument#{'s' if args.count > 1}" unless args.empty?),
@@ -125,14 +135,14 @@ class Pgtk::Impatient
   # terminates the session, which frees locks and releases the connection
   # slot back to the pool.
   #
-  # @yield [Pgtk::Impatient] Yields an impatient transaction
+  # @yield [Object] Yields a transaction object that responds to +exec+
   # @return [Object] Result of the block
   def transaction
     @pool.transaction do |t|
-      ms = Integer((@timeout * 1000).to_s, 10)
+      ms = [Integer(@timeout * 1000), 1].max
       t.exec("SET LOCAL statement_timeout = #{ms}")
       t.exec("SET LOCAL idle_in_transaction_session_timeout = #{ms}")
-      yield(Pgtk::Impatient.new(t, @timeout))
+      yield(t)
     end
   end
 end

data/lib/pgtk/version.rb

@@ -10,5 +10,5 @@ require_relative '../pgtk'
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
 # License:: MIT
 module Pgtk
-  VERSION = '0.31.8' unless defined?(VERSION)
+  VERSION = '0.31.9' unless defined?(VERSION)
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgtk
 version: !ruby/object:Gem::Version
-  version: 0.31.8
+  version: 0.31.9
 platform: ruby
 authors:
 - Yegor Bugayenko