pgtk 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7acb299c9e4e6cd1e272651041704fd89da2858bd1e4b2aa935eed9724815419
-  data.tar.gz: 1260a6fb42a11e34d1a733eb9d1bff8ba6a28f81724457e12986adccd134ebc5
+  metadata.gz: f4e1d913f72c6d33b8ecdb1cc17487c2ad7dfceae06f897b81cf0b4c12d32278
+  data.tar.gz: 456a7e3ae4a04891f3c51c0bc32108a30625782db57cca1725dbc4aec20b9363
 SHA512:
-  metadata.gz: 29aad3a51e77675418fc5eaffa72d7e0015d4e6d1464c87cc118f3ab94e223b0ce4461cffba91e7f4e2d22b594bb0a61f2d4b299db1055d2637d9afca5a0533d
-  data.tar.gz: 8483ec44d6da87cd0e57f57e2ca14373965269a5463bc74ba7e38ac4693b4acf35299a64b6ec91a17fc04812160ca31e6826313fce660cdd3e210c8cc3007c81
+  metadata.gz: 810a9b990e6e040683f02f58932ce480aa250331d1a73c6750e68f9ede1b069a0a63446ce3ecc3971bf07cb5695f2c25ce64d697fe33a4d1d5be18ed5d7b7ae5
+  data.tar.gz: c2ac270f074f32bab3ce1dc03b7a68b9c5ae17eeccc764d07e379813a665d57b968f6f2de672b9640db31d56e716a7212813e95d6968d8988ff4fd25e375d898

data/Gemfile.lock

@@ -36,8 +36,8 @@ GEM
       tago (~> 0.1)
     ellipsized (0.3.0)
     joined (0.4.0)
-    json (2.20.0)
-    language_server-protocol (3.17.0.5)
+    json (2.21.1)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     loog (0.8.0)
@@ -71,7 +71,7 @@ GEM
       racc (~> 1.4)
     os (1.1.4)
     parallel (2.1.0)
-    parser (3.3.11.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     pg (1.6.3)
@@ -95,7 +95,7 @@ GEM
       tago (~> 0.0)
     regexp_parser (2.12.0)
     rexml (3.4.4)
-    rubocop (1.88.1)
+    rubocop (1.88.2)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -106,13 +106,13 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
-    rubocop-elegant (0.7.0)
+    rubocop-elegant (0.7.1)
       lint_roller (~> 1.1)
       rubocop (~> 1.75)
-    rubocop-minitest (0.39.1)
+    rubocop-minitest (0.40.0)
       lint_roller (~> 1.1)
       rubocop (>= 1.75.0, < 2.0)
       rubocop-ast (>= 1.38.0, < 2.0)
@@ -148,7 +148,7 @@ GEM
       nokogiri (~> 1.8)
       rainbow (~> 3.0)
       slop (~> 4.4)
-    yard (0.9.44)
+    yard (0.9.45)
 
 PLATFORMS
   aarch64-linux

data/README.md

@@ -217,14 +217,26 @@ end
 ## Query Timeouts with `Pgtk::Impatient`
 
 To prevent queries from running indefinitely, use `Pgtk::Impatient` to enforce
-timeouts on database operations:
+timeouts on database operations.
+The limit itself belongs to the connection: the wire puts `statement_timeout`
+into the startup packet, and the decorator explains what happened when
+PostgreSQL applies it:
 
 ```ruby
 require 'pgtk/impatient'
-# Wrap the pool with a 5-second timeout for all queries
+# Every connection of the pool carries a 5-second limit
+pool = Pgtk::Pool.new(
+  Pgtk::Wire::Env.new('DATABASE_URL', options: '-c statement_timeout=5000'),
+  max: 4
+)
+pool.start!
+# Wrap the pool, telling it about the very same 5 seconds
 impatient = Pgtk::Impatient.new(pool, 5)
 ```
 
+Both numbers must agree, since the connection stops the query, while the
+decorator only reports it.
+
 The impatient decorator ensures queries don't hang your application:
 
 ```ruby
@@ -243,31 +255,32 @@ You can exclude specific queries from timeout enforcement using regex patterns:
 impatient = Pgtk::Impatient.new(pool, 2, /^SELECT/, /^VACUUM/)
 ```
 
-Excluded queries are never wrapped in a transaction, because statements such as
-`VACUUM`, `REINDEX`, or `CREATE INDEX CONCURRENTLY` cannot run inside a
-transaction block. Instead, a longer fallback timeout (300 seconds by default,
-configurable via the `default:` argument) is applied at the session level with
-`SET statement_timeout` before the query runs, and reset afterwards. Pass
-`default: 0` to run excluded queries with no timeout at all:
+Excluded queries get a longer fallback timeout (300 seconds by default,
+configurable via the `default:` argument), applied at the session level with
+`SET statement_timeout` before the query runs and reset afterwards. This is how
+statements that legitimately need much longer than a query, such as `VACUUM`,
+`REINDEX`, or `CREATE INDEX CONCURRENTLY`, stay possible. Pass `default: 0` to
+run excluded queries with no timeout at all:
 
 ```ruby
 # Give excluded queries a 60-second fallback timeout
 impatient = Pgtk::Impatient.new(pool, 2, /^VACUUM/, default: 60)
 ```
 
-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.
+The limit travels in the startup packet and nowhere else. An in-band
+`SET LOCAL statement_timeout` arrives behind a `START TRANSACTION`, and both of
+them run with no limit in force, which is exactly the hang that `Impatient`
+exists to prevent. A setting from the startup packet is in force from the first
+byte of the first statement, survives a transaction-pooling PgBouncer, and
+frees the server-side connection slot even when the client cannot deliver a
+cancellation request.
 
 Key features:
 
 1. Configurable timeout in seconds for each query
 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,
+1. Sends each query in a single round trip, with the limit already in force,
    so timeouts are enforced server-side and orphan backends do not pile up
 
 ## Query Caching with `Pgtk::Stash`

data/lib/pgtk/impatient/too_slow.rb

@@ -8,9 +8,9 @@ require_relative '../../pgtk'
 class Pgtk::Impatient; end
 
 # Raised by Pgtk::Impatient#exec when the query takes longer than the
-# configured timeout. The deadline is enforced server-side via
-# +SET LOCAL statement_timeout+, so the underlying +PG::QueryCanceled+
-# is translated into this error for the caller.
+# configured timeout. The deadline is enforced server-side, by the
+# +statement_timeout+ of the connection, so the underlying
+# +PG::QueryCanceled+ is translated into this error for the caller.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2026 Yegor Bugayenko

data/lib/pgtk/impatient.rb

@@ -12,26 +12,30 @@ require_relative '../pgtk'
 # 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 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.
+# This class implements the same interface as Pool. The timeout itself is
+# enforced by PostgreSQL, through the +statement_timeout+ that the wire puts
+# into the startup packet of every connection. The limit is in force from the
+# first byte of the first statement, which no in-band +SET+ can achieve: the
+# +SET+ itself, and the +START TRANSACTION+ ahead of it, would travel with no
+# limit at all. Because the setting arrives in the startup packet, it also
+# survives a transaction-pooling PgBouncer, and it frees the server-side
+# connection slot even when the client cannot deliver a cancellation request.
+# When PostgreSQL terminates a query at the deadline, +TooSlow+ is raised here.
 #
 # Queries that match one of the +off+ regular expressions are excluded from
-# this checking. They are never wrapped in a transaction, because some
-# statements (such as +VACUUM+, +REINDEX+, or +CREATE INDEX CONCURRENTLY+)
-# cannot run inside a transaction block. Instead, a session-level
-# +SET statement_timeout+ is applied on the same connection before the query
-# runs (and reset afterwards), using the +default+ fallback timeout. Pass
-# +default: 0+ to run excluded queries with no timeout at all.
+# this checking. They run on a single connection, guarded by a session-level
+# +SET statement_timeout+ with the +default+ fallback timeout, which is reset
+# afterwards. Pass +default: 0+ to run excluded queries with no timeout at all.
+# This is how statements that take much longer than a query, such as +VACUUM+
+# or +REINDEX+, stay possible.
 #
 # Basic usage:
 #
-#   # Create and configure a regular pool
-#   pool = Pgtk::Pool.new(wire, max: 4)
+#   # Create a pool of connections that carry a two-second limit
+#   pool = Pgtk::Pool.new(
+#     Pgtk::Wire::Env.new('DATABASE_URL', options: '-c statement_timeout=2000'),
+#     max: 4
+#   )
 #   pool.start!
 #
 #   # Wrap the pool in an impatient decorator with a 2-second timeout
@@ -69,7 +73,8 @@ class Pgtk::Impatient
   # Constructor.
   #
   # @param [Pgtk::Pool] pool The pool to decorate
-  # @param [Integer] timeout Timeout in seconds for each SQL query
+  # @param [Integer] timeout Timeout in seconds for each SQL query, the same
+  #   one that the connections of the pool carry as +statement_timeout+
   # @param [Array<Regex>] off List of regex to exclude queries from checking
   # @param [Integer] default Fallback timeout in seconds for excluded queries (0 = no timeout)
   def initialize(pool, timeout, *off, default: 300)
@@ -103,18 +108,14 @@ class Pgtk::Impatient
 
   # 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+.
+  # The query travels alone, in a single round trip, and the limit is the
+  # +statement_timeout+ that the connection already carries. When the deadline
+  # fires, the underlying +PG::QueryCanceled+ is translated to +TooSlow+.
   #
-  # Queries matching one of the +off+ regular expressions bypass this
-  # transaction. They run on a single connection without a transaction block,
-  # guarded by a session-level +SET statement_timeout+ (the +default+ fallback,
-  # reset afterwards) or by no timeout at all when +default+ is zero. This keeps
-  # statements that cannot run inside a transaction, such as +VACUUM+ or
+  # Queries matching one of the +off+ regular expressions are guarded instead
+  # by a session-level +SET statement_timeout+ (the +default+ fallback, reset
+  # afterwards), or by no timeout at all when +default+ is zero. This keeps
+  # statements that need much longer than a query, such as +VACUUM+ or
   # +REINDEX+, working as expected.
   #
   # @param [String, Array] query The SQL query with params inside (possibly)
@@ -124,20 +125,14 @@ class Pgtk::Impatient
   def exec(query, *args)
     sql = query.is_a?(Array) ? query.join(' ') : query
     if @off.any? { |re| re.match?(sql) }
-      ms = Integer(@default * 1000)
-      return @pool.exec(sql, *args) if ms.zero?
       return @pool.session do |t|
-        t.exec("SET statement_timeout = #{ms}")
+        t.exec("SET statement_timeout = #{Integer(@default * 1000)}")
         t.exec(sql, *args).tap { t.exec('RESET statement_timeout') }
       end
     end
     start = Time.now
-    ms = [Integer(@timeout * 1000), 1].max
     begin
-      @pool.transaction do |t|
-        t.exec("SET LOCAL statement_timeout = #{ms}")
-        t.exec(sql, *args)
-      end
+      @pool.exec(sql, *args)
     rescue PG::QueryCanceled
       raise(
         TooSlow, [

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.33.0' unless defined?(VERSION)
+  VERSION = '0.34.0' unless defined?(VERSION)
 end

data/resources/pom.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
- * SPDX-License-Identifier: MIT
+* SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
+* SPDX-License-Identifier: MIT
 -->
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
   <modelVersion>4.0.0</modelVersion>
@@ -10,7 +10,7 @@
   <version>0.0.0</version>
   <packaging>pom</packaging>
   <properties>
-    <postgresql.version>42.7.12</postgresql.version>
+    <postgresql.version>42.7.13</postgresql.version>
     <liquibase.version>5.0.3</liquibase.version>
   </properties>
   <dependencies>

data/test-resources/2019/01-test.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
- * SPDX-License-Identifier: MIT
+* SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
+* SPDX-License-Identifier: MIT
 -->
 <databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-2.0.xsd" logicalFilePath="001-initial-schema.xml">
   <changeSet id="01" author="yegor256">

data/test-resources/master.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!--
- * SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
- * SPDX-License-Identifier: MIT
+* SPDX-FileCopyrightText: Copyright (c) 2019-2026 Yegor Bugayenko
+* SPDX-License-Identifier: MIT
 -->
 <databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-2.0.xsd">
   <includeAll path="2019"/>

metadata

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