pgmq-ruby 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b279a0ca02d6b0970b00c829df9201f746bc112157d9b782308bbdf2238daae
-  data.tar.gz: b3d46c1e884ff4e362a15c3384f8b0cc1515f16fdc1806606376fbd855011087
+  metadata.gz: 5e359ff6e278f15f414b12524d8922c6f7ae7cfb274ce770250ca347a88c160d
+  data.tar.gz: 821beca651d6115f7c1f9ef46efe63b5985eb07ac8f77ed3b31a26e51ff85b23
 SHA512:
-  metadata.gz: 9c8b865a9296430fe93b3ab7e7a8fb89857370cd29c8288cd61f8ccc5ddf4ef7a192070e1479079dd8920361997911595c6b2fc7b3239b0d69aee161680c272e
-  data.tar.gz: 92ac6cf951476851bb442d10497317f53496594fd4da05171b0fab0f2e9191a6e5d0251cd5154025501dbac1b802175050b5d9eb712e4dac8f3b9f7ba839a305
+  metadata.gz: 31215de55d5ae155d1e364263c36c1fce1bcbf1d07774c8afbd9bde05e8e607dbf0bdb1c4bd62db527431dc9332e3828f78109ad4361963319a61db3a5a23520
+  data.tar.gz: e52b05c020270c1d90f50c238d95e042af6e8d1b69849f483de1e62695cd1f085bac5b762de76c3d35466355d52fc3fa9bbca316a576bbbab577beaa45beca71

data/CHANGELOG.md

@@ -1,5 +1,102 @@
 # Changelog
 
+## 0.8.0 (2026-10-25)
+
+### Consumer
+- **[Feature]** Add `PGMQ::Consumer`, a minimal single-threaded consumer loop modelled on the rdkafka-ruby simple
+  consumer. `PGMQ::Consumer.new(client, queue, vt:, batch_size:, max_poll_seconds:, poll_interval_ms:, on_success:,
+  max_attempts:)` wraps an existing client; `#each` long-polls with `read_with_poll`, yields one `PGMQ::Message` at a
+  time and deletes (or archives, `on_success: :archive`) it when the block returns. A block exception stops the loop
+  and is re-raised without acknowledging the message, so it reappears after `vt` (at-least-once delivery). Messages
+  whose `read_ct` exceeds `max_attempts` (requires `batch_size: 1`) are archived without being yielded. `#stop` only
+  sets a flag, so it is safe in a signal trap; the loop finishes the messages it already read, then returns.
+- **[Feature]** `PGMQ::Consumer` consumes several queues when given an Array of names (`PGMQ::Consumer.new(client,
+  %w[orders emails])`), like an rdkafka-ruby consumer subscribed to several topics. It reads them with
+  `read_multi_with_poll`, rotating the read order each poll, sets `queue_name` on every yielded message and
+  acknowledges each message on its own queue. With `max_attempts`, it reads one message per poll across all queues.
+
+### Metrics
+- **[Feature]** `PGMQ::Metrics` exposes `queue_visible_length` (messages whose visibility timeout has passed, PGMQ
+  v1.5.0+) and `default_partition_length` (estimated rows in the default partitions of a partitioned queue and its
+  archive, PGMQ v1.13.0+; `nil` for non-partitioned queues, non-zero means pg_partman maintenance is failing). Both
+  are raw values like the other fields, and `nil` on PGMQ versions that do not return them.
+
+### Queue Management
+- **[Feature]** `create_partitioned` accepts `premake:`, the number of partitions pg_partman creates ahead of the
+  current one for the queue and archive tables (PGMQ's default is 4). Raise it when writes outrun the pre-made
+  partitions and land in the default partition. Requires PGMQ v1.13.0+ when given; without it the SQL call is
+  unchanged.
+
+### Documentation
+- **[Fix]** YARD examples used a non-existent `msg.payload`; they now use `msg.message`.
+- **[Fix]** The README long-polling example now treats the `read_with_poll` result as an Array of messages.
+- **[Fix]** The `enable_notify_insert` and `wait_for_notify` docs and the README now say that on PGMQ older than
+  v1.13.1, insert notifications never fire for a queue name with uppercase letters (pgmq/pgmq#593). Create queues with
+  lower-case names, or use PGMQ v1.13.1+.
+
+### Producer
+- **[Fix]** A Float `delay:` in `produce`, `produce_batch`, `produce_topic` and `produce_batch_topic` no longer fails
+  with `PGMQ::Errors::ConnectionError` (`invalid input syntax for type integer`). A fractional delay such as `1.5` now
+  makes the message visible 1.5 seconds later: it is sent to PGMQ's `timestamptz` overload as `clock_timestamp()`
+  plus the delay (PGMQ v1.10.0+), the same way PGMQ handles an integer delay. Integer and `Time` delays are unchanged.
+- **[Breaking]** `produce` and `produce_batch` raise `PGMQ::Errors::MessageInvalidError` when a message is not a
+  String (including `nil`) or headers are neither a String nor `nil`. Previously a Hash or `nil` was bound as SQL
+  NULL, so the call returned a `msg_id` but the message or headers were stored as NULL without an error. Any other
+  non-String value now raises too, including Integer, Float, `true` and Array values that were stored as JSON before,
+  `false` headers that were dropped, and Hash values on a connection with a query type map
+  (`PG::BasicTypeMapForQueries`), which were stored as JSON objects. The error message names the invalid key
+  (`message` or `headers`; in a batch `messages.<index>.message` or `messages.<index>.headers`) and the reason, such
+  as `must be a JSON String`. Inside `transaction` the error is wrapped in `PGMQ::Errors::ConnectionError` like any
+  other error. Serialize payloads to JSON before producing. The check is the new `PGMQ::Contracts::Message`, built on
+  `PGMQ::Contractable`, the contract layer extracted from karafka-core (no new dependency).
+
+### Validation
+- **[Breaking]** Every argument check now runs through a contract in `PGMQ::Contracts` (`Message`, `Batch`,
+  `MultiQueue`, `Consumer`, `Autovacuum`, `Connection`), with the error messages in `config/locales/errors.yml`.
+  Client calls raise new validation errors instead of `ArgumentError`, like WaterDrop:
+  `PGMQ::Errors::MessageInvalidError` (`produce`, `produce_batch`, `produce_batch_topic`),
+  `PGMQ::Errors::MultiQueueInvalidError` (`read_multi`, `read_multi_with_poll`, `pop_multi`, `delete_multi`,
+  `archive_multi`, `set_vt_multi`) and `PGMQ::Errors::AutovacuumSettingsInvalidError` (`tune_autovacuum`). They
+  inherit from `PGMQ::Errors::BaseError`, not from `ArgumentError`, so `rescue ArgumentError` no longer catches them.
+  `PGMQ::Consumer.new`, the connection parameters and the `PGMQ::Connection` reconnectable error settings still raise
+  `PGMQ::Errors::ConfigurationError`. The message is now a Hash of each invalid key and its reason, such as
+  `queue_names` and `cannot be empty`. The headers length error of `produce_batch` and `produce_batch_topic` no longer
+  includes the two lengths. New checks: `produce_batch` and `produce_batch_topic` raise
+  `PGMQ::Errors::MessageInvalidError` when messages is not an Array or headers is neither an Array nor `nil` (String
+  headers failed in SQL with `PGMQ::Errors::ConnectionError` before), and `tune_autovacuum` checks the queue and
+  archive settings before it changes any table (an unknown archive setting raised only after the queue table was
+  changed). A setting value that is not numeric raises `PGMQ::Errors::AutovacuumSettingsInvalidError` too, also before
+  any table changes (it raised `ArgumentError` from `Float()` or `Integer()` for a String, `TypeError` for other values
+  such as `nil` or `true`, so `rescue TypeError` no longer catches it). Two calls that returned without an error now
+  raise a validation error: `produce_batch` and `produce_batch_topic` with an empty messages Array and non-empty or
+  String headers (they returned `[]`), and `tune_autovacuum` (and `create` with `tune_autovacuum:`) with
+  `archive: false` and an unknown or non-numeric archive setting (it ignored the archive settings).
+
+### Transactions
+- **[Fix]** The transactional client yielded by `PGMQ::Client#transaction` now raises the new
+  `PGMQ::Errors::TransactionError` when used from another thread or fiber, or after the block has returned.
+  Previously such calls checked out a different pool connection and committed outside the transaction, so a
+  rollback did not undo them (and with `pool_size: 1` they waited for the pool timeout). An unrescued
+  `TransactionError` propagates from `#transaction` as is, not wrapped in `PGMQ::Errors::ConnectionError`.
+
+### Testing
+- **[Fix]** Transaction tests produce JSON strings instead of Hashes, which were stored as NULL.
+- **[Change]** Add `spec/integration/concurrency_overlap_spec.rb`, which proves concurrency by asserting overlapping
+  execution intervals (not order or absolute timings): threads and fibers overlap on long polls and `LISTEN` waits,
+  the reactor keeps running, a pool of one serializes work, and the transactional client rejects other threads and
+  fibers. `ConcurrencyTracker` now uses the monotonic clock, and the fiber long-polling example asserts its result.
+- **[Fix]** `FiberSchedulerHelper.with_scheduler` uses `Sync` instead of a top-level `Async`, so a failed assertion
+  inside a fiber scheduler integration spec now fails the spec instead of being only logged.
+
+## 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

data/README.md

@@ -15,7 +15,7 @@ PGMQ-Ruby is a Ruby client for PGMQ (PostgreSQL Message Queue). It provides dire
 - **Like Sidekiq/Resque** - but without Redis, using PostgreSQL for both data and queues
 - **Like rdkafka-ruby** - a thin, efficient wrapper around the underlying system (PGMQ SQL functions)
 
-> **Architecture Note**: This library follows the rdkafka-ruby/Karafka pattern - `pgmq-ruby` is the low-level foundation, while higher-level features (job processing, Rails integration, retry strategies) will live in `pgmq-framework` (similar to how Karafka builds on rdkafka-ruby).
+> **Architecture Note**: This library follows the rdkafka-ruby/Karafka pattern - `pgmq-ruby` is the low-level foundation, while higher-level features (job processing, Rails integration, retry strategies, middleware) will live in `pgmq-framework` (similar to how Karafka builds on rdkafka-ruby). Like rdkafka-ruby's simple consumer, `pgmq-ruby` ships a minimal single-threaded [`PGMQ::Consumer`](#consumer) loop for one or more queues.
 
 ## Table of Contents
 
@@ -29,12 +29,14 @@ PGMQ-Ruby is a Ruby client for PGMQ (PostgreSQL Message Queue). It provides dire
   - [Sending Messages](#sending-messages)
   - [Reading Messages](#reading-messages)
   - [Grouped Reading](#grouped-reading)
+  - [Consumer](#consumer)
   - [Message Lifecycle](#message-lifecycle)
   - [Monitoring](#monitoring)
   - [Transaction Support](#transaction-support)
   - [Topic Routing](#topic-routing-amqp-like-patterns)
 - [Message Object](#message-object)
 - [Working with JSON](#working-with-json)
+- [Error Handling](#error-handling)
 - [Development](#development)
 - [Author](#author)
 
@@ -78,7 +80,7 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 | | `set_vt_batch` | Batch update visibility timeouts | ✅ |
 | | `set_vt_multi` | Update visibility timeouts across multiple queues | ✅ |
 | | `list_queues` | List all queues with metadata | ✅ |
-| | `metrics` | Get queue metrics (length, age, total messages) | ✅ |
+| | `metrics` | Get queue metrics (length, visible length, age, total messages, default partition length) | ✅ |
 | | `metrics_all` | Get metrics for all queues | ✅ |
 | | `enable_notify_insert` | Enable PostgreSQL NOTIFY on insert | ✅ |
 | | `update_notify_insert` | Update throttle interval on an existing NOTIFY trigger | ✅ |
@@ -88,13 +90,14 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 | **Ruby Enhancements** | Transaction Support | Atomic operations via `client.transaction do \|txn\|` | ✅ |
 | | Conditional Filtering | Server-side JSONB filtering with `conditional:` | ✅ |
 | | Multi-Queue Ops | Read/pop/delete/archive from multiple queues | ✅ |
+| | Consumer | Minimal single-threaded `PGMQ::Consumer` loop over one or more queues with ack on success | ✅ |
 | | Queue Validation | 48-character limit and name validation | ✅ |
 | | Connection Pooling | Thread-safe connection pool for concurrency | ✅ |
 | | Pluggable Serializers | JSON (default) with custom serializer support | ✅ |
 
 ## Requirements
 
-- Ruby 3.2+
+- Ruby 3.3+
 - PostgreSQL 14-18 with PGMQ extension installed
 
 ### Installing PGMQ Extension
@@ -371,7 +374,7 @@ misconfiguration can't silently disable retries.
 
 **Connection Pool Benefits:**
 - **Thread-safe** - Multiple threads can safely share a single client
-- **Fiber-aware** - Works with Ruby 3.0+ Fiber Scheduler for non-blocking I/O (tested with the `async` gem)
+- **Fiber-aware** - Works with the Ruby 3.3+ Fiber Scheduler for non-blocking I/O (tested with the `async` gem)
 - **Auto-reconnect** - Recovers from lost connections (configurable, extendable)
 - **Health checks** - Verifies connections before use to prevent stale connection errors
 - **Monitoring** - Track pool utilization with `client.stats`
@@ -392,6 +395,13 @@ client.create_partitioned("queue_name",
   retention_interval: "7 days"
 )  # => true/false
 
+# Pre-make more partitions ahead of the current one (default 4; PGMQ v1.13.0+)
+client.create_partitioned("queue_name",
+  partition_interval: "10000",
+  retention_interval: "100000",
+  premake: 12
+)  # => true/false
+
 # Create unlogged queue (faster, no crash recovery)
 client.create_unlogged("queue_name")  # => true/false
 
@@ -576,8 +586,8 @@ msg = client.read("queue_name", vt: 30)
 # Read batch
 messages = client.read_batch("queue_name", vt: 30, qty: 10)
 
-# Read with long-polling
-msg = client.read_with_poll("queue_name",
+# Read with long-polling (returns an Array of messages)
+messages = client.read_with_poll("queue_name",
   vt: 30,
   qty: 1,
   max_poll_seconds: 5,
@@ -586,6 +596,8 @@ msg = client.read_with_poll("queue_name",
 
 # Event-driven consumption via LISTEN/NOTIFY (more efficient than long-polling at low message rates)
 # Step 1: enable server-side NOTIFY trigger once (idempotent)
+# On PGMQ < v1.13.1, NOTIFY never fires for a queue name with uppercase letters
+# (pgmq/pgmq#593): create queues with lower-case names, or use PGMQ v1.13.1+.
 client.enable_notify_insert("queue_name")
 
 # Step 2: consumer loop — wake up on notification, then drain all available messages.
@@ -752,6 +764,57 @@ CREATE INDEX idx_orders_status
   ON pgmq.q_orders USING gin ((message->'status'));
 ```
 
+### Consumer
+
+`PGMQ::Consumer` is a minimal, single-threaded consumer loop for one or more queues, similar to the simple consumer of rdkafka-ruby. It wraps an existing client (it does not close it), long-polls with `read_with_poll` (`read_multi_with_poll` for several queues), yields one message at a time and acknowledges it on its own queue when the block returns.
+
+```ruby
+client = PGMQ::Client.new(ENV.fetch("DATABASE_URL"))
+
+consumer = PGMQ::Consumer.new(client, "orders",
+  vt: 30,               # visibility timeout (seconds) of read messages
+  batch_size: 1,        # messages read per queue per poll (still yielded one at a time)
+  max_poll_seconds: 5,  # how long one poll waits for messages
+  poll_interval_ms: 100,
+  on_success: :delete,  # or :archive
+  max_attempts: nil     # nil = retry forever; N = archive once read_ct > N (needs batch_size: 1)
+)
+
+# stop only sets a flag, so it is safe in a signal trap
+trap("TERM") { consumer.stop }
+trap("INT")  { consumer.stop }
+
+consumer.each do |message|
+  process(JSON.parse(message.message))
+end # returns after stop, once the messages already read are done
+
+client.close
+```
+
+To consume several queues (up to 50) with one consumer, pass an Array of names, like subscribing an rdkafka-ruby consumer to several topics. Every yielded message has `queue_name` set:
+
+```ruby
+consumer = PGMQ::Consumer.new(client, %w[orders emails], vt: 30)
+
+consumer.each do |message|
+  case message.queue_name
+  when "orders" then process_order(message)
+  when "emails" then send_email(message)
+  end
+end
+```
+
+Semantics:
+
+- **Acknowledgement**: when the block returns, the message is deleted (or archived with `on_success: :archive`).
+- **Errors**: when the block raises, the message is not acknowledged, the loop stops and the error is re-raised. The message becomes visible again after `vt`. Retry by calling `each` again (e.g. from a supervisor).
+- **Retry limit**: with `max_attempts: N`, a message whose `read_ct` exceeds `N` is archived without being yielded. It requires `batch_size: 1`, and with several queues one message is then read per poll: every read raises `read_ct`, so messages released after another message failed would count a read they never got.
+- **Stopping**: `stop` takes effect once the messages already read in the current poll are processed, or after the current poll (up to `max_poll_seconds`) when the queue is empty. A stopped consumer stays stopped.
+- **Batches**: when the block raises, the messages of the batch that were not yielded yet are released (`vt` set to 0) right away.
+- **Delivery**: at-least-once. If processing takes longer than `vt`, another reader may receive the same message; extend it from the block with `client.set_vt(message.queue_name, message.msg_id, vt: 30)` for long jobs.
+- **Several queues**: one `read_multi_with_poll` query reads all queues. It polls from the client (sleeping `poll_interval_ms` between reads) instead of waiting on the server like `read_with_poll`. The read order rotates every poll, so a busy queue does not starve the others.
+- **Scope**: one thread. Run one consumer per thread or process to scale; consumers can share a client, and each needs its own connection from the client's pool while polling.
+
 ### Message Lifecycle
 
 ```ruby
@@ -801,6 +864,8 @@ client.convert_archive_partitioned("queue_name",
 )
 
 # Enable PostgreSQL NOTIFY for a queue (for LISTEN-based consumers)
+# On PGMQ < v1.13.1, NOTIFY never fires for a queue name with uppercase letters
+# (pgmq/pgmq#593): create queues with lower-case names, or use PGMQ v1.13.1+.
 client.enable_notify_insert("queue_name", throttle_interval_ms: 250)
 
 # Update the throttle interval without disabling/re-enabling the trigger
@@ -834,6 +899,8 @@ puts metrics.queue_length        # => 42
 puts metrics.oldest_msg_age_sec  # => 120
 puts metrics.newest_msg_age_sec  # => 5
 puts metrics.total_messages      # => 1000
+puts metrics.queue_visible_length      # => 40 (PGMQ v1.5.0+)
+puts metrics.default_partition_length  # => nil for non-partitioned queues, 0 is healthy (PGMQ v1.13.0+)
 
 # Get all queue metrics
 all_metrics = client.metrics_all
@@ -902,6 +969,8 @@ end
 - All operations within the block execute in a single PostgreSQL transaction
 - If any operation fails, the entire transaction is rolled back automatically
 - The transactional client delegates all `PGMQ::Client` methods for convenience
+- The transactional client is bound to the thread/fiber that opened the transaction and is valid only inside the
+  block: using it from another thread or fiber, or after the block returns, raises `PGMQ::Errors::TransactionError`
 
 **Use Cases:**
 
@@ -1143,6 +1212,40 @@ msg = helper.read("orders", vt: 30)
 puts msg.data["order_id"]  # => 123
 ```
 
+## Error Handling
+
+All PGMQ-Ruby errors inherit from `PGMQ::Errors::BaseError`. When PostgreSQL rejects a call, the client raises
+`PGMQ::Errors::ConnectionError`, not only when the connection fails or is lost: a missing queue, invalid JSON or an
+invalid integer raise it too. Outside a transaction, the original `PG::Error` is in `#cause`.
+
+```ruby
+begin
+  client.produce("orders", "not json")
+rescue PGMQ::Errors::ConnectionError => e
+  e.message      # => "Database connection error: ERROR:  invalid input syntax for type json ..."
+  e.cause.class  # => PG::InvalidTextRepresentation
+end
+```
+
+Invalid arguments are rejected by a contract before they reach PostgreSQL, with a validation error:
+
+- `PGMQ::Errors::MessageInvalidError` from `produce`, `produce_batch` and `produce_batch_topic`, for example when a
+  message is not a String or its headers are neither a String nor `nil`
+- `PGMQ::Errors::MultiQueueInvalidError` from the multi-queue operations (`read_multi`, `read_multi_with_poll`,
+  `pop_multi`, `delete_multi`, `archive_multi`, `set_vt_multi`)
+- `PGMQ::Errors::AutovacuumSettingsInvalidError` from `tune_autovacuum` for an unknown storage parameter or a
+  non-numeric value
+- `PGMQ::Errors::ConfigurationError` from `PGMQ::Consumer.new` and invalid connection settings
+
+The error message names each invalid key and the reason, for example `messages.1.message` for the second message of a
+batch.
+Inside a transaction it arrives as `PGMQ::Errors::ConnectionError`, as described below.
+
+A failed `client.transaction` block, including an exception your own code raises in it, raises
+`PGMQ::Errors::ConnectionError` with the message `Transaction failed: ...`. Its `#cause` is the error raised in the
+block. For a database error that is the inner `PGMQ::Errors::ConnectionError`, so the `PG::Error` is in
+`e.cause.cause`. A `PGMQ::Errors::TransactionError` is raised unchanged.
+
 ## Development
 
 ```bash

data/config/locales/errors.yml

@@ -0,0 +1,46 @@
+en:
+  validations:
+    message:
+      missing: needs to be present
+      message_format: must be a JSON String
+      headers_format: must be a JSON String or nil
+
+    batch:
+      missing: needs to be present
+      messages_format: must be an Array
+      headers_format: must be an Array or nil
+      headers_length: must have one element per message
+
+    multi_queue:
+      queue_names_format: must be an Array
+      queue_names_empty: cannot be empty
+      queue_names_too_many: cannot exceed 50 queues
+      deletions_format: must be a Hash
+      archives_format: must be a Hash
+      updates_format: must be a Hash
+
+    consumer:
+      missing: needs to be present
+      queue_names_empty: needs at least one queue name
+      queue_names_too_many: cannot exceed 50 queues
+      queue_names_unique: must be unique (case-insensitive)
+      on_success_format: must be :delete or :archive
+      vt_format: must be a positive Integer
+      batch_size_format: must be a positive Integer
+      max_poll_seconds_format: must be a positive Integer
+      poll_interval_ms_format: must be a positive Integer
+      max_attempts_format: must be a positive Integer or nil
+      max_attempts_batch_size: "requires batch_size: 1"
+
+    autovacuum:
+      missing: needs to be present
+      queue_settings_format: must contain only known storage parameters
+      archive_settings_format: must contain only known storage parameters
+      queue_settings_values: must contain only numeric values
+      archive_settings_values: must contain only numeric values
+
+    connection:
+      conn_params_empty: are required
+      conn_params_format: must be a connection String, a non-empty Hash or a callable
+      reconnectable_error_patterns_format: must contain Strings or Regexps
+      reconnectable_error_classes_format: must contain Exception subclasses

data/lib/pgmq/client/autovacuum.rb

@@ -42,12 +42,10 @@ module PGMQ
         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
+      # Validates the storage settings before they are interpolated into SQL
+      CONTRACT = Contracts::Autovacuum.new
+
+      private_constant :CONTRACT
 
       # Tunes autovacuum and storage parameters on a queue's underlying tables.
       #
@@ -64,6 +62,8 @@ module PGMQ
       # @param archive_settings [Hash{Symbol=>Numeric}] storage params for the archive table, merged onto
       #   {DEFAULT_ARCHIVE_SETTINGS}
       # @return [void]
+      # @raise [PGMQ::Errors::AutovacuumSettingsInvalidError] if queue_settings or archive_settings has an unknown
+      #   storage parameter or a value that is not numeric
       # @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)
       #
@@ -109,11 +109,19 @@ module PGMQ
       # @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)))
+        queue_settings = symbolize(queue_settings)
+        archive_settings = symbolize(archive_settings)
+
+        CONTRACT.validate!(
+          { queue_settings: queue_settings, archive_settings: archive_settings },
+          Errors::AutovacuumSettingsInvalidError
+        )
+
+        alter_storage(conn, "q_#{queue_name}", DEFAULT_QUEUE_SETTINGS.merge(queue_settings))
 
         return unless archive
 
-        alter_storage(conn, "a_#{queue_name}", DEFAULT_ARCHIVE_SETTINGS.merge(symbolize(archive_settings)))
+        alter_storage(conn, "a_#{queue_name}", DEFAULT_ARCHIVE_SETTINGS.merge(archive_settings))
       end
 
       # Issues a single ALTER TABLE setting the given storage parameters on one pgmq table.
@@ -125,8 +133,8 @@ module PGMQ
       #
       # 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.
+      # parameter names and values are validated by {PGMQ::Contracts::Autovacuum}; 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")
@@ -134,38 +142,19 @@ module PGMQ
       # @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(", ")
+        clause = settings.map { |key, value| "#{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.
+      # Coerces a setting value to its SQL form: Float for scale factors, Integer for everything else.
+      # {PGMQ::Contracts::Autovacuum} has already rejected values that do not coerce.
       #
       # @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)
+        Contracts::Autovacuum::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.

data/lib/pgmq/client/consumer.rb

@@ -17,7 +17,7 @@ module PGMQ
       # @example
       #   msg = client.read("orders", vt: 30)
       #   if msg
-      #     process(msg.payload)
+      #     process(msg.message)
       #     client.delete("orders", msg.msg_id)
       #   end
       #
@@ -60,7 +60,7 @@ module PGMQ
       # @example
       #   messages = client.read_batch("orders", vt: 30, qty: 10)
       #   messages.each do |msg|
-      #     process(msg.payload)
+      #     process(msg.message)
       #     client.delete("orders", msg.msg_id)
       #   end
       #
@@ -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

@@ -41,6 +41,9 @@ module PGMQ
       #
       # @example Disable throttling (notify on every insert)
       #   client.enable_notify_insert("orders", throttle_interval_ms: 0)
+      # @note On PGMQ older than v1.13.1, notifications never fire for a queue name with uppercase letters
+      #   (pgmq/pgmq#593). The call succeeds, but no NOTIFY is sent. Create the queue with a lower-case name, or use
+      #   PGMQ v1.13.1+.
       def enable_notify_insert(queue_name, throttle_interval_ms: 250)
         validate_queue_name!(queue_name)
 
@@ -66,10 +69,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 +86,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 +187,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 +204,11 @@ 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.
+      # @note On PGMQ older than v1.13.1, no notification arrives for a queue name with uppercase letters
+      #   (pgmq/pgmq#593), so this method never returns a notification. Create the queue with a lower-case name,
+      #   or use PGMQ v1.13.1+.
       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/message_lifecycle.rb

@@ -14,7 +14,7 @@ module PGMQ
       #
       # @example
       #   msg = client.pop("orders")
-      #   process(msg.payload) if msg
+      #   process(msg.message) if msg
       def pop(queue_name)
         validate_queue_name!(queue_name)
 
@@ -35,7 +35,7 @@ module PGMQ
       #
       # @example Pop up to 10 messages
       #   messages = client.pop_batch("orders", 10)
-      #   messages.each { |msg| process(msg.payload) }
+      #   messages.each { |msg| process(msg.message) }
       def pop_batch(queue_name, qty)
         validate_queue_name!(queue_name)
         return [] if qty <= 0
@@ -109,6 +109,7 @@ module PGMQ
       #
       # @param deletions [Hash] hash of queue_name => array of msg_ids
       # @return [Hash] hash of queue_name => array of deleted msg_ids
+      # @raise [PGMQ::Errors::MultiQueueInvalidError] if deletions is not a Hash
       #
       # @example Delete messages from multiple queues
       #   client.delete_multi({
@@ -123,7 +124,7 @@ module PGMQ
       #   deletions = messages.group_by(&:queue_name).transform_values { |mss| mss.map(&:msg_id) }
       #   client.delete_multi(deletions)
       def delete_multi(deletions)
-        raise ArgumentError, "deletions must be a hash" unless deletions.is_a?(Hash)
+        MULTI_QUEUE_CONTRACT.validate!({ deletions: deletions }, Errors::MultiQueueInvalidError)
         return {} if deletions.empty?
 
         # Validate all queue names
@@ -202,6 +203,7 @@ module PGMQ
       #
       # @param archives [Hash] hash of queue_name => array of msg_ids
       # @return [Hash] hash of queue_name => array of archived msg_ids
+      # @raise [PGMQ::Errors::MultiQueueInvalidError] if archives is not a Hash
       #
       # @example Archive messages from multiple queues
       #   client.archive_multi({
@@ -209,7 +211,7 @@ module PGMQ
       #     'notifications' => [5]
       #   })
       def archive_multi(archives)
-        raise ArgumentError, "archives must be a hash" unless archives.is_a?(Hash)
+        MULTI_QUEUE_CONTRACT.validate!({ archives: archives }, Errors::MultiQueueInvalidError)
         return {} if archives.empty?
 
         # Validate all queue names
@@ -317,6 +319,7 @@ module PGMQ
       # @param updates [Hash] hash of queue_name => array of msg_ids
       # @param vt [Integer, Time] visibility timeout as seconds offset or absolute timestamp
       # @return [Hash] hash of queue_name => array of updated PGMQ::Message objects
+      # @raise [PGMQ::Errors::MultiQueueInvalidError] if updates is not a Hash
       #
       # @example Extend visibility timeout for messages from multiple queues
       #   client.set_vt_multi({
@@ -334,7 +337,7 @@ module PGMQ
       #   updates = messages.group_by(&:queue_name).transform_values { |msgs| msgs.map(&:msg_id) }
       #   client.set_vt_multi(updates, vt: 120)
       def set_vt_multi(updates, vt:)
-        raise ArgumentError, "updates must be a hash" unless updates.is_a?(Hash)
+        MULTI_QUEUE_CONTRACT.validate!({ updates: updates }, Errors::MultiQueueInvalidError)
         return {} if updates.empty?
 
         # Validate all queue names