pgmq-ruby 0.7.0 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee008476f444de984ef7413b21bee87043d9e5e87a7eabf85a934cf74b147225
-  data.tar.gz: 1dd10b9b77c9dc4109f6a8e779c970fc6f7ee2e4880cecb467ab3060ecc4f571
+  metadata.gz: 570ab8b29056f8831e828d18b114f49cf708b9350a7a0b6fd20645d73d3cd6c2
+  data.tar.gz: 246a625f56ca744cada699f99b631651d814232cafdf9fca6bf4b0c70d1e2b37
 SHA512:
-  metadata.gz: 32cc154c5df5d6501de5bf93daf32857448645b9fe5071bec84b51dbda86cf0efd1fe6cddfd24707fda8201e7d6b8fb10c02f3c7e2bf108226b50a4cbe1b65fd
-  data.tar.gz: ad2630d6736bc49490ccb2eec83da4878dd4b349e9e06cd12f5d9f62a10109922a379c0dab43aa5a0c8a3f33241ca71f6c6ba24386cc6a7cf097db1397ef2518
+  metadata.gz: f88edaa90fde3e5bfc585f3e22702c1a0545d0b807d7ae8807dc39bd4ea3dd1f0857a55885b6d3122332fe5a8a06a7e0d282a65524aee6e89e8f04882e0b0792
+  data.tar.gz: 06a01af44cfa4dd807ec23eaff5985c4fd72a3c2363f9b6706c89a8b6bf2e6c348cb71a176e23f7010ba7643210f8c461dc541865ede37b82888fa67e057ff04

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.7.2 (2026-08-31)
+
+### Dependencies
+- **[Change]** Loosen the `connection_pool` runtime dependency from `~> 2.4` to `>= 2.4, < 4` so applications can
+  upgrade to `connection_pool` 3.x. The gem only uses `ConnectionPool.new(size:, timeout:)`, `#with`, `#shutdown`,
+  `#reload`, `#available` and the `TimeoutError` / `PoolShuttingDownError` classes, all of which are unchanged in 3.x
+  (the 3.0 breaking change was positional-to-keyword arguments on `#checkout` / `#reap`, which are not used here).
+  The lockfile now resolves to 3.0.2 so CI exercises the new major.
+
+## 0.7.1 (2026-07-09)
+
+### Connection Pool
+- **[Feature]** Add `PGMQ::Connection#reload` (and `PGMQ::Client#reload`, which delegates to it). It drops every
+  connection currently in the pool and lets the pool rebuild fresh ones lazily on the next checkout — unlike `#close`,
+  which shuts the pool down permanently. Use it to recover from a connection that libpq still reports as
+  `CONNECTION_OK` but is in fact wedged, e.g. after a wall-clock `Timeout.timeout` interrupted a query mid-flight and
+  left the socket poisoned so it re-hangs on reuse. `#verify_connection!` cannot catch that case (the connection does
+  not report `CONNECTION_BAD`), so the caller must discard it explicitly; `reload` is the safe, pool-wide way to do so.
+  Connections it drops are closed. Implemented via `ConnectionPool#reload`.
+
 ## 0.7.0 (2026-06-15)
 
 ### Queue Naming

data/lib/pgmq/client/consumer.rb

@@ -235,8 +235,6 @@ module PGMQ
       # next), `read_grouped_head` surfaces the leading edge of every group in one call - useful for detecting
       # head-of-line stalls or building per-group progress dashboards.
       #
-      # @note Requires PGMQ v1.11.1+.
-      #
       # @param queue_name [String] name of the queue
       # @param vt [Integer] visibility timeout in seconds
       # @param qty [Integer] maximum number of groups to sample
@@ -254,6 +252,7 @@ module PGMQ
       #   heads.each do |msg|
       #     alert_if_stuck(msg) if msg.enqueued_at < Time.now - 3600
       #   end
+      # @note Requires PGMQ v1.11.1+.
       def read_grouped_head(queue_name, vt: DEFAULT_VT, qty: 1)
         validate_queue_name!(queue_name)
 

data/lib/pgmq/client/maintenance.rb

@@ -66,10 +66,6 @@ module PGMQ
       # If the archive table is already partitioned the function returns without error (idempotent). If the archive
       # table does not exist it also returns without error.
       #
-      # @note Requires the `pg_partman` PostgreSQL extension. If pg_partman is not installed and the archive table
-      #   exists, the call raises `PGMQ::Errors::ConnectionError`. If the archive table does not exist the call
-      #   succeeds (returns nil) without touching pg_partman, so no extension is needed in that case.
-      #
       # @param queue_name [String] name of the queue whose archive table to convert
       # @param partition_interval [String] partition interval passed to pg_partman (default: "10000" rows or a time
       #   expression such as "daily" / "1 month")
@@ -87,6 +83,9 @@ module PGMQ
       #     partition_interval: "daily",
       #     retention_interval: "30 days"
       #   )
+      # @note Requires the `pg_partman` PostgreSQL extension. If pg_partman is not installed and the archive table
+      #   exists, the call raises `PGMQ::Errors::ConnectionError`. If the archive table does not exist the call
+      #   succeeds (returns nil) without touching pg_partman, so no extension is needed in that case.
       def convert_archive_partitioned(
         queue_name,
         partition_interval: "10000",
@@ -185,9 +184,6 @@ module PGMQ
       # The return value mirrors `PG::Connection#wait_for_notify`: the channel name string on success,
       # or `nil` on timeout.
       #
-      # @note Orchestration (retry loop, reconnect-on-drop, graceful shutdown) is the caller's responsibility.
-      #   This method is a thin primitive — it listens once, waits, and returns.
-      #
       # @param queue_name [String] name of the queue (must have notifications enabled via {#enable_notify_insert})
       # @param timeout [Numeric, nil] seconds to wait; `nil` blocks indefinitely
       # @return [String, nil] notification channel name, or `nil` if the timeout expired
@@ -205,6 +201,8 @@ module PGMQ
       #   client.wait_for_notify("orders", timeout: 5) do |channel, pid, payload|
       #     puts "Notified on #{channel} by backend #{pid}"
       #   end
+      # @note Orchestration (retry loop, reconnect-on-drop, graceful shutdown) is the caller's responsibility.
+      #   This method is a thin primitive - it listens once, waits, and returns.
       def wait_for_notify(queue_name, timeout: nil)
         validate_queue_name!(queue_name)
         # PGMQ trigger fires pg_notify('pgmq.q_<queue>.INSERT', NULL)

data/lib/pgmq/client.rb

@@ -84,6 +84,16 @@ module PGMQ
       @connection.close
     end
 
+    # Drops every pooled connection and rebuilds lazily on the next checkout, leaving the pool usable (unlike {#close}).
+    # Use it to discard a connection that reports +CONNECTION_OK+ but is actually wedged - e.g. after a wall-clock
+    # timeout interrupted a query mid-flight and left the socket poisoned so it would re-hang on reuse. See
+    # {PGMQ::Connection#reload}.
+    #
+    # @return [void]
+    def reload
+      @connection.reload
+    end
+
     # Returns connection pool statistics
     #
     # @return [Hash] statistics about the connection pool

data/lib/pgmq/connection.rb

@@ -178,6 +178,26 @@ module PGMQ
       @pool.shutdown { |conn| conn.close unless conn.finished? }
     end
 
+    # Drops every connection currently in the pool and lets the pool build fresh ones lazily on the next checkout.
+    # Unlike {#close} (which shuts the pool down permanently), the pool stays usable afterwards.
+    #
+    # Use this to recover from a connection that libpq still reports as +CONNECTION_OK+ but which is in fact wedged -
+    # e.g. after a wall-clock timeout (+Timeout.timeout+) interrupted a query mid-flight, leaving the socket poisoned so
+    # it re-hangs on reuse. {#verify_connection!} cannot catch that case (the connection does not report
+    # +CONNECTION_BAD+), so the caller must discard it explicitly; +reload+ is the safe, pool-wide way to do so.
+    #
+    # @return [void]
+    # @example Discard the pool after a query had to be force-interrupted
+    #   begin
+    #     Timeout.timeout(5) { connection.with_connection { |conn| conn.exec("SELECT ...") } }
+    #   rescue Timeout::Error
+    #     connection.reload # drop the possibly-poisoned pooled connections
+    #     raise
+    #   end
+    def reload
+      @pool.reload { |conn| conn.close unless conn.finished? }
+    end
+
     # Returns connection pool statistics
     #
     # @return [Hash] statistics about the connection pool

data/lib/pgmq/queue_name.rb

@@ -126,13 +126,12 @@ module PGMQ
     # a digit), truncates to fit {MAX_LENGTH}, and falls back to {SANITIZE_FALLBACK} when nothing usable remains. The
     # return value always satisfies {.valid?}.
     #
+    # @param name [String, #to_s] arbitrary input
+    # @return [String] a guaranteed-valid queue name
     # @note Because it coerces rather than rejects, distinct inputs can map to the *same* name (e.g. +"a/b"+ and
     #   +"a-b"+ both become +"a_b"+; +"!!!"+ and +""+ both become +"queue"+). If your name selects a queue table,
     #   that means two logically different inputs could share one queue. When that matters - especially for untrusted
     #   input - prefer {.sanitize!}, which raises instead of substituting.
-    #
-    # @param name [String, #to_s] arbitrary input
-    # @return [String] a guaranteed-valid queue name
     def sanitize(name)
       cleaned = name.to_s.downcase
         .gsub(/[^a-z0-9_]+/, "_").squeeze("_")

data/lib/pgmq/version.rb

@@ -2,5 +2,5 @@
 
 module PGMQ
   # Current version of the pgmq-ruby gem
-  VERSION = "0.7.0"
+  VERSION = "0.7.2"
 end

data/pgmq-ruby.gemspec

@@ -26,7 +26,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Runtime dependencies
-  spec.add_dependency "connection_pool", "~> 2.4"
+  spec.add_dependency "connection_pool", ">= 2.4", "< 4"
   spec.add_dependency "pg", "~> 1.5"
   spec.add_dependency "zeitwerk", "~> 2.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgmq-ruby
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.2
 platform: ruby
 authors:
 - Maciej Mensfeld
@@ -13,16 +13,22 @@ dependencies:
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -107,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby client for PGMQ (Postgres Message Queue)
 test_files: []