pgtk 0.31.7 → 0.31.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9620e5581d667750f82a36568c6b64fcb27c2c588b93fc433869f1a430159128
-  data.tar.gz: 281908df6408d31c7ae69ff9ea4a4122881b7ae54c7906e87d10abf885d625d4
+  metadata.gz: 52f06b5f116d87eb7229752520f8cfff19e5c97d53c94a5acac935ad5f5d74e7
+  data.tar.gz: 83f18d647dbcd7ab1e503ac14da13d3abf77353f70acc2937090b237bcf28af7
 SHA512:
-  metadata.gz: f633a5925cbf6f8ad61247c898a7d58a59d8a64dcf7e23597f625ddfad816e856ae00b6b4960839abec9d763b931a4c519bce49c3bd2724fef38854e7c316c7e
-  data.tar.gz: a70e63d0772e40632333d382d4c8598a6a1ab60d72b3ce7bc8675ed12aced75acdc6117fbfccfc6fd9094e927136f7b9f983ba99491b673a392fd7fdb645597a
+  metadata.gz: 4f70d7c3755cee075cd586b4ed3830cc2c932bc4a0213e36fe18104e9b4c4c6ac74fcb00e985aeda37766c62b399ffd829a537f59582be7cb2be31a7eacfaac6
+  data.tar.gz: 9cf6517ef4f27aaf6403fd3dbc522b11c69853a7ccc704f009126f29d7b1aedbcf852522f3d90ff242b3bf482f51634f33c9c2373a88c880e8281b20a731403e

data/Gemfile.lock

@@ -42,7 +42,7 @@ GEM
     loog (0.8.0)
       ellipsized
       logger (~> 1.0)
-    minitest (6.0.5)
+    minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
     minitest-mock (5.27.0)

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,9 +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 without delay
-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. Retries happen immediately, except on `PG::ConnectionBad`,
+   where an exponential backoff (50ms, 200ms, 1s) is applied
+   between attempts to avoid amplifying upstream login storms
+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/liquicheck_task.rb

@@ -7,7 +7,7 @@ require 'nokogiri'
 require 'rake/tasklib'
 require_relative '../pgtk'
 
-# Liquicheck rake task for check Liquibase XML files.
+# Liquicheck rake task to check Liquibase XML files.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko
 # License:: MIT
@@ -63,7 +63,7 @@ class Pgtk::LiquicheckTask < Rake::TaskLib
     context = node.attr('context')&.to_s
     on(errors, file) do
       demand(id, 'ID is empty')
-      confirm(id, /[-a-z]+/, "ID #{id.inspect} has not suffix in #{context} context") if context
+      confirm(id, /[-a-z]+/, "ID #{id.inspect} has no suffix in #{context} context") if context
     end
     on(errors, file) do
       demand(author, 'author is empty')

data/lib/pgtk/pool.rb

@@ -114,7 +114,7 @@ class Pgtk::Pool
   #    puts 'Title: ' + row['title']
   #  end
   #
-  # All values in the retrieved hash are strings. No matter what types of
+  # All values in the retrieved hash are strings. No matter what types
   # of data you have in the database, you get strings here. It's your job
   # to convert them to the type you need.
   #
@@ -322,6 +322,7 @@ class Pgtk::Pool
           conn = renew(conn, reason)
         rescue StandardError => e
           @log.warn("Failed to renew dead connection (#{reason}): #{e.message}")
+          raise(e)
         end
       end
       begin

data/lib/pgtk/retry.rb

@@ -54,6 +54,8 @@ class Pgtk::Retry
   # so its message and stack trace are preserved for debugging.
   class Exhausted < StandardError; end
 
+  BACKOFFS = [0.05, 0.2, 1.0].freeze
+
   # Constructor.
   #
   # @param [Pgtk::Pool] pool The pool to decorate
@@ -86,13 +88,15 @@ class Pgtk::Retry
   end
 
   # Execute a SQL query with automatic retry on transient failures.
-  # SELECT queries are retried on any error, since reads are idempotent.
-  # Non-SELECT queries are retried only on PG::ConnectionBad, since by
-  # definition the query never reached the server, so retrying cannot
-  # duplicate a write. Other errors on writes propagate immediately,
-  # because a failure may occur after the server received the query but
-  # before the acknowledgement reached the client, and retrying a
-  # non-idempotent write could duplicate it.
+  # Only SELECT queries are retried, since reads are idempotent.
+  # Non-SELECT queries propagate the original error immediately, even
+  # on PG::ConnectionBad, because that error can be raised after the
+  # server already received the query but before the acknowledgement
+  # reached the client, and retrying a non-idempotent write could
+  # duplicate it. When the underlying error is PG::ConnectionBad, an
+  # exponential backoff (see BACKOFFS) is applied between attempts, so
+  # that a SELECT failing against an upstream pool that is in its
+  # login-failure cache window does not amplify the storm.
   #
   # @param [String] sql The SQL query with params inside (possibly)
   # @return [Array] Result rows
@@ -101,14 +105,11 @@ class Pgtk::Retry
     attempt = 0
     begin
       @pool.exec(sql, *)
-    rescue PG::ConnectionBad => e
-      attempt += 1
-      raise(Exhausted, "Retry gave up after #{@attempts} attempts: #{e.message}") if attempt >= @attempts
-      retry
     rescue StandardError, Pgtk::Impatient::TooSlow => e
       raise(e) unless query.strip.upcase.start_with?('SELECT')
       attempt += 1
       raise(Exhausted, "Retry gave up after #{@attempts} attempts: #{e.message}") if attempt >= @attempts
+      sleep(BACKOFFS[attempt - 1] || BACKOFFS.last) if e.is_a?(PG::ConnectionBad)
       retry
     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.7' unless defined?(VERSION)
+  VERSION = '0.31.9' unless defined?(VERSION)
 end

data/resources/pom.xml

@@ -10,7 +10,7 @@
   <version>0.0.0</version>
   <packaging>pom</packaging>
   <properties>
-    <postgresql.version>42.7.10</postgresql.version>
+    <postgresql.version>42.7.11</postgresql.version>
     <liquibase.version>5.0.2</liquibase.version>
   </properties>
   <dependencies>

metadata

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