pgmq-ruby 0.6.2 → 0.7.0

data/lib/pgmq/client/autovacuum.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module PGMQ
+  class Client
+    # Autovacuum and storage tuning for queue and archive tables.
+    #
+    # PGMQ tables churn in a way PostgreSQL's defaults are not tuned for. A hot queue inserts, updates, and deletes
+    # rows constantly: every read UPDATEs +vt+, +read_ct+, and +last_read_at+, and every read+archive cycle deletes
+    # from the queue table and inserts into the archive. Two defaults hurt under that load:
+    #
+    # - +autovacuum_vacuum_scale_factor+ defaults to 0.2, so autovacuum only runs after dead tuples reach 20% of the
+    #   table - by which point a busy queue has bloated its heap and B-tree indexes, slowing every read and lock.
+    # - +fillfactor+ defaults to 100, so heap pages fill completely. Because +vt+ is indexed and changes on every
+    #   read, those UPDATEs are not HOT-eligible; leaving page headroom reduces page density between vacuum passes.
+    #
+    # This module applies per-table storage parameters via +ALTER TABLE+ so autovacuum runs far more often (and
+    # fillfactor reserves churn headroom) on these specific tables, without touching cluster-wide settings. It is
+    # intentionally opt-in: the gem is a thin wrapper and does not mutate table storage parameters unless you ask it
+    # to (either by calling {#tune_autovacuum} or by passing +tune_autovacuum: true+ to a queue-creation method).
+    #
+    # @see https://www.postgresql.org/docs/current/runtime-config-autovacuum.html
+    # @see https://planetscale.com/blog/keeping-a-postgres-queue-healthy
+    module Autovacuum
+      # Default storage parameters for the active queue table. Aggressive: autovacuum and autoanalyze trigger at 1%/5%
+      # dead-or-changed tuples, a small +cost_delay+ keeps each vacuum pass quick, and +fillfactor+ reserves 30% of
+      # each page for the per-read UPDATE churn (the queue table is the only one that benefits from fillfactor).
+      DEFAULT_QUEUE_SETTINGS = {
+        autovacuum_vacuum_scale_factor: 0.01,
+        autovacuum_vacuum_threshold: 50,
+        autovacuum_vacuum_cost_delay: 2,
+        autovacuum_analyze_scale_factor: 0.05,
+        fillfactor: 70
+      }.freeze
+
+      # Default storage parameters for the archive table. Archives are append-heavy with periodic purge, so a looser
+      # scale factor and a slightly higher cost delay are enough while still beating the 0.2 default. No fillfactor:
+      # archive rows are inserted once and never updated, so there is no page-churn headroom to reserve.
+      DEFAULT_ARCHIVE_SETTINGS = {
+        autovacuum_vacuum_scale_factor: 0.05,
+        autovacuum_vacuum_threshold: 50,
+        autovacuum_vacuum_cost_delay: 5,
+        autovacuum_analyze_scale_factor: 0.05
+      }.freeze
+
+      # Storage parameters whose values are interpolated as Floats; everything else is interpolated as an Integer.
+      FLOAT_SETTINGS = %i[
+        autovacuum_vacuum_scale_factor
+        autovacuum_analyze_scale_factor
+      ].freeze
+      private_constant :FLOAT_SETTINGS
+
+      # Tunes autovacuum and storage parameters on a queue's underlying tables.
+      #
+      # Applies {DEFAULT_QUEUE_SETTINGS} to the queue table (+pgmq.q_<name>+) and, unless +archive: false+,
+      # {DEFAULT_ARCHIVE_SETTINGS} to the archive table (+pgmq.a_<name>+). Pass +queue_settings:+ / +archive_settings:+
+      # to override or extend the parameters per table; the Hash you pass is merged onto the defaults, so you only
+      # name the keys you want to change. Any other PostgreSQL storage default is left untouched. Safe to call
+      # repeatedly - +ALTER TABLE ... SET+ is idempotent for a given value.
+      #
+      # @param queue_name [String] name of the queue
+      # @param queue_settings [Hash{Symbol=>Numeric}] storage params for the queue table, merged onto
+      #   {DEFAULT_QUEUE_SETTINGS}
+      # @param archive [Boolean] also tune the archive table (default: true)
+      # @param archive_settings [Hash{Symbol=>Numeric}] storage params for the archive table, merged onto
+      #   {DEFAULT_ARCHIVE_SETTINGS}
+      # @return [void]
+      # @raise [PGMQ::Errors::InvalidQueueNameError] if the queue name is invalid
+      # @raise [PGMQ::Errors::ConnectionError] if the database operation fails (e.g. the queue does not exist)
+      #
+      # @example Apply PGMQ-tuned defaults to an existing queue
+      #   client.tune_autovacuum("orders")
+      #
+      # @example Override a couple of queue params, skip the archive
+      #   client.tune_autovacuum("orders", queue_settings: { autovacuum_vacuum_scale_factor: 0.005, fillfactor: 80 },
+      #                          archive: false)
+      #
+      # @note On a partitioned queue or archive, the parameters are set on the parent table. PostgreSQL does not
+      #   cascade storage parameters to existing partitions, so pre-existing partitions keep their own settings;
+      #   set them per-partition if needed.
+      def tune_autovacuum(queue_name, queue_settings: {}, archive: true, archive_settings: {})
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          tune_autovacuum_on(
+            conn,
+            queue_name,
+            queue_settings: queue_settings,
+            archive: archive,
+            archive_settings: archive_settings
+          )
+        end
+
+        nil
+      end
+
+      private
+
+      # Resolves storage settings against the PGMQ-tuned defaults and applies them on an existing connection.
+      #
+      # Single source of truth for both entry points: {#tune_autovacuum} (which passes its keyword arguments through)
+      # and the +tune_autovacuum:+ creation flag (which passes a possibly-empty Hash). Keeping the default resolution
+      # and the archive-skip rule here means the two paths cannot drift - +archive+ is a single truthiness test in one
+      # place, and per-table overrides are merged onto the defaults in one place.
+      #
+      # @param conn [PG::Connection] the connection to run the ALTER TABLE statements on
+      # @param queue_name [String] name of the queue (already validated)
+      # @param queue_settings [Hash] queue-table overrides, merged onto {DEFAULT_QUEUE_SETTINGS}
+      # @param archive [Boolean] also tune the archive table
+      # @param archive_settings [Hash] archive-table overrides, merged onto {DEFAULT_ARCHIVE_SETTINGS}
+      # @return [void]
+      def tune_autovacuum_on(conn, queue_name, queue_settings: {}, archive: true, archive_settings: {})
+        alter_storage(conn, "q_#{queue_name}", DEFAULT_QUEUE_SETTINGS.merge(symbolize(queue_settings)))
+
+        return unless archive
+
+        alter_storage(conn, "a_#{queue_name}", DEFAULT_ARCHIVE_SETTINGS.merge(symbolize(archive_settings)))
+      end
+
+      # Issues a single ALTER TABLE setting the given storage parameters on one pgmq table.
+      #
+      # PGMQ folds queue names to lower case when it creates the backing tables (`pgmq.create('MyQueue')` produces
+      # `pgmq.q_myqueue`), so the table name is lower-cased to match the physical table before it is quoted. Without
+      # this, a mixed-case queue name would build `q_MyQueue`, and +quote_ident+ would preserve that case and target a
+      # non-existent relation.
+      #
+      # Identifiers cannot be passed as bind parameters, so the table name is quoted with the connection's
+      # +quote_ident+. The queue name has already passed {#validate_queue_name!} (strict identifier rules); the
+      # parameter names are validated against the known default keys; and the values are coerced to Float/Integer, so
+      # no untrusted text reaches the statement.
+      #
+      # @param conn [PG::Connection] database connection
+      # @param table [String] unqualified table name (e.g. "q_orders")
+      # @param settings [Hash{Symbol=>Numeric}] storage parameters to set
+      # @return [void]
+      def alter_storage(conn, table, settings)
+        qualified = "pgmq.#{conn.quote_ident(table.downcase)}"
+        clause = settings.map { |key, value| "#{storage_param_name(key)} = #{coerce_setting(key, value)}" }.join(", ")
+
+        conn.exec("ALTER TABLE #{qualified} SET (#{clause})")
+      end
+
+      # Validates a storage-parameter name against the known keys before it is interpolated into SQL.
+      #
+      # Parameter names cannot be bound; allow-listing them against the union of the queue and archive default keys
+      # keeps an arbitrary Symbol from being injected as a raw identifier.
+      #
+      # @param key [Symbol] storage parameter name
+      # @return [String] the validated parameter name
+      # @raise [ArgumentError] if the key is not a recognised storage parameter
+      def storage_param_name(key)
+        return key.to_s if known_storage_params.include?(key)
+
+        raise ArgumentError, "Unknown storage parameter #{key.inspect}; allowed: #{known_storage_params.to_a.sort}"
+      end
+
+      # @return [Set<Symbol>] the union of queue and archive default keys
+      def known_storage_params
+        @known_storage_params ||= (DEFAULT_QUEUE_SETTINGS.keys + DEFAULT_ARCHIVE_SETTINGS.keys).to_set
+      end
+
+      # Coerces a setting value to its SQL form: Float for scale factors, Integer for everything else. Raising on
+      # non-numeric input is the injection guard for values.
+      #
+      # @param key [Symbol] storage parameter name
+      # @param value [Numeric, String] the value to coerce
+      # @return [Float, Integer]
+      def coerce_setting(key, value)
+        FLOAT_SETTINGS.include?(key) ? Float(value) : Integer(value)
+      end
+
+      # Symbolizes top-level keys of a settings Hash so callers may pass either Symbol or String keys.
+      #
+      # @param settings [Hash]
+      # @return [Hash{Symbol=>Object}]
+      def symbolize(settings)
+        settings.to_h.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/pgmq/client/consumer.rb

@@ -4,8 +4,8 @@ module PGMQ
   class Client
     # Single-queue message reading operations
     #
-    # This module handles reading messages from a single queue, including basic reads,
-    # batch reads, and long-polling for efficient message consumption.
+    # This module handles reading messages from a single queue, including basic reads, batch reads, and long-polling for
+    # efficient message consumption.
     module Consumer
       # Reads a message from the queue
       #
@@ -151,11 +151,126 @@ module PGMQ
         result.map { |row| Message.new(row) }
       end
 
+      # Reads messages using SQS-style grouped ordering (throughput-optimised)
+      #
+      # Messages are grouped by the first key in their JSON payload. Unlike round-robin, this strategy fills the
+      # requested batch from the oldest group first, then moves on to the next group only when the first is exhausted.
+      # Maximises throughput for bursty workloads at the cost of fairness across groups.
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] number of messages to read
+      # @return [Array<PGMQ::Message>] array of messages, oldest group first
+      #
+      # @example Throughput-first batch processing
+      #   # Queue contains: user1_msg1, user1_msg2, user2_msg1
+      #   messages = client.read_grouped("tasks", vt: 30, qty: 3)
+      #   # Returns: user1_msg1, user1_msg2, user2_msg1  (drains user1 first)
+      #
+      # @example High-volume processing where fairness is not required
+      #   loop do
+      #     messages = client.read_grouped("jobs", vt: 30, qty: 20)
+      #     break if messages.empty?
+      #     messages.each { |msg| process(msg) }
+      #   end
+      def read_grouped(queue_name, vt: DEFAULT_VT, qty: 1)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT * FROM pgmq.read_grouped($1::text, $2::integer, $3::integer)",
+            [queue_name, vt, qty]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Reads messages using SQS-style grouped ordering with long-polling support
+      #
+      # Combines SQS-style throughput-first grouped ordering with long-polling. Blocks up to max_poll_seconds if the
+      # queue is empty, returning as soon as any message arrives.
+      #
+      # @param queue_name [String] name of the queue
+      # @param vt [Integer] visibility timeout in seconds
+      # @param qty [Integer] number of messages to read
+      # @param max_poll_seconds [Integer] maximum time to poll in seconds
+      # @param poll_interval_ms [Integer] interval between polls in milliseconds
+      # @return [Array<PGMQ::Message>] array of messages
+      #
+      # @example Poll with throughput-first grouped ordering
+      #   messages = client.read_grouped_with_poll("jobs",
+      #     vt: 30,
+      #     qty: 10,
+      #     max_poll_seconds: 5,
+      #     poll_interval_ms: 100
+      #   )
+      def read_grouped_with_poll(
+        queue_name,
+        vt: DEFAULT_VT,
+        qty: 1,
+        max_poll_seconds: 5,
+        poll_interval_ms: 100
+      )
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT * FROM pgmq.read_grouped_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)",
+            [queue_name, vt, qty, max_poll_seconds, poll_interval_ms]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Reads one message per FIFO group from the head of each group
+      #
+      # Returns exactly one message - the oldest visible message - from each distinct FIFO group, up to qty groups.
+      # Groups are determined by the `x-pgmq-group` key in the message headers (set via the `headers:` param on
+      # `produce`). Messages without that header key all land in a single implicit default group, so only one of them is
+      # returned per call.
+      #
+      # Unlike `read_grouped` (which groups by the first payload key and drains one group fully before moving to the
+      # 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
+      # @return [Array<PGMQ::Message>] one message per group, up to qty
+      #
+      # @example Sample the head of each group
+      #   # Produce with x-pgmq-group headers so each tenant is a separate group
+      #   client.produce("tasks", '{"job":"build"}', headers: '{"x-pgmq-group":"tenant_a"}')
+      #   client.produce("tasks", '{"job":"test"}',  headers: '{"x-pgmq-group":"tenant_b"}')
+      #   messages = client.read_grouped_head("tasks", vt: 30, qty: 10)
+      #   # Returns: one message from tenant_a and one from tenant_b
+      #
+      # @example Monitor for stuck groups
+      #   heads = client.read_grouped_head("jobs", vt: 30, qty: 100)
+      #   heads.each do |msg|
+      #     alert_if_stuck(msg) if msg.enqueued_at < Time.now - 3600
+      #   end
+      def read_grouped_head(queue_name, vt: DEFAULT_VT, qty: 1)
+        validate_queue_name!(queue_name)
+
+        result = with_connection do |conn|
+          conn.exec_params(
+            "SELECT * FROM pgmq.read_grouped_head($1::text, $2::integer, $3::integer)",
+            [queue_name, vt, qty]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
       # Reads messages using grouped round-robin ordering
       #
-      # Messages are grouped by the first key in their JSON payload and returned
-      # in round-robin order across groups. This ensures fair processing when
-      # messages from different entities (users, orders, etc.) are in the queue.
+      # Messages are grouped by the first key in their JSON payload and returned in round-robin order across groups.
+      # This ensures fair processing when messages from different entities (users, orders, etc.) are in the queue.
       #
       # @param queue_name [String] name of the queue
       # @param vt [Integer] visibility timeout in seconds
@@ -188,8 +303,7 @@ module PGMQ
 
       # Reads messages using grouped round-robin with long-polling support
       #
-      # Combines grouped round-robin ordering with long-polling for efficient
-      # and fair message consumption.
+      # Combines grouped round-robin ordering with long-polling for efficient and fair message consumption.
       #
       # @param queue_name [String] name of the queue
       # @param vt [Integer] visibility timeout in seconds

data/lib/pgmq/client/maintenance.rb

@@ -4,8 +4,7 @@ module PGMQ
   class Client
     # Queue maintenance operations
     #
-    # This module handles queue maintenance tasks such as purging messages
-    # and detaching archive tables.
+    # This module handles queue maintenance tasks such as purging messages and detaching archive tables.
     module Maintenance
       # Purges all messages from a queue
       #
@@ -27,9 +26,8 @@ module PGMQ
 
       # Enables PostgreSQL NOTIFY when messages are inserted into a queue
       #
-      # When enabled, PostgreSQL will send a NOTIFY event on message insert,
-      # allowing clients to use LISTEN instead of polling. The throttle interval
-      # prevents notification storms during high-volume inserts.
+      # When enabled, PostgreSQL will send a NOTIFY event on message insert, allowing clients to use LISTEN instead of
+      # polling. The throttle interval prevents notification storms during high-volume inserts.
       #
       # @param queue_name [String] name of the queue
       # @param throttle_interval_ms [Integer] minimum ms between notifications (default: 250)
@@ -56,6 +54,105 @@ module PGMQ
         nil
       end
 
+      # Converts a standard queue's archive table to a pg_partman-managed partitioned table
+      #
+      # Provides a migration path for queues originally created with `create` or `create_unlogged` whose archive tables
+      # have grown large enough to benefit from partitioning. The queue message table is not affected - only the archive
+      # table (`pgmq.a_<queue_name>`) is converted.
+      #
+      # The operation renames the existing archive table to `pgmq.a_<queue_name>_old`, creates a new partitioned table
+      # with the same schema, and hands it over to pg_partman for lifecycle management. **Existing archived rows are
+      # left in the `_old` table and must be migrated manually** if visibility in the new partitioned archive is needed.
+      # 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")
+      # @param retention_interval [String] retention interval passed to pg_partman (default: "100000")
+      # @param leading_partition [Integer] number of leading partitions pg_partman should pre-create (default: 10)
+      # @return [void]
+      # @raise [PGMQ::Errors::InvalidQueueNameError] if queue name is invalid
+      # @raise [PGMQ::Errors::ConnectionError] if the database operation fails (e.g. pg_partman not installed)
+      #
+      # @example Convert with default partitioning (row-count based)
+      #   client.convert_archive_partitioned("orders")
+      #
+      # @example Convert with time-based daily partitioning
+      #   client.convert_archive_partitioned("orders",
+      #     partition_interval: "daily",
+      #     retention_interval: "30 days"
+      #   )
+      def convert_archive_partitioned(
+        queue_name,
+        partition_interval: "10000",
+        retention_interval: "100000",
+        leading_partition: 10
+      )
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.convert_archive_partitioned($1::text, $2::text, $3::text, $4::integer)",
+            [queue_name, partition_interval, retention_interval, leading_partition]
+          )
+        end
+
+        nil
+      end
+
+      # Lists all queues that have a NOTIFY trigger enabled, with their throttle configuration
+      #
+      # Returns one {PGMQ::NotifyThrottle} per queue that has had {#enable_notify_insert} called on it.
+      # Useful for auditing notification configuration across all queues at once.
+      #
+      # @return [Array<PGMQ::NotifyThrottle>] throttle configs (empty array if none configured)
+      #
+      # @example
+      #   throttles = client.list_notify_insert_throttles
+      #   throttles.each do |t|
+      #     puts "#{t.queue_name}: #{t.throttle_interval_ms}ms"
+      #   end
+      def list_notify_insert_throttles
+        result = with_connection do |conn|
+          conn.exec("SELECT * FROM pgmq.list_notify_insert_throttles()")
+        end
+
+        result.map { |row| PGMQ::NotifyThrottle.new(row) }
+      end
+
+      # Updates the throttle interval for an already-enabled NOTIFY trigger
+      #
+      # Changes how frequently PostgreSQL is allowed to fire a NOTIFY event on message insert, without
+      # having to disable and re-enable the trigger. The queue must already have notifications enabled
+      # via {#enable_notify_insert}.
+      #
+      # @param queue_name [String] name of the queue
+      # @param throttle_interval_ms [Integer] new minimum ms between notifications
+      # @return [void]
+      #
+      # @example Tighten throttle to 100ms during high-throughput ingestion
+      #   client.update_notify_insert("orders", throttle_interval_ms: 100)
+      #
+      # @example Remove throttling entirely
+      #   client.update_notify_insert("orders", throttle_interval_ms: 0)
+      def update_notify_insert(queue_name, throttle_interval_ms:)
+        validate_queue_name!(queue_name)
+
+        with_connection do |conn|
+          conn.exec_params(
+            "SELECT pgmq.update_notify_insert($1::text, $2::integer)",
+            [queue_name, throttle_interval_ms]
+          )
+        end
+
+        nil
+      end
+
       # Disables PostgreSQL NOTIFY for a queue
       #
       # @param queue_name [String] name of the queue
@@ -72,6 +169,58 @@ module PGMQ
 
         nil
       end
+
+      # Blocks until a PostgreSQL NOTIFY arrives on the queue's channel or the timeout expires.
+      #
+      # PGMQ sends notifications on the channel `pgmq.q_<queue_name>.INSERT` whenever a message is inserted (requires
+      # {#enable_notify_insert} to be called first). This method issues `LISTEN`, waits for a notification via the `pg`
+      # gem's `wait_for_notify`, then issues `UNLISTEN` before returning the connection to the pool.
+      #
+      # Compared with {PGMQ::Client::Consumer#read_with_poll}, which holds the connection inside a PL/pgSQL loop for
+      # the full poll window, `wait_for_notify` releases the connection the moment a notification arrives (or the
+      # timeout expires). This makes it more efficient under low message rates where the poll window would otherwise
+      # burn idle time.
+      #
+      # The optional block receives `channel`, `backend_pid`, and `payload` when a notification arrives.
+      # 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
+      #
+      # @example Basic usage (wake up when a message arrives, then read it)
+      #   client.enable_notify_insert("orders")
+      #
+      #   loop do
+      #     next unless client.wait_for_notify("orders", timeout: 5)
+      #     msg = client.read("orders", vt: 30)
+      #     process(msg) if msg
+      #   end
+      #
+      # @example Block form (inspect notification metadata)
+      #   client.wait_for_notify("orders", timeout: 5) do |channel, pid, payload|
+      #     puts "Notified on #{channel} by backend #{pid}"
+      #   end
+      def wait_for_notify(queue_name, timeout: nil)
+        validate_queue_name!(queue_name)
+        # PGMQ trigger fires pg_notify('pgmq.q_<queue>.INSERT', NULL)
+        channel = "pgmq.q_#{queue_name}.INSERT"
+
+        with_connection do |conn|
+          conn.exec("LISTEN \"#{channel}\"")
+          begin
+            conn.wait_for_notify(timeout) do |ch, pid, payload|
+              yield ch, pid, payload if block_given?
+            end
+          ensure
+            conn.exec("UNLISTEN \"#{channel}\"")
+          end
+        end
+      end
     end
   end
 end

data/lib/pgmq/client/message_lifecycle.rb

@@ -4,8 +4,8 @@ module PGMQ
   class Client
     # Message lifecycle operations (pop, delete, archive, visibility timeout)
     #
-    # This module handles message state transitions including popping (atomic read+delete),
-    # deleting, archiving, and updating visibility timeouts.
+    # This module handles message state transitions including popping (atomic read+delete), deleting, archiving, and
+    # updating visibility timeouts.
     module MessageLifecycle
       # Pops a message (atomic read + delete)
       #
@@ -104,8 +104,8 @@ module PGMQ
 
       # Deletes specific messages from multiple queues in a single transaction
       #
-      # Efficiently deletes messages across different queues atomically.
-      # Useful when processing related messages from different queues.
+      # Efficiently deletes messages across different queues atomically. Useful when processing related messages from
+      # different queues.
       #
       # @param deletions [Hash] hash of queue_name => array of msg_ids
       # @return [Hash] hash of queue_name => array of deleted msg_ids
@@ -307,9 +307,8 @@ module PGMQ
 
       # Updates visibility timeout for messages across multiple queues in a single transaction
       #
-      # Efficiently updates visibility timeouts across different queues atomically.
-      # Useful when processing related messages from different queues and needing
-      # to extend their visibility timeouts together.
+      # Efficiently updates visibility timeouts across different queues atomically. Useful when processing related
+      # messages from different queues and needing to extend their visibility timeouts together.
       #
       # Supports two modes:
       # - Integer offset (seconds from now): `vt: 60` - messages visible in 60 seconds

data/lib/pgmq/client/metrics.rb

@@ -4,8 +4,7 @@ module PGMQ
   class Client
     # Queue metrics and monitoring
     #
-    # This module handles retrieving queue metrics such as queue length,
-    # message age, and total message counts.
+    # This module handles retrieving queue metrics such as queue length, message age, and total message counts.
     module Metrics
       # Gets metrics for a specific queue
       #

data/lib/pgmq/client/multi_queue.rb

@@ -4,13 +4,13 @@ module PGMQ
   class Client
     # Multi-queue operations
     #
-    # This module handles efficient operations across multiple queues using single
-    # database queries with UNION ALL for optimal performance.
+    # This module handles efficient operations across multiple queues using single database queries with UNION ALL for
+    # optimal performance.
     module MultiQueue
       # Reads from multiple queues in a single query
       #
-      # This is the most efficient way to monitor multiple queues with a single
-      # database connection. Uses UNION ALL to read from all queues in one query.
+      # This is the most efficient way to monitor multiple queues with a single database connection. Uses UNION ALL to
+      # read from all queues in one query.
       #
       # @param queue_names [Array<String>] array of queue names to read from
       # @param vt [Integer] visibility timeout in seconds
@@ -53,8 +53,7 @@ module PGMQ
         # Validate all queue names (prevents SQL injection)
         queue_names.each { |qn| validate_queue_name!(qn) }
 
-        # Build UNION ALL query for all queues
-        # Note: Queue names are validated, so this is safe from SQL injection
+        # Build UNION ALL query for all queues. Note: Queue names are validated, so this is safe from SQL injection.
         union_queries = queue_names.map do |queue_name|
           # Escape single quotes in queue name (though validation should prevent this)
           escaped_name = queue_name.gsub("'", "''")
@@ -76,9 +75,8 @@ module PGMQ
 
       # Reads from multiple queues with long-polling (waits for messages)
       #
-      # Efficiently polls multiple queues waiting for the first available message.
-      # This uses a single connection with periodic polling until a message arrives
-      # or the timeout is reached.
+      # Efficiently polls multiple queues waiting for the first available message. This uses a single connection with
+      # periodic polling until a message arrives or the timeout is reached.
       #
       # @param queue_names [Array<String>] array of queue names to poll
       # @param vt [Integer] visibility timeout in seconds
@@ -144,8 +142,8 @@ module PGMQ
 
       # Pops a message from multiple queues (atomic read + delete)
       #
-      # Efficiently gets and immediately deletes the first available message from
-      # any of the specified queues. Uses a single query with UNION ALL.
+      # Efficiently gets and immediately deletes the first available message from any of the specified queues. Uses a
+      # single query with UNION ALL.
       #
       # @param queue_names [Array<String>] array of queue names
       # @return [PGMQ::Message, nil] message with queue_name attribute, or nil if no messages