pgmq-ruby 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bad592ec19aca0b0437ef08ef6cbcb8ecdb2f9155ddbc27196ef00e8b10b22ce
-  data.tar.gz: 8220e5b37d111f10afb169100c7a7d45231a19f7b6b31880b200a744abb427b5
+  metadata.gz: ee008476f444de984ef7413b21bee87043d9e5e87a7eabf85a934cf74b147225
+  data.tar.gz: 1dd10b9b77c9dc4109f6a8e779c970fc6f7ee2e4880cecb467ab3060ecc4f571
 SHA512:
-  metadata.gz: c9236e3bba26ee065dcc21d87f945ff2a71439695202322fef2e1c87502b91e655e73d7cc498084109b75023073e56bcca060bf4f4da45fd403bfaa25c802049
-  data.tar.gz: f9c94727f9839d0cffad5928147015e90801ec41eeb3e32b4577fb8743da9891d5e2dc9cce622d3308853ac44abd15076d085165f56e6785c420752a2e8d56dd
+  metadata.gz: 32cc154c5df5d6501de5bf93daf32857448645b9fe5071bec84b51dbda86cf0efd1fe6cddfd24707fda8201e7d6b8fb10c02f3c7e2bf108226b50a4cbe1b65fd
+  data.tar.gz: ad2630d6736bc49490ccb2eec83da4878dd4b349e9e06cd12f5d9f62a10109922a379c0dab43aa5a0c8a3f33241ca71f6c6ba24386cc6a7cf097db1397ef2518

data/CHANGELOG.md

@@ -1,6 +1,101 @@
 # Changelog
 
-## Unreleased
+## 0.7.0 (2026-06-15)
+
+### Queue Naming
+- **[Feature]** Add `PGMQ::QueueName`, a module that is now the single source of truth for queue-name rules and
+  exposes tiers for deriving valid names from less-trusted input:
+  - `PGMQ::QueueName.valid?(name)` / `PGMQ::QueueName.validate!(name)` - the existing strict check (used internally
+    by every `PGMQ::Client` operation); `validate!` returns the name when valid and raises
+    `PGMQ::Errors::InvalidQueueNameError` otherwise.
+  - `PGMQ::QueueName.normalize(name)` - rewrites a name meant to be valid but using friendly separators. Maps
+    hyphens, dots, and colons to underscores, strips any *other* invalid character (so `"a@b"` → `"ab"`, not
+    `"a_b"`), then validates - e.g. a Turbo Stream channel `"chat:room-7"` → `"chat_room_7"`. Raises if the result
+    still can't be valid (empty, or starts with a digit). Colons map to underscores (rather than being stripped) so
+    distinct turbo-rails stream names don't collide on one queue.
+  - `PGMQ::QueueName.sanitize!(name)` - strips every invalid character then validates; raises
+    `InvalidQueueNameError` if nothing valid remains. A SQL-identifier guard for untrusted input: the result is
+    always either a name you know is safe or an exception, never a silent substitute.
+  - `PGMQ::QueueName.sanitize(name)` - the lenient sibling of `sanitize!`: best-effort coercion that never raises for
+    content (lowercases, replaces illegal runs, prefixes leading digits, truncates to the length limit, falls back
+    to `"queue"`). Convenient, but distinct inputs can map to the same name, so prefer `sanitize!` for untrusted
+    input.
+
+  `PGMQ::Client#validate_queue_name!` now delegates to `PGMQ::QueueName.validate!`; error messages are unchanged.
+### Connection Management
+- **[Feature]** `PGMQ::Client#with_connection` is now public. Every PGMQ operation already checks
+  out a pooled, health-checked connection through this method; exposing it lets callers run
+  PostgreSQL statements PGMQ does not wrap (ad-hoc `NOTIFY`/`LISTEN`, advisory locks, custom
+  monitoring queries, DDL alongside queue tables) on the same pool instead of standing up a second
+  one. The yielded object is the raw `PG::Connection` (no type mapping, no implicit transaction);
+  use `client.transaction` when atomicity is required.
+
+### Queue Maintenance
+- **[Feature]** Add `list_notify_insert_throttles` — returns an array of `PGMQ::NotifyThrottle`
+  objects (one per queue with NOTIFY enabled), each carrying `queue_name`, `throttle_interval_ms`,
+  and `last_notified_at`. Useful for auditing notification configuration across all queues.
+  Requires PGMQ v1.11.0+.
+- **[Feature]** Add `update_notify_insert(queue_name, throttle_interval_ms:)` — updates the NOTIFY
+  throttle interval on an already-enabled trigger without having to disable and re-enable it.
+  Requires PGMQ v1.11.0+.
+- **[Feature]** Add `wait_for_notify(queue_name, timeout: nil)` — thin wrapper around PostgreSQL `LISTEN/NOTIFY`
+  for event-driven message consumption. Blocks until the queue's NOTIFY channel (`pgmq.q_<queue>.INSERT`) fires or the
+  timeout expires, then issues `UNLISTEN` and returns the connection to the pool. Unlike `read_with_poll`, which
+  holds a connection open inside a PL/pgSQL loop for the full poll window, `wait_for_notify` releases the
+  connection the moment the notification arrives — more efficient under low message rates. Requires
+  `enable_notify_insert` to be called first to attach the server-side trigger.
+- **[Feature]** Add `convert_archive_partitioned(queue_name, partition_interval:, retention_interval:,
+  leading_partition:)` - 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. Idempotent: returns without error if the archive table is
+  already partitioned or does not exist. Requires the `pg_partman` PostgreSQL extension.
+
+### Queue Management
+- **[Feature]** Add `create_fifo_index(queue_name)` - creates the FIFO index on a queue's underlying table required
+  for correct ordering and acceptable performance with grouped read operations (`read_grouped`, `read_grouped_rr`,
+  `read_grouped_head`). The operation is idempotent.
+- **[Feature]** Add `create_fifo_indexes_all` - convenience wrapper that creates FIFO indexes on every queue
+  registered in `pgmq.meta`. Useful for one-time migrations when adding grouped reads to an existing deployment.
+- **[Feature]** Add `tune_autovacuum(queue_name, queue_settings:, archive:, archive_settings:)` - sets per-table
+  autovacuum and storage parameters on a queue's tables (`pgmq.q_<name>` and, unless `archive: false`,
+  `pgmq.a_<name>`) via `ALTER TABLE`. PGMQ tables churn under constant insert/update/delete (every read UPDATEs
+  `vt`/`read_ct`/`last_read_at`), so PostgreSQL's defaults (`autovacuum_vacuum_scale_factor` 0.2, `fillfactor` 100)
+  let dead tuples and index/page bloat accumulate before autovacuum runs. The tuned defaults set, on the queue
+  table: `autovacuum_vacuum_scale_factor 0.01`, `autovacuum_vacuum_threshold 50`, `autovacuum_vacuum_cost_delay 2`,
+  `autovacuum_analyze_scale_factor 0.05`, and `fillfactor 70` (the indexed per-read UPDATE is not HOT-eligible, so
+  page headroom helps); and on the archive table the same minus `fillfactor` (append-only) with `cost_delay 5`.
+  Pass `queue_settings:`/`archive_settings:` Hashes to override individual parameters (merged onto the defaults).
+  Parameter names are allow-listed and values coerced (`Float`/`Integer`); the table name is quoted (`quote_ident`)
+  and lower-cased to match PGMQ's table naming. Opt-in: the gem does not change storage parameters unless asked.
+- **[Feature]** `create`, `create_unlogged`, and `create_partitioned` accept a `tune_autovacuum:` keyword. Pass
+  `true` to apply the tuned defaults to the new queue's tables, or a Hash of the `tune_autovacuum` keyword options.
+  Defaults to `false` (no change), preserving the thin-wrapper behaviour.
+
+### Message Operations
+- **[Enhancement]** Add Ruby warning category opt-in to test helpers
+- **[Feature]** Add `read_grouped_head(queue_name, vt:, qty:)` - reads exactly one message (the
+  oldest visible) from each distinct FIFO group, up to `qty` groups. Groups are identified by the
+  `x-pgmq-group` key in message headers (set via `headers:` on `produce`); messages without that
+  header all share one implicit default group. Unlike `read_grouped` (which groups by the first
+  payload key and drains one group fully before moving on), `read_grouped_head` surfaces the
+  leading edge of every group in a single call - ideal for detecting head-of-line stalls or
+  building per-group progress dashboards. Requires PGMQ v1.11.1+.
+- **[Feature]** Add SQS-style grouped reading:
+  - `read_grouped(queue_name, vt:, qty:)` - reads messages grouped by the first JSON key,
+    filling the batch from the oldest group first (throughput-optimised). Contrast with
+    `read_grouped_rr` which interleaves groups fairly.
+  - `read_grouped_with_poll(queue_name, vt:, qty:, max_poll_seconds:, poll_interval_ms:)` -
+    same strategy with long-polling support.
+
+  Use `read_grouped` when maximising throughput matters more than fairness across groups
+  (e.g. a single tenant has a burst of work). Use `read_grouped_rr` when you need to
+  prevent any one group from monopolising workers.
+- **[Feature]** `produce`, `produce_batch`, and `produce_batch_topic` now accept an absolute `Time`
+  object for the `delay:` parameter in addition to an integer number of seconds. This mirrors the
+  existing `set_vt` behaviour and maps to the `timestamptz` overloads added in PGMQ v1.10.0.
+  Pass `delay: Time.now + 3600` to schedule a message to become visible at a specific wall-clock
+  time. Note: `produce_topic` does not support `Time` delay because the upstream `pgmq.send_topic`
+  SQL function does not yet have a `timestamptz` overload.
 
 ## 0.6.2 (2026-05-08)
 
@@ -26,7 +121,7 @@
 ### Infrastructure
 - **[Change]** Migrate test framework from RSpec to Minitest/Spec with Mocha for mocking, aligning with the broader Karafka ecosystem conventions.
 - **[Change]** Replace `rubocop-rspec` with `rubocop-minitest` for test linting.
-- **[Change]** Add `bin/integrations` runner script that centralizes integration spec execution. Specs no longer need `require_relative "support/example_helper"` — the runner injects it via `-r` flag. Run all specs with `bin/integrations` or specific ones with `bin/integrations spec/integration/foo_spec.rb`.
+- **[Change]** Add `bin/integrations` runner script that centralizes integration spec execution. Specs no longer need `require_relative "support/example_helper"` - the runner injects it via `-r` flag. Run all specs with `bin/integrations` or specific ones with `bin/integrations spec/integration/foo_spec.rb`.
 
 ## 0.5.0 (2026-02-24)
 

data/README.md

@@ -28,7 +28,7 @@ PGMQ-Ruby is a Ruby client for PGMQ (PostgreSQL Message Queue). It provides dire
   - [Queue Management](#queue-management)
   - [Sending Messages](#sending-messages)
   - [Reading Messages](#reading-messages)
-  - [Grouped Round-Robin Reading](#grouped-round-robin-reading)
+  - [Grouped Reading](#grouped-reading)
   - [Message Lifecycle](#message-lifecycle)
   - [Monitoring](#monitoring)
   - [Transaction Support](#transaction-support)
@@ -49,8 +49,11 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 | **Reading** | `read` | Read single message with visibility timeout | ✅ |
 | | `read_batch` | Read multiple messages with visibility timeout | ✅ |
 | | `read_with_poll` | Long-polling for efficient message consumption | ✅ |
+| | `read_grouped` | SQS-style throughput-first grouped reading | ✅ |
+| | `read_grouped_with_poll` | Throughput-first grouped reading with long-polling | ✅ |
 | | `read_grouped_rr` | Round-robin reading across message groups | ✅ |
 | | `read_grouped_rr_with_poll` | Round-robin with long-polling | ✅ |
+| | `read_grouped_head` | One message per FIFO group from the head of each group | ✅ |
 | | `pop` | Atomic read + delete operation | ✅ |
 | | `pop_batch` | Atomic batch read + delete operation | ✅ |
 | **Deleting/Archiving** | `delete` | Delete single message | ✅ |
@@ -58,9 +61,12 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 | | `archive` | Archive single message for long-term storage | ✅ |
 | | `archive_batch` | Archive multiple messages | ✅ |
 | | `purge_queue` | Remove all messages from queue | ✅ |
+| | `convert_archive_partitioned` | Convert archive table to pg_partman-managed partitions | ✅ |
 | **Queue Management** | `create` | Create standard queue | ✅ |
 | | `create_partitioned` | Create partitioned queue (requires pg_partman) | ✅ |
 | | `create_unlogged` | Create unlogged queue (faster, no crash recovery) | ✅ |
+| | `create_fifo_index` | Create FIFO index required for grouped reads | ✅ |
+| | `create_fifo_indexes_all` | Create FIFO indexes on all existing queues | ✅ |
 | | `drop_queue` | Delete queue and all messages | ✅ |
 | **Topic Routing** | `bind_topic` | Bind topic pattern to queue (AMQP-like) | ✅ |
 | | `unbind_topic` | Remove topic binding | ✅ |
@@ -75,7 +81,10 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 | | `metrics` | Get queue metrics (length, age, total messages) | ✅ |
 | | `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 | ✅ |
 | | `disable_notify_insert` | Disable notifications | ✅ |
+| | `list_notify_insert_throttles` | List all queues with NOTIFY enabled and their throttle config | ✅ |
+| | `wait_for_notify` | Block until a NOTIFY arrives on the queue's channel | ✅ |
 | **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 | ✅ |
@@ -290,6 +299,42 @@ client = PGMQ::Client.new(
 )
 ```
 
+#### Running custom SQL on the PGMQ pool
+
+Every PGMQ operation checks out a pooled connection through `client.with_connection`.
+The method is public, so you can run PostgreSQL statements PGMQ does not wrap
+without standing up a second connection pool. The connection is health-checked
+(when `auto_reconnect` is enabled) and returned to the pool when the block exits.
+
+```ruby
+# Fire a custom NOTIFY alongside your queues
+client.with_connection do |conn|
+  conn.exec_params("SELECT pg_notify($1, $2)", ["my_channel", payload])
+end
+
+# Run a monitoring query PGMQ does not wrap
+depth = client.with_connection do |conn|
+  conn.exec("SELECT count(*) FROM pgmq.q_orders")[0]["count"].to_i
+end
+```
+
+You receive the raw `PG::Connection`: results come back as strings (no type
+mapping) and the statement is **not** wrapped in a transaction. Use
+[`client.transaction`](#transaction-support) when you need atomicity.
+
+> **Pool-safety caveats.** You're handed a *pooled* connection, so two rules apply:
+>
+> 1. **Don't keep the connection past 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 — using it afterwards can corrupt libpq
+>    state (nil results, wrong data, segfaults).
+> 2. **Clean up session state before the block exits.** The pool does *not* reset
+>    connections on check-in. A `LISTEN`, `SET`, session-level advisory lock
+>    (`pg_advisory_lock`), prepared statement, or temp table you create survives
+>    and leaks to the next pool user. Undo it (`UNLISTEN`, `RESET`,
+>    `pg_advisory_unlock`, …) before returning. For LISTEN/NOTIFY consumption,
+>    prefer `client.wait_for_notify`, which manages `LISTEN`/`UNLISTEN` for you.
+
 #### Extending the lost-connection error matchers
 
 PGMQ-Ruby ships with a curated list of `PG::Error` messages and classes
@@ -312,7 +357,7 @@ PGMQ::Connection.reconnectable_error_patterns = [
 PGMQ::Connection.reconnectable_error_classes = [PG::ConnectionRefused]
 ```
 
-The built-in defaults are always kept — your patterns and classes are
+The built-in defaults are always kept - your patterns and classes are
 appended to them. Configuration errors (e.g. passing an Integer as a
 pattern) raise `PGMQ::Errors::ConfigurationError` immediately so
 misconfiguration can't silently disable retries.
@@ -320,7 +365,7 @@ misconfiguration can't silently disable retries.
 > **Reserve these options for connection-level failures.** A "reconnectable"
 > error means the socket is dead and a retry on a fresh connection is safe.
 > Do **not** add patterns or classes for query-level errors (deadlocks,
-> constraint violations, statement timeouts) — those will replay your
+> constraint violations, statement timeouts) - those will replay your
 > operation against a healthy connection and may cause duplicate work or
 > mask bugs.
 
@@ -350,9 +395,19 @@ client.create_partitioned("queue_name",
 # Create unlogged queue (faster, no crash recovery)
 client.create_unlogged("queue_name")  # => true/false
 
+# Create a queue with autovacuum tuned for PGMQ's read+delete churn (see "Autovacuum Tuning")
+client.create("queue_name", tune_autovacuum: true)
+
 # Drop queue (returns true if dropped, false if didn't exist)
 client.drop_queue("queue_name")  # => true/false
 
+# Create the FIFO index required for grouped reads (read_grouped, read_grouped_rr, read_grouped_head)
+# Idempotent - safe to call on a queue that already has the index
+client.create_fifo_index("queue_name")
+
+# Create FIFO indexes for all existing queues at once (useful for migrating an existing deployment)
+client.create_fifo_indexes_all
+
 # List all queues
 queues = client.list_queues
 # => [#<PGMQ::QueueMetadata queue_name="orders" created_at=...>, ...]
@@ -387,6 +442,98 @@ client.create("a" * 48)          # ✗ Too long (48+ chars)
 # Raises PGMQ::Errors::InvalidQueueNameError
 ```
 
+**Deriving valid names with `PGMQ::QueueName`**
+
+`PGMQ::Client` always validates the name you pass (via `PGMQ::QueueName.validate!`).
+When the name comes from a friendlier source — a Turbo Stream channel, a slug, or
+untrusted user input — `PGMQ::QueueName` gives you a few tiers so you can decide
+how strict to be:
+
+```ruby
+# Tier 1 — assert a name you control is valid (raises otherwise)
+PGMQ::QueueName.valid?("orders")          # => true
+PGMQ::QueueName.validate!("my-queue")     # => raises PGMQ::Errors::InvalidQueueNameError
+
+# Tier 2 — normalize a name meant to be valid but using friendly separators.
+# Hyphens/dots/colons become underscores; any OTHER invalid char is stripped;
+# raises if the result still can't be valid (empty, or starts with a digit).
+PGMQ::QueueName.normalize("chat:room-7")  # => "chat_room_7"
+PGMQ::QueueName.normalize("order.events") # => "order_events"
+PGMQ::QueueName.normalize("a@b")          # => "ab"   (the "@" is dropped, not turned into "_")
+PGMQ::QueueName.normalize("123-go")       # => raises (starts with a digit)
+
+# Tier 3 — sanitize! untrusted input: strip every invalid char, then validate.
+# Raises rather than substituting, so it never silently points at a different
+# queue. Use this as a SQL-identifier guard for untrusted input.
+PGMQ::QueueName.sanitize!("orders!!")     # => "orders"
+PGMQ::QueueName.sanitize!("!!!")          # => raises PGMQ::Errors::InvalidQueueNameError
+
+# Tier 3 (lenient) — sanitize never raises; always returns a valid name (prefixes
+# leading digits, truncates to length, falls back to "queue"). Convenient, but
+# distinct inputs can map to the SAME name, so prefer sanitize! for untrusted input.
+PGMQ::QueueName.sanitize("99 Problems!")  # => "q_99_problems"
+PGMQ::QueueName.sanitize("!!!")           # => "queue"
+
+client.create(PGMQ::QueueName.sanitize!(params[:topic]))  # raises on junk rather than guessing
+```
+
+#### Autovacuum Tuning
+
+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:
+
+- `autovacuum_vacuum_scale_factor` defaults to `0.2`, so autovacuum only runs
+  once 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.
+
+`tune_autovacuum` sets 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 **opt-in**
+— the gem never mutates storage parameters unless you ask.
+
+The tuned defaults:
+
+| Parameter | Queue table (`pgmq.q_…`) | Archive table (`pgmq.a_…`) |
+|-----------|--------------------------|----------------------------|
+| `autovacuum_vacuum_scale_factor`  | `0.01` | `0.05` |
+| `autovacuum_vacuum_threshold`     | `50`   | `50`   |
+| `autovacuum_vacuum_cost_delay`    | `2`    | `5`    |
+| `autovacuum_analyze_scale_factor` | `0.05` | `0.05` |
+| `fillfactor`                      | `70`   | — (append-only, not set) |
+
+```ruby
+# Tune an existing queue with the PGMQ-tuned defaults above
+client.tune_autovacuum("orders")
+
+# Override individual parameters (merged onto the defaults) and skip the archive
+client.tune_autovacuum("orders",
+  queue_settings: { autovacuum_vacuum_scale_factor: 0.005, fillfactor: 80 },
+  archive: false)
+
+# Override an archive parameter only
+client.tune_autovacuum("orders", archive_settings: { autovacuum_vacuum_scale_factor: 0.02 })
+
+# Or tune at creation time (true = defaults, or a Hash of the keywords above)
+client.create("orders", tune_autovacuum: true)
+client.create("orders", tune_autovacuum: { queue_settings: { fillfactor: 80 }, archive: false })
+client.create_unlogged("fast", tune_autovacuum: true)
+client.create_partitioned("big", partition_interval: "daily",
+  retention_interval: "7 days", tune_autovacuum: true)
+```
+
+Only parameters you name in `queue_settings:` / `archive_settings:` change; the
+rest keep the tuned defaults. Values are coerced (`Float`/`Integer`) and
+parameter names are allow-listed before they reach the `ALTER TABLE`.
+
+> **Partitioned queues:** parameters are set on the partitioned *parent* table.
+> PostgreSQL does not cascade storage parameters to existing partitions, so set
+> them per-partition if you need to retune already-created partitions.
+
 ### Sending Messages
 
 ```ruby
@@ -437,12 +584,38 @@ msg = client.read_with_poll("queue_name",
   poll_interval_ms: 100
 )
 
+# Event-driven consumption via LISTEN/NOTIFY (more efficient than long-polling at low message rates)
+# Step 1: enable server-side NOTIFY trigger once (idempotent)
+client.enable_notify_insert("queue_name")
+
+# Step 2: consumer loop — wake up on notification, then drain all available messages.
+# With throttling (default 250ms), a burst of inserts fires only one NOTIFY.
+# Always use read_batch after waking up to avoid leaving messages stranded.
+loop do
+  next unless client.wait_for_notify("queue_name", timeout: 5)
+
+  msgs = client.read_batch("queue_name", vt: 30, qty: 10)
+  msgs.each { |m| process(m); client.delete("queue_name", m.msg_id) }
+end
+
 # Pop (atomic read + delete)
 msg = client.pop("queue_name")
 
 # Pop batch (atomic read + delete for multiple messages)
 messages = client.pop_batch("queue_name", 10)
 
+# SQS-style grouped reading (throughput-first: drains oldest group before moving on)
+# Messages grouped by first key in their JSON payload
+messages = client.read_grouped("queue_name", vt: 30, qty: 10)
+
+# Throughput-first grouped reading with long-polling
+messages = client.read_grouped_with_poll("queue_name",
+  vt: 30,
+  qty: 10,
+  max_poll_seconds: 5,
+  poll_interval_ms: 100
+)
+
 # Grouped round-robin reading (fair processing across entities)
 # Messages are grouped by the first key in their JSON payload
 messages = client.read_grouped_rr("queue_name", vt: 30, qty: 10)
@@ -454,38 +627,82 @@ messages = client.read_grouped_rr_with_poll("queue_name",
   max_poll_seconds: 5,
   poll_interval_ms: 100
 )
+
+# Read one message per FIFO group from the head of each group
+# Groups are set via x-pgmq-group header (requires PGMQ v1.11.1+)
+client.produce("queue_name", '{"job":"a"}', headers: '{"x-pgmq-group":"tenant_a"}')
+client.produce("queue_name", '{"job":"b"}', headers: '{"x-pgmq-group":"tenant_b"}')
+messages = client.read_grouped_head("queue_name", vt: 30, qty: 10)
+# => one message from tenant_a and one from tenant_b
 ```
 
-#### Grouped Round-Robin Reading
+#### Grouped Reading
 
-When processing messages from multiple entities (users, orders, tenants), regular FIFO ordering can cause starvation - one entity with many messages can monopolize workers.
+PGMQ provides three grouped-reading strategies for processing messages from multiple entities (users, tenants, orders). All three group by the **first key** in the JSON payload (except `read_grouped_head`, which uses the `x-pgmq-group` message header).
 
-Grouped round-robin ensures fair processing by interleaving messages from different groups:
+##### Throughput-First (`read_grouped` / `read_grouped_with_poll`)
+
+Drains the oldest group completely before moving to the next. Best when maximising throughput matters more than fairness:
 
 ```ruby
-# Queue contains messages for different users:
-# user_a: 5 messages, user_b: 2 messages, user_c: 1 message
+# Queue: user_a has 3 messages, user_b has 1
+messages = client.read_grouped("tasks", vt: 30, qty: 3)
+# => [user_a_1, user_a_2, user_a_3]  - drains user_a first
+
+# With long-polling (waits up to max_poll_seconds if queue is empty)
+messages = client.read_grouped_with_poll("tasks",
+  vt: 30,
+  qty: 10,
+  max_poll_seconds: 5,
+  poll_interval_ms: 100
+)
+```
+
+##### Round-Robin (`read_grouped_rr` / `read_grouped_rr_with_poll`)
 
-# Regular read would process all user_a messages first (unfair)
-messages = client.read_batch("tasks", vt: 30, qty: 8)
-# => [user_a_1, user_a_2, user_a_3, user_a_4, user_a_5, user_b_1, user_b_2, user_c_1]
+Interleaves one message per group on each pass. Best for fairness - prevents any single entity from monopolising workers:
 
-# Grouped round-robin ensures fair distribution
+```ruby
+# Queue: user_a: 5 messages, user_b: 2, user_c: 1
 messages = client.read_grouped_rr("tasks", vt: 30, qty: 8)
 # => [user_a_1, user_b_1, user_c_1, user_a_2, user_b_2, user_a_3, user_a_4, user_a_5]
-```
 
-**How it works:**
-- Messages are grouped by the **first key** in their JSON payload
-- The first key should be your grouping identifier (e.g., `user_id`, `tenant_id`, `order_id`)
-- PGMQ rotates through groups, taking one message from each before repeating
+# With long-polling
+messages = client.read_grouped_rr_with_poll("tasks",
+  vt: 30,
+  qty: 10,
+  max_poll_seconds: 5,
+  poll_interval_ms: 100
+)
+```
 
-**Message format for grouping:**
+**Message format for payload-based grouping** (used by `read_grouped` and `read_grouped_rr`):
 ```ruby
-# Good - user_id is first key, used for grouping
+# user_id is first key - PGMQ uses it as the group identifier
 client.produce("tasks", '{"user_id":"user_a","task":"process"}')
+```
+
+##### Head-of-Group (`read_grouped_head`) - PGMQ v1.11.1+
+
+Returns the oldest visible message from each FIFO group, up to `qty` groups. Groups are identified by the `x-pgmq-group` key in the message **headers**. Messages without that header all share one implicit default group.
 
-# The grouping key should come first in your JSON
+Useful for detecting head-of-line stalls or building per-group progress dashboards - one call surfaces the leading edge of every group simultaneously:
+
+```ruby
+# Produce with x-pgmq-group headers
+client.produce("jobs", '{"task":"build"}', headers: '{"x-pgmq-group":"tenant_a"}')
+client.produce("jobs", '{"task":"build"}', headers: '{"x-pgmq-group":"tenant_a"}')
+client.produce("jobs", '{"task":"test"}',  headers: '{"x-pgmq-group":"tenant_b"}')
+
+# Returns one message per group (oldest from each)
+messages = client.read_grouped_head("jobs", vt: 30, qty: 100)
+# => [tenant_a oldest msg, tenant_b oldest msg]
+
+# Check for stuck groups
+messages.each do |msg|
+  group = JSON.parse(msg.headers)["x-pgmq-group"]
+  puts "#{group} head enqueued at #{msg.enqueued_at}"
+end
 ```
 
 #### Conditional Message Filtering
@@ -572,11 +789,40 @@ client.set_vt_multi({
 # Purge all messages
 count = client.purge_queue("queue_name")
 
+# Convert a standard queue's archive table to pg_partman-managed partitions (requires pg_partman)
+# Useful for queues created with `create`/`create_unlogged` whose archives have grown large.
+# Idempotent - safe to call if the archive is already partitioned or doesn't exist yet.
+client.convert_archive_partitioned("queue_name")
+
+# Custom partition/retention intervals (same syntax as create_partitioned)
+client.convert_archive_partitioned("queue_name",
+  partition_interval: "daily",
+  retention_interval: "30 days"
+)
+
 # Enable PostgreSQL NOTIFY for a queue (for LISTEN-based consumers)
 client.enable_notify_insert("queue_name", throttle_interval_ms: 250)
 
+# Update the throttle interval without disabling/re-enabling the trigger
+client.update_notify_insert("queue_name", throttle_interval_ms: 100)
+
+# List all queues with NOTIFY enabled and their current throttle 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
+
 # Disable notifications
 client.disable_notify_insert("queue_name")
+
+# Block until a NOTIFY arrives on the queue's channel (or timeout expires)
+# Returns the payload string on notification, nil on timeout
+client.wait_for_notify("queue_name", timeout: 5)
+
+# Block form — inspect notification metadata
+client.wait_for_notify("queue_name", timeout: 5) do |channel, pid, payload|
+  puts "Notified on #{channel} by backend #{pid}"
+end
 ```
 
 ### Monitoring