pgmq-ruby 0.6.2 → 0.7.0

data/lib/pgmq/client/producer.rb

@@ -4,31 +4,36 @@ module PGMQ
   class Client
     # Message producing operations
     #
-    # This module handles producing messages to queues, both individual messages
-    # and batches. Users must serialize messages to JSON strings themselves.
+    # This module handles producing messages to queues, both individual messages and batches. Users must serialize
+    # messages to JSON strings themselves.
     module Producer
       # Produces a message to a queue
       #
       # @param queue_name [String] name of the queue
       # @param message [String] message as JSON string (for PostgreSQL JSONB)
       # @param headers [String, nil] optional headers as JSON string (for metadata, routing, tracing)
-      # @param delay [Integer] delay in seconds before message becomes visible
+      # @param delay [Numeric, Time] delay in seconds before message becomes visible (integer or float),
+      #   or an absolute Time at which the message becomes visible, including ActiveSupport::TimeWithZone
+      #   (PGMQ v1.10.0+)
       # @return [String] message ID as string
       #
       # @example Basic produce
       #   msg_id = client.produce("orders", '{"order_id":123,"total":99.99}')
       #
-      # @example With delay
+      # @example With integer delay (seconds)
       #   msg_id = client.produce("orders", '{"data":"value"}', delay: 60)
       #
+      # @example With absolute timestamp delay
+      #   msg_id = client.produce("orders", '{"data":"value"}', delay: Time.now + 3600)
+      #
       # @example With headers for routing/tracing
       #   msg_id = client.produce("orders", '{"order_id":123}',
       #     headers: '{"trace_id":"abc123","priority":"high"}')
       #
-      # @example With headers and delay
+      # @example With headers and absolute timestamp delay
       #   msg_id = client.produce("orders", '{"order_id":123}',
       #     headers: '{"correlation_id":"req-456"}',
-      #     delay: 30)
+      #     delay: Time.now + 300)
       #
       # @note Users must serialize to JSON themselves. Higher-level frameworks
       #       should handle serialization.
@@ -41,11 +46,21 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          if headers
+          if headers && !delay.is_a?(Numeric)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::timestamptz)",
+              [queue_name, message, headers, delay.to_time.utc.iso8601(6)]
+            )
+          elsif headers
             conn.exec_params(
               "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::jsonb, $4::integer)",
               [queue_name, message, headers, delay]
             )
+          elsif !delay.is_a?(Numeric)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::timestamptz)",
+              [queue_name, message, delay.to_time.utc.iso8601(6)]
+            )
           else
             conn.exec_params(
               "SELECT * FROM pgmq.send($1::text, $2::jsonb, $3::integer)",
@@ -62,7 +77,9 @@ module PGMQ
       # @param queue_name [String] name of the queue
       # @param messages [Array<String>] array of message payloads as JSON strings
       # @param headers [Array<String>, nil] optional array of headers as JSON strings (must match messages length)
-      # @param delay [Integer] delay in seconds before messages become visible
+      # @param delay [Numeric, Time] delay in seconds before messages become visible (integer or float),
+      #   or an absolute Time at which the messages become visible, including ActiveSupport::TimeWithZone
+      #   (PGMQ v1.10.0+)
       # @return [Array<String>] array of message IDs
       # @raise [ArgumentError] if headers array length doesn't match messages length
       #
@@ -97,19 +114,27 @@ module PGMQ
             "headers array length (#{headers.length}) must match messages array length (#{messages.length})"
         end
 
-        # Use PostgreSQL array parameter binding for security
-        # PG gem will properly encode the array values
         result = with_connection do |conn|
-          # Create array encoder for proper PostgreSQL array formatting
           encoder = PG::TextEncoder::Array.new
           encoded_messages = encoder.encode(messages)
 
-          if headers
+          if headers && !delay.is_a?(Numeric)
+            encoded_headers = encoder.encode(headers)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], $4::timestamptz)",
+              [queue_name, encoded_messages, encoded_headers, delay.to_time.utc.iso8601(6)]
+            )
+          elsif headers
             encoded_headers = encoder.encode(headers)
             conn.exec_params(
               "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::jsonb[], $4::integer)",
               [queue_name, encoded_messages, encoded_headers, delay]
             )
+          elsif !delay.is_a?(Numeric)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::timestamptz)",
+              [queue_name, encoded_messages, delay.to_time.utc.iso8601(6)]
+            )
           else
             conn.exec_params(
               "SELECT * FROM pgmq.send_batch($1::text, $2::jsonb[], $3::integer)",

data/lib/pgmq/client/queue_management.rb

@@ -4,12 +4,15 @@ module PGMQ
   class Client
     # Queue management operations (create, drop, list)
     #
-    # This module handles all queue lifecycle operations including creating queues
-    # (standard, partitioned, unlogged), dropping queues, and listing existing queues.
+    # This module handles all queue lifecycle operations including creating queues (standard, partitioned, unlogged),
+    # dropping queues, and listing existing queues.
     module QueueManagement
       # Creates a new queue
       #
       # @param queue_name [String] name of the queue to create
+      # @param tune_autovacuum [Boolean, Hash] when truthy, tune autovacuum on the new queue's tables after creation.
+      #   Pass +true+ for PGMQ-tuned defaults, or a Hash of options forwarded to {Autovacuum#tune_autovacuum}
+      #   (e.g. +{scale_factor: 0.005, archive: false}+). Defaults to +false+ (no change).
       # @return [Boolean] true if queue was created, false if it already existed
       # @raise [PGMQ::Errors::InvalidQueueNameError] if queue name is invalid
       # @raise [PGMQ::Errors::ConnectionError] if database operation fails
@@ -17,12 +20,16 @@ module PGMQ
       # @example
       #   client.create("orders")  # => true (created)
       #   client.create("orders")  # => false (already exists)
-      def create(queue_name)
+      #
+      # @example Create with tuned autovacuum
+      #   client.create("orders", tune_autovacuum: true)
+      def create(queue_name, tune_autovacuum: false)
         validate_queue_name!(queue_name)
 
         with_connection do |conn|
           existed = queue_exists?(conn, queue_name)
           conn.exec_params("SELECT pgmq.create($1::text)", [queue_name])
+          apply_tune_autovacuum_option(conn, queue_name, tune_autovacuum)
           !existed
         end
       end
@@ -34,6 +41,9 @@ module PGMQ
       # @param queue_name [String] name of the queue
       # @param partition_interval [String] partition interval (e.g., "daily", "10000")
       # @param retention_interval [String] retention interval (e.g., "7 days", "100000")
+      # @param tune_autovacuum [Boolean, Hash] when truthy, tune autovacuum on the new queue's tables after creation.
+      #   Pass +true+ for PGMQ-tuned defaults, or a Hash forwarded to {Autovacuum#tune_autovacuum}. Defaults to
+      #   +false+. Note: storage parameters are set on the partitioned parent and do not cascade to partitions.
       # @return [Boolean] true if queue was created, false if it already existed
       #
       # @example
@@ -44,7 +54,8 @@ module PGMQ
       def create_partitioned(
         queue_name,
         partition_interval: "10000",
-        retention_interval: "100000"
+        retention_interval: "100000",
+        tune_autovacuum: false
       )
         validate_queue_name!(queue_name)
 
@@ -54,6 +65,7 @@ module PGMQ
             "SELECT pgmq.create_partitioned($1::text, $2::text, $3::text)",
             [queue_name, partition_interval, retention_interval]
           )
+          apply_tune_autovacuum_option(conn, queue_name, tune_autovacuum)
           !existed
         end
       end
@@ -61,16 +73,20 @@ module PGMQ
       # Creates an unlogged queue for higher throughput (no crash recovery)
       #
       # @param queue_name [String] name of the queue
+      # @param tune_autovacuum [Boolean, Hash] when truthy, tune autovacuum on the new queue's tables after creation.
+      #   Pass +true+ for PGMQ-tuned defaults, or a Hash forwarded to {Autovacuum#tune_autovacuum}. Defaults to
+      #   +false+.
       # @return [Boolean] true if queue was created, false if it already existed
       #
       # @example
       #   client.create_unlogged("fast_queue")  # => true
-      def create_unlogged(queue_name)
+      def create_unlogged(queue_name, tune_autovacuum: false)
         validate_queue_name!(queue_name)
 
         with_connection do |conn|
           existed = queue_exists?(conn, queue_name)
           conn.exec_params("SELECT pgmq.create_unlogged($1::text)", [queue_name])
+          apply_tune_autovacuum_option(conn, queue_name, tune_autovacuum)
           !existed
         end
       end
@@ -94,6 +110,49 @@ module PGMQ
         result[0]["drop_queue"] == "t"
       end
 
+      # Creates the FIFO index on a queue's table required for grouped reads
+      #
+      # Grouped read operations (`read_grouped`, `read_grouped_rr`, `read_grouped_head`) rely on this index for correct
+      # ordering and acceptable query performance. Without it, grouped reads will work but may be slow or return
+      # incorrect ordering at scale. The operation is idempotent - calling it on a queue that already has the index is
+      # safe.
+      #
+      # @param queue_name [String] name of the queue
+      # @return [void]
+      # @raise [PGMQ::Errors::InvalidQueueNameError] if queue name is invalid
+      # @raise [PGMQ::Errors::ConnectionError] if database operation fails
+      #
+      # @example
+      #   client.create("tasks")
+      #   client.create_fifo_index("tasks")
+      def create_fifo_index(queue_name)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params("SELECT pgmq.create_fifo_index($1::text)", [queue_name])
+        end
+
+        nil
+      end
+
+      # Creates FIFO indexes on all existing queues
+      #
+      # Convenience wrapper that calls `create_fifo_index` for every queue registered in `pgmq.meta`. Useful for
+      # one-time migrations when adding grouped reads to an existing deployment. The operation is idempotent.
+      #
+      # @return [void]
+      # @raise [PGMQ::Errors::ConnectionError] if database operation fails
+      #
+      # @example Migrate an existing deployment to use grouped reads
+      #   client.create_fifo_indexes_all
+      def create_fifo_indexes_all
+        with_connection do |conn|
+          conn.exec("SELECT pgmq.create_fifo_indexes_all()")
+        end
+
+        nil
+      end
+
       # Lists all queues
       #
       # @return [Array<PGMQ::QueueMetadata>] array of queue metadata objects
@@ -123,6 +182,29 @@ module PGMQ
         )
         result.ntuples.positive?
       end
+
+      # Applies the +tune_autovacuum:+ creation option on the create connection.
+      #
+      # Accepts the same shapes the create methods document: +false+/+nil+ (no-op), +true+ (PGMQ-tuned defaults), or a
+      # Hash of {Autovacuum#tune_autovacuum} keyword options (+queue_settings:+, +archive:+, +archive_settings:+).
+      # Delegates resolution and the ALTER TABLE statements to {Autovacuum#tune_autovacuum_on}, the single source of
+      # truth shared with {Autovacuum#tune_autovacuum}, so defaults and the archive-skip rule cannot drift between the
+      # two paths. Runs on the connection that just created the queue, so the ALTER TABLE shares that checkout rather
+      # than acquiring a second one.
+      #
+      # @param conn [PG::Connection] the connection the queue was created on
+      # @param queue_name [String] name of the queue
+      # @param option [Boolean, Hash] the tune_autovacuum option as passed to the create method
+      # @option option [Hash] :queue_settings queue-table storage params, merged onto the defaults
+      # @option option [Boolean] :archive also tune the archive table (default: true)
+      # @option option [Hash] :archive_settings archive-table storage params, merged onto the defaults
+      # @return [void]
+      def apply_tune_autovacuum_option(conn, queue_name, option)
+        return unless option
+
+        opts = option.is_a?(Hash) ? option.transform_keys(&:to_sym) : {}
+        tune_autovacuum_on(conn, queue_name, **opts)
+      end
     end
   end
 end

data/lib/pgmq/client/topics.rb

@@ -4,8 +4,8 @@ module PGMQ
   class Client
     # Topic routing operations (AMQP-like patterns)
     #
-    # This module provides AMQP-style topic routing for PGMQ, allowing messages
-    # to be routed to multiple queues based on pattern matching.
+    # This module provides AMQP-style topic routing for PGMQ, allowing messages to be routed to multiple queues based on
+    # pattern matching.
     #
     # Topic patterns support wildcards:
     # - `*` matches exactly one word between dots (e.g., `orders.*` matches `orders.new`)
@@ -15,8 +15,7 @@ module PGMQ
     module Topics
       # Binds a topic pattern to a queue
       #
-      # Messages sent with routing keys matching this pattern will be delivered
-      # to the specified queue.
+      # Messages sent with routing keys matching this pattern will be delivered to the specified queue.
       #
       # @param pattern [String] topic pattern with optional wildcards (* or #)
       # @param queue_name [String] name of the queue to bind
@@ -66,8 +65,7 @@ module PGMQ
 
       # Sends a message via topic routing
       #
-      # The message will be delivered to all queues whose bound patterns match
-      # the routing key.
+      # The message will be delivered to all queues whose bound patterns match the routing key.
       #
       # @param routing_key [String] dot-separated routing key (e.g., "orders.new.priority")
       # @param message [String] message as JSON string
@@ -108,13 +106,14 @@ module PGMQ
 
       # Sends multiple messages via topic routing
       #
-      # All messages will be delivered to all queues whose bound patterns match
-      # the routing key.
+      # All messages will be delivered to all queues whose bound patterns match the routing key.
       #
       # @param routing_key [String] dot-separated routing key
       # @param messages [Array<String>] array of message payloads as JSON strings
       # @param headers [Array<String>, nil] optional array of headers as JSON strings
-      # @param delay [Integer] delay in seconds before messages become visible
+      # @param delay [Numeric, Time] delay in seconds before messages become visible (integer or float),
+      #   or an absolute Time at which the messages become visible, including ActiveSupport::TimeWithZone
+      #   (PGMQ v1.10.0+)
       # @return [Array<Hash>] array of hashes with :queue_name and :msg_id
       #
       # @example Batch topic send
@@ -135,12 +134,23 @@ module PGMQ
           encoder = PG::TextEncoder::Array.new
           encoded_messages = encoder.encode(messages)
 
-          if headers
+          if headers && !delay.is_a?(Numeric)
+            encoded_headers = encoder.encode(headers)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::jsonb[], $4::timestamptz)",
+              [routing_key, encoded_messages, encoded_headers, delay.to_time.utc.iso8601(6)]
+            )
+          elsif headers
             encoded_headers = encoder.encode(headers)
             conn.exec_params(
               "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::jsonb[], $4::integer)",
               [routing_key, encoded_messages, encoded_headers, delay]
             )
+          elsif !delay.is_a?(Numeric)
+            conn.exec_params(
+              "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::timestamptz)",
+              [routing_key, encoded_messages, delay.to_time.utc.iso8601(6)]
+            )
           elsif delay > 0
             conn.exec_params(
               "SELECT * FROM pgmq.send_batch_topic($1::text, $2::jsonb[], $3::integer)",
@@ -217,8 +227,8 @@ module PGMQ
 
       # Validates a routing key
       #
-      # Routing keys are dot-separated words (no wildcards allowed).
-      # Returns false for invalid routing keys (PGMQ raises an error for invalid keys).
+      # Routing keys are dot-separated words (no wildcards allowed). Returns false for invalid routing keys (PGMQ raises
+      # an error for invalid keys).
       #
       # @param routing_key [String] routing key to validate
       # @return [Boolean] true if valid, false if invalid

data/lib/pgmq/client.rb

@@ -3,8 +3,8 @@
 module PGMQ
   # Low-level client for interacting with PGMQ (Postgres Message Queue)
   #
-  # This is a thin wrapper around PGMQ SQL functions. For higher-level
-  # abstractions (job processing, retries, Rails integration), use pgmq-framework.
+  # This is a thin wrapper around PGMQ SQL functions. For higher-level abstractions (job processing, retries, Rails
+  # integration), use pgmq-framework.
   #
   # @example Basic usage
   #   client = PGMQ::Client.new(
@@ -34,6 +34,7 @@ module PGMQ
     include Maintenance          # Queue maintenance (purge, notifications)
     include Metrics              # Monitoring and metrics
     include Topics               # Topic routing (AMQP-like patterns, PGMQ v1.11.0+)
+    include Autovacuum           # Autovacuum tuning for queue/archive tables
 
     # Default visibility timeout in seconds
     DEFAULT_VT = 30
@@ -93,47 +94,61 @@ module PGMQ
       @connection.stats
     end
 
-    private
-
-    # Executes a block with a database connection
-    # @yield [PG::Connection] database connection
-    # @return [Object] result of the block
+    # Checks out a pooled connection and yields the raw +PG::Connection+ for arbitrary SQL.
+    #
+    # All PGMQ operations run through this method internally, so it carries the same guarantees: a connection is taken
+    # from the pool, health-checked when +auto_reconnect+ is enabled, and a single retry on a fresh connection is
+    # attempted if the checked-out connection turns out to be dead before any SQL is sent (see
+    # {PGMQ::Connection#with_connection}). The connection is returned to the pool when the block exits.
+    #
+    # Exposed so callers can issue PostgreSQL statements PGMQ does not wrap without standing up a second pool: ad-hoc
+    # +NOTIFY+, +LISTEN+, advisory locks, custom monitoring queries, or DDL that lives alongside your queue tables.
+    # Reusing the PGMQ pool keeps connection accounting in one place.
+    #
+    # @yield [PG::Connection] a pooled, health-checked database connection
+    # @return [Object] the return value of the block
+    # @raise [PGMQ::Errors::ConnectionError] if a connection cannot be obtained
+    #
+    # @example Fire a custom NOTIFY on the PGMQ pool
+    #   client.with_connection do |conn|
+    #     conn.exec_params("SELECT pg_notify($1, $2)", ["my_channel", payload])
+    #   end
+    #
+    # @example Run a query PGMQ does not wrap
+    #   depth = client.with_connection do |conn|
+    #     conn.exec("SELECT count(*) FROM pgmq.q_orders")[0]["count"].to_i
+    #   end
+    #
+    # @note You receive the raw +PG::Connection+. PGMQ performs no type mapping (results come back as strings) and does
+    #   not wrap your statement in a transaction. Use {#transaction} when you need atomicity.
+    #
+    # @note Do not retain or use the yielded connection outside the block. Once the block returns, the connection
+    #   goes back to the pool and another thread may check it out; +PG::Connection+ is not thread-safe, so using it
+    #   after the block can corrupt libpq state (nil results, wrong data, segfaults).
+    #
+    # @note The connection is returned to the pool *without* resetting session state. Anything session-scoped you
+    #   create - +LISTEN+, +SET+, a session-level advisory lock (+pg_advisory_lock+), a prepared statement, a temp
+    #   table - survives check-in and leaks to the next pool user. Undo it before the block exits (+UNLISTEN+,
+    #   +RESET+, +pg_advisory_unlock+, etc.). For LISTEN/NOTIFY consumption, prefer {#wait_for_notify}, which manages
+    #   +LISTEN+/+UNLISTEN+ for you.
     def with_connection(&)
       @connection.with_connection(&)
     end
 
+    private
+
     # Validates a queue name
+    #
+    # Delegates to {PGMQ::QueueName.validate!}, the single source of truth for queue-name rules. See
+    # {PGMQ::QueueName} for the +normalize+ and +sanitize+ helpers if you need to derive a valid name from
+    # friendlier or untrusted input before calling a queue operation.
+    #
     # @param queue_name [String] queue name to validate
     # @return [void]
     # @raise [PGMQ::Errors::InvalidQueueNameError] if name is invalid
     def validate_queue_name!(queue_name)
-      if queue_name.nil? || queue_name.to_s.strip.empty?
-        raise(
-          Errors::InvalidQueueNameError,
-          "Queue name cannot be empty"
-        )
-      end
-
-      # PGMQ creates tables with prefixes (pgmq.q_<name>, pgmq.a_<name>)
-      # PostgreSQL has a 63-character limit for identifiers, but PGMQ enforces 48
-      # to account for prefixes and potential suffixes
-      if queue_name.to_s.length >= 48
-        raise(
-          Errors::InvalidQueueNameError,
-          "Queue name '#{queue_name}' exceeds maximum length of 48 characters " \
-          "(current length: #{queue_name.to_s.length})"
-        )
-      end
-
-      # PostgreSQL identifier rules: start with letter or underscore,
-      # contain only letters, digits, underscores
-      return if queue_name.to_s.match?(/\A[a-zA-Z_][a-zA-Z0-9_]*\z/)
-
-      raise(
-        Errors::InvalidQueueNameError,
-        "Invalid queue name '#{queue_name}': must start with a letter or underscore " \
-        "and contain only letters, digits, and underscores"
-      )
+      QueueName.validate!(queue_name)
+      nil
     end
   end
 end

data/lib/pgmq/connection.rb

@@ -27,14 +27,11 @@ module PGMQ
     DEFAULT_POOL_TIMEOUT = 5
 
     class << self
-      # Additional error message patterns (String or Regexp) that mean the
-      # connection is dead and a retry on a fresh socket is safe. Strings are
-      # matched as case-insensitive substrings; Regexps match the original
-      # message. The built-in LOST_CONNECTION_MESSAGES are always checked
-      # first — this list is appended to them.
+      # Additional error message patterns (String or Regexp) that mean the connection is dead and a retry on a fresh
+      # socket is safe. Strings are matched as case-insensitive substrings; Regexps match the original message. The
+      # built-in LOST_CONNECTION_MESSAGES are always checked first - this list is appended to them.
       #
-      # Thread-safe: reads are lock-free (frozen array swap); writes should
-      # be done at boot time before forking workers.
+      # Thread-safe: reads are lock-free (frozen array swap); writes should be done at boot time before forking workers.
       #
       # @return [Array<String, Regexp>]
       # @example
@@ -42,9 +39,8 @@ module PGMQ
       #   PGMQ::Connection.reconnectable_error_patterns << /\Abroken pipe\b/i
       attr_reader :reconnectable_error_patterns
 
-      # Additional exception classes that mean the connection is dead.
-      # `PG::ConnectionBad` and `PG::UnableToSend` are always matched — this
-      # list is appended to them. Subclasses also match.
+      # Additional exception classes that mean the connection is dead. `PG::ConnectionBad` and `PG::UnableToSend` are
+      # always matched - this list is appended to them. Subclasses also match.
       #
       # Thread-safe: reads are lock-free; writes should be done at boot time.
       #
@@ -73,9 +69,8 @@ module PGMQ
 
       # Normalizes user-supplied reconnectable error patterns.
       #
-      # Strings are downcased once at configuration time so the hot path
-      # (`connection_lost_error?`) only does substring checks. Regexps are
-      # passed through unchanged.
+      # Strings are downcased once at configuration time so the hot path (`connection_lost_error?`) only does substring
+      # checks. Regexps are passed through unchanged.
       #
       # @param patterns [Array<String, Regexp>, String, Regexp, nil]
       # @return [Array<String, Regexp>]
@@ -198,11 +193,9 @@ module PGMQ
 
     private
 
-    # Messages libpq raises when the server/pooler has already torn down the
-    # socket. The list has grown organically with each pooler/TLS variant we
-    # see in the wild; the class check below catches future variants that
-    # libpq raises as `PG::ConnectionBad` or `PG::UnableToSend` without
-    # waiting for a new message to hit production.
+    # Messages libpq raises when the server/pooler has already torn down the socket. The list has grown organically with
+    # each pooler/TLS variant we see in the wild; the class check below catches future variants that libpq raises as
+    # `PG::ConnectionBad` or `PG::UnableToSend` without waiting for a new message to hit production.
     LOST_CONNECTION_MESSAGES = [
       "server closed the connection",
       "connection not open",
@@ -220,13 +213,10 @@ module PGMQ
 
     # Checks if the error indicates a lost connection.
     #
-    # Matches in three steps: first by class (`PG::ConnectionBad` /
-    # `PG::UnableToSend` are dedicated connection-failure classes libpq
-    # raises regardless of message, plus any user-supplied classes), then
-    # by built-in message substrings for the bare `PG::Error` cases where
-    # libpq doesn't reach for the specific subclass, and finally by
-    # user-supplied patterns (strings matched as case-insensitive
-    # substrings, Regexps matched against the original message).
+    # Matches in three steps: first by class (`PG::ConnectionBad` / `PG::UnableToSend` are dedicated connection-failure
+    # classes libpq raises regardless of message, plus any user-supplied classes), then by built-in message substrings
+    # for the bare `PG::Error` cases where libpq doesn't reach for the specific subclass, and finally by user-supplied
+    # patterns (strings matched as case-insensitive substrings, Regexps matched against the original message).
     #
     # @param error [PG::Error] the error to check
     # @return [Boolean] true if the connection was lost and a retry on a
@@ -252,11 +242,9 @@ module PGMQ
 
     # Verifies a connection is alive and working.
     #
-    # Also resets when the connection reports `PG::CONNECTION_BAD`, which
-    # happens when the server (or an intermediate pooler such as PgBouncer)
-    # has closed the socket while the client-side `PG::Connection` object
-    # still exists. `#finished?` alone only catches connections closed
-    # explicitly from the client side.
+    # Also resets when the connection reports `PG::CONNECTION_BAD`, which happens when the server (or an intermediate
+    # pooler such as PgBouncer) has closed the socket while the client-side `PG::Connection` object still exists.
+    # `#finished?` alone only catches connections closed explicitly from the client side.
     #
     # @param conn [PG::Connection] connection to verify
     # @raise [PG::Error] if the reset itself fails
@@ -306,16 +294,15 @@ module PGMQ
       ConnectionPool.new(size: @pool_size, timeout: @pool_timeout) do
         conn = create_connection(params)
 
-        # Detect shared connections: if a callable returns the same PG::Connection
-        # object to multiple pool slots, concurrent use will corrupt libpq state
-        # (nil results, segfaults, wrong data). Fail fast with a clear message.
+        # Detect shared connections: if a callable returns the same PG::Connection object to multiple pool slots,
+        # concurrent use will corrupt libpq state (nil results, segfaults, wrong data). Fail fast with a clear message.
         if conn.is_a?(PG::Connection)
           seen_mutex.synchronize do
             if seen_connections.key?(conn)
               raise PGMQ::Errors::ConfigurationError,
                 "Connection callable returned the same PG::Connection object " \
                 "(object_id: #{conn.object_id}) to multiple pool slots. " \
-                "PG::Connection is NOT thread-safe — concurrent use causes nil results, " \
+                "PG::Connection is NOT thread-safe - concurrent use causes nil results, " \
                 "segfaults, and data corruption. Ensure your callable returns a unique " \
                 "PG::Connection instance on each invocation (for example, by calling " \
                 "PG.connect inside the callable)."
@@ -338,10 +325,10 @@ module PGMQ
       # If we have a callable (e.g., for Rails), call it to get the connection
       return params.call if params.respond_to?(:call)
 
-      # Create new connection from parameters
-      # Low-level library: return all values as strings from PostgreSQL
-      # No automatic type conversion - let higher-level frameworks handle parsing
-      # conn.type_map_for_results intentionally NOT set
+      # Create new connection from parameters.
+      # Low-level library: return all values as strings from PostgreSQL.
+      # No automatic type conversion - let higher-level frameworks handle parsing.
+      # conn.type_map_for_results intentionally NOT set.
       PG.connect(params[:conninfo] || params)
     rescue PG::Error => e
       raise PGMQ::Errors::ConnectionError, "Failed to connect to database: #{e.message}"

data/lib/pgmq/message.rb

@@ -3,8 +3,8 @@
 module PGMQ
   # Represents a message read from a PGMQ queue
   #
-  # Returns raw values from PostgreSQL without transformation.
-  # Higher-level frameworks should handle parsing, deserialization, etc.
+  # Returns raw values from PostgreSQL without transformation. Higher-level frameworks should handle parsing,
+  # deserialization, etc.
   #
   # @example Reading a message (raw values)
   #   msg = client.read("my_queue", vt: 30)
@@ -24,9 +24,8 @@ module PGMQ
       # @param row [Hash] database row from PG result
       # @return [Message]
       def new(row, **)
-        # Return raw values as-is from PostgreSQL
-        # No parsing, no deserialization, no transformation
-        # The pg gem returns JSONB as String by default
+        # Return raw values as-is from PostgreSQL. No parsing, no deserialization, no transformation.
+        # The pg gem returns JSONB as String by default.
         super(
           msg_id: row["msg_id"],
           read_ct: row["read_ct"],

data/lib/pgmq/notify_throttle.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PGMQ
+  # Represents the NOTIFY throttle configuration for a queue
+  #
+  # @example Inspecting notification configuration
+  #   throttles = client.list_notify_insert_throttles
+  #   throttles.each do |t|
+  #     puts "#{t.queue_name}: #{t.throttle_interval_ms}ms (last notified: #{t.last_notified_at})"
+  #   end
+  class NotifyThrottle < Data.define(:queue_name, :throttle_interval_ms, :last_notified_at)
+    class << self
+      # Creates a new NotifyThrottle from a database row
+      # @param row [Hash] database row from PG result
+      # @return [NotifyThrottle]
+      def new(row, **)
+        super(
+          queue_name: row["queue_name"],
+          throttle_interval_ms: row["throttle_interval_ms"],
+          last_notified_at: row["last_notified_at"]
+        )
+      end
+    end
+  end
+end