pgmq-ruby 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6b6b3dcddd3785167a0fd8482fb0900f0d51c9c5cf68ddd23b60e84eb306012
-  data.tar.gz: 94604bf7c55a2bd62a63486278641c247b0a9d9cf3b50379d30ee0b7c8c840f4
+  metadata.gz: 812f7254909aa9125fa79b5304cb3fad8461cce5372dd02206c7cfdf9b99afa9
+  data.tar.gz: 754f398b518800546fa2c2fe2bbaf3a3d3eb742ca5c162d9c89cd1415ac40a57
 SHA512:
-  metadata.gz: 3ea99c27e92f96f137c9552985830949cdff6538409646ddf6b10e587c05c2b831c8c083570996ff2c0ffbefd09ae01fa84002e2ca9093f0a27ec6f7387a2b59
-  data.tar.gz: 437713bad4d37ff821487493097c6229b8c2069b260b74e587b3452f74508392b1dba7cf37ee3dd91c52143a4c147db373035351a8dc0d86f1d6cd70a4370d4d
+  metadata.gz: 40b65d9001f469d2e88c04cc5f4bcf85b234b850a19ee4089e0b25f52b266bf45c8680398de43a61a042998a08760b867d3be1878aad518567caa6a0801cec80
+  data.tar.gz: 175b62d75d9fa46391570026e345b18c099ab75dabfe4518acd89e750de4fce97eebd01fcc8733ce771492343a74f50dbca9534c2305e47599eebe966dd04d9d

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.6.0 (2026-04-02)
+
+### Breaking Changes
+- **[Breaking]** Drop Ruby 3.2 support. Minimum required Ruby version is now 3.3.0.
+
+### Connection Management
+- **[Breaking]** Detect shared `PG::Connection` across pool slots at creation time. When a callable connection factory returns the same `PG::Connection` object to multiple pool slots, concurrent threads corrupt libpq's internal state, causing nil `PG::Result` (`NoMethodError: undefined method 'ntuples' for nil`), segfaults, or wrong data. The pool now tracks connection identity via `ObjectSpace::WeakKeyMap` and raises `PGMQ::Errors::ConfigurationError` immediately with a descriptive error message. WeakKeyMap entries are automatically cleaned up when connections are GC'd. **This change is breaking for configurations that intentionally share a single `PG::Connection` across multiple pool slots. Users must ensure their callable returns a distinct `PG::Connection` per pool slot or configure `pool_size: 1` when reusing a single shared connection.**
+
+### 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`.
+
+## 0.5.0 (2026-02-24)
+
+### Breaking Changes
+- **[Breaking]** Remove `detach_archive(queue_name)` method. PGMQ 2.0 no longer requires archive table detachment as archive tables are no longer member objects. The server-side function was already a no-op in PGMQ 2.0+.
+- **[Breaking]** Rename `vt_offset:` parameter to `vt:` in `set_vt`, `set_vt_batch`, and `set_vt_multi` methods. The `vt:` parameter now accepts either an integer offset (seconds from now) or an absolute `Time` object for PGMQ v1.11.0+.
+
+### PGMQ v1.11.0 Features
+- **[Feature]** Add `last_read_at` field to `PGMQ::Message`. Returns the timestamp of the last read operation for the message, or nil if the message has never been read. This enables tracking when messages were last accessed (PGMQ v1.8.1+).
+- **[Feature]** Add Grouped Round-Robin reading for fair message processing:
+  - `read_grouped_rr(queue_name, vt:, qty:)` - Read messages in round-robin order across groups
+  - `read_grouped_rr_with_poll(queue_name, vt:, qty:, max_poll_seconds:, poll_interval_ms:)` - With long-polling
+
+  Messages are grouped by the first key in their JSON payload. This ensures fair processing
+  when multiple entities (users, orders, etc.) have messages in the queue, preventing any
+  single entity from monopolizing workers.
+- **[Feature]** Add Topic Routing support (AMQP-like patterns). New methods in `PGMQ::Client`:
+  - `bind_topic(pattern, queue_name)` - Bind a topic pattern to a queue
+  - `unbind_topic(pattern, queue_name)` - Remove a topic binding
+  - `produce_topic(routing_key, message, headers:, delay:)` - Send message via routing key
+  - `produce_batch_topic(routing_key, messages, headers:, delay:)` - Batch send via routing key
+  - `list_topic_bindings(queue_name:)` - List all topic bindings
+  - `test_routing(routing_key)` - Test which queues a routing key matches
+  - `validate_routing_key(routing_key)` - Validate a routing key
+  - `validate_topic_pattern(pattern)` - Validate a topic pattern
+
+  Topic patterns support wildcards: `*` (single word) and `#` (zero or more words).
+  Requires PGMQ v1.11.0+.
+
+### Testing
+- **[Feature]** Add Fiber Scheduler integration tests demonstrating compatibility with Ruby's Fiber Scheduler API and the `async` gem for concurrent I/O operations.
+
+### Infrastructure
+- **[Fix]** Update docker-compose.yml volume mount for PostgreSQL 18+ compatibility.
+- **[Change]** Replace Coditsu with StandardRB for code linting. This provides faster, more consistent linting using the community Ruby Style Guide.
+
 ## 0.4.0 (2025-12-26)
 
 ### Breaking Changes
@@ -118,7 +166,7 @@ Initial release of pgmq-ruby - a low-level Ruby client for PGMQ (PostgreSQL Mess
 - [Enhancement] Example scripts demonstrating all features.
 
 ### Dependencies
-- Ruby >= 3.2.0
+- Ruby >= 3.3.0
 - PostgreSQL >= 14 with PGMQ extension
 - `pg` gem (~> 1.5)
 - `connection_pool` gem (~> 2.4)

data/README.md

@@ -25,11 +25,17 @@ PGMQ-Ruby is a Ruby client for PGMQ (PostgreSQL Message Queue). It provides dire
 - [Quick Start](#quick-start)
 - [Configuration](#configuration)
 - [API Reference](#api-reference)
+  - [Queue Management](#queue-management)
+  - [Sending Messages](#sending-messages)
+  - [Reading Messages](#reading-messages)
+  - [Grouped Round-Robin Reading](#grouped-round-robin-reading)
+  - [Message Lifecycle](#message-lifecycle)
+  - [Monitoring](#monitoring)
+  - [Transaction Support](#transaction-support)
+  - [Topic Routing](#topic-routing-amqp-like-patterns)
 - [Message Object](#message-object)
-- [Serializers](#serializers)
-- [Rails Integration](#rails-integration)
+- [Working with JSON](#working-with-json)
 - [Development](#development)
-- [License](#license)
 - [Author](#author)
 
 ## PGMQ Feature Support
@@ -43,6 +49,8 @@ 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_rr` | Round-robin reading across message groups | ✅ |
+| | `read_grouped_rr_with_poll` | Round-robin with long-polling | ✅ |
 | | `pop` | Atomic read + delete operation | ✅ |
 | | `pop_batch` | Atomic batch read + delete operation | ✅ |
 | **Deleting/Archiving** | `delete` | Delete single message | ✅ |
@@ -54,8 +62,13 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 | | `create_partitioned` | Create partitioned queue (requires pg_partman) | ✅ |
 | | `create_unlogged` | Create unlogged queue (faster, no crash recovery) | ✅ |
 | | `drop_queue` | Delete queue and all messages | ✅ |
-| | `detach_archive` | Detach archive table from queue | ✅ |
-| **Utilities** | `set_vt` | Update message visibility timeout | ✅ |
+| **Topic Routing** | `bind_topic` | Bind topic pattern to queue (AMQP-like) | ✅ |
+| | `unbind_topic` | Remove topic binding | ✅ |
+| | `produce_topic` | Send message via routing key | ✅ |
+| | `produce_batch_topic` | Batch send via routing key | ✅ |
+| | `list_topic_bindings` | List all topic bindings | ✅ |
+| | `test_routing` | Test which queues match a routing key | ✅ |
+| **Utilities** | `set_vt` | Update visibility timeout (integer or Time) | ✅ |
 | | `set_vt_batch` | Batch update visibility timeouts | ✅ |
 | | `set_vt_multi` | Update visibility timeouts across multiple queues | ✅ |
 | | `list_queues` | List all queues with metadata | ✅ |
@@ -75,6 +88,67 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 - Ruby 3.2+
 - PostgreSQL 14-18 with PGMQ extension installed
 
+### Installing PGMQ Extension
+
+PGMQ can be installed on your PostgreSQL instance in several ways:
+
+#### Standard Installation (Self-hosted PostgreSQL)
+
+For self-hosted PostgreSQL instances with filesystem access, install via [PGXN](https://pgxn.org/dist/pgmq/):
+
+```bash
+pgxn install pgmq
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/pgmq/pgmq.git
+cd pgmq/pgmq-extension
+make && make install
+```
+
+Then enable the extension:
+
+```sql
+CREATE EXTENSION pgmq;
+```
+
+#### Managed PostgreSQL Services (AWS RDS, Aurora, etc.)
+
+For managed PostgreSQL services that don't allow native extension installation, PGMQ provides a **SQL-only installation** that works without filesystem access:
+
+```bash
+git clone https://github.com/pgmq/pgmq.git
+cd pgmq
+psql -f pgmq-extension/sql/pgmq.sql postgres://user:pass@your-rds-host:5432/database
+```
+
+This creates a `pgmq` schema with all required functions. See [PGMQ Installation Guide](https://github.com/pgmq/pgmq/blob/main/INSTALLATION.md) for details.
+
+**Comparison:**
+
+| Feature | Extension | SQL-only |
+|---------|-----------|----------|
+| Version tracking | Yes | No |
+| Upgrade path | Yes | Manual |
+| Filesystem access | Required | Not needed |
+| Managed cloud services | Limited | Full support |
+
+#### Using pg_tle (Trusted Language Extensions)
+
+If your managed PostgreSQL service supports [pg_tle](https://github.com/aws/pg_tle) (available on AWS RDS PostgreSQL 14.5+ and Aurora), you can potentially install PGMQ as a Trusted Language Extension since PGMQ is written in PL/pgSQL and SQL (both supported by pg_tle).
+
+To use pg_tle:
+
+1. Enable pg_tle on your instance (add to `shared_preload_libraries`)
+2. Create the pg_tle extension: `CREATE EXTENSION pg_tle;`
+3. Use `pgtle.install_extension()` to install PGMQ's SQL functions
+
+See [AWS pg_tle documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/PostgreSQL_trusted_language_extension.html) for setup instructions.
+
+> **Note:** The SQL-only installation is simpler and recommended for most managed service use cases. pg_tle provides additional version management and extension lifecycle features if needed.
+
 ## Installation
 
 Add to your Gemfile:
@@ -218,7 +292,7 @@ client = PGMQ::Client.new(
 
 **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
+- **Fiber-aware** - Works with Ruby 3.0+ Fiber Scheduler for non-blocking I/O (tested with the `async` gem)
 - **Auto-reconnect** - Recovers from lost connections (configurable)
 - **Health checks** - Verifies connections before use to prevent stale connection errors
 - **Monitoring** - Track pool utilization with `client.stats`
@@ -334,6 +408,50 @@ msg = client.pop("queue_name")
 
 # Pop batch (atomic read + delete for multiple messages)
 messages = client.pop_batch("queue_name", 10)
+
+# 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)
+
+# Grouped round-robin with long-polling
+messages = client.read_grouped_rr_with_poll("queue_name",
+  vt: 30,
+  qty: 10,
+  max_poll_seconds: 5,
+  poll_interval_ms: 100
+)
+```
+
+#### Grouped Round-Robin Reading
+
+When processing messages from multiple entities (users, orders, tenants), regular FIFO ordering can cause starvation - one entity with many messages can monopolize workers.
+
+Grouped round-robin ensures fair processing by interleaving messages from different groups:
+
+```ruby
+# Queue contains messages for different users:
+# user_a: 5 messages, user_b: 2 messages, user_c: 1 message
+
+# 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]
+
+# Grouped round-robin ensures fair distribution
+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
+
+**Message format for grouping:**
+```ruby
+# Good - user_id is first key, used for grouping
+client.produce("tasks", '{"user_id":"user_a","task":"process"}')
+
+# The grouping key should come first in your JSON
 ```
 
 #### Conditional Message Filtering
@@ -398,17 +516,24 @@ client.archive("queue_name", msg_id)
 # Archive batch
 archived_ids = client.archive_batch("queue_name", [101, 102, 103])
 
-# Update visibility timeout
-msg = client.set_vt("queue_name", msg_id, vt_offset: 60)
+# Update visibility timeout with integer offset (seconds from now)
+msg = client.set_vt("queue_name", msg_id, vt: 60)
+
+# Update visibility timeout with absolute Time (PGMQ v1.11.0+)
+future_time = Time.now + 300  # 5 minutes from now
+msg = client.set_vt("queue_name", msg_id, vt: future_time)
 
 # Batch update visibility timeout
-updated_msgs = client.set_vt_batch("queue_name", [101, 102, 103], vt_offset: 60)
+updated_msgs = client.set_vt_batch("queue_name", [101, 102, 103], vt: 60)
+
+# Batch update with absolute Time
+updated_msgs = client.set_vt_batch("queue_name", [101, 102, 103], vt: Time.now + 120)
 
 # Update visibility timeout across multiple queues
 client.set_vt_multi({
   "orders" => [1, 2, 3],
   "notifications" => [5, 6]
-}, vt_offset: 120)
+}, vt: 120)
 
 # Purge all messages
 count = client.purge_queue("queue_name")
@@ -512,6 +637,82 @@ end
 - Read operations with long visibility timeouts may cause lock contention
 - Consider using `pop()` for atomic read+delete in simple cases
 
+### Topic Routing (AMQP-like Patterns)
+
+PGMQ v1.11.0+ supports AMQP-style topic routing, allowing messages to be delivered to multiple queues based on pattern matching.
+
+#### Topic Patterns
+
+Topic patterns support wildcards:
+- `*` matches exactly one word (e.g., `orders.*` matches `orders.new` but not `orders.new.priority`)
+- `#` matches zero or more words (e.g., `orders.#` matches `orders`, `orders.new`, and `orders.new.priority`)
+
+```ruby
+# Create queues for different purposes
+client.create("new_orders")
+client.create("order_updates")
+client.create("all_orders")
+client.create("audit_log")
+
+# Bind topic patterns to queues
+client.bind_topic("orders.new", "new_orders")        # Exact match
+client.bind_topic("orders.update", "order_updates")  # Exact match
+client.bind_topic("orders.*", "all_orders")          # Single-word wildcard
+client.bind_topic("#", "audit_log")                  # Catch-all
+
+# Send messages via routing key
+# Message is delivered to ALL queues with matching patterns
+count = client.produce_topic("orders.new", '{"order_id":123}')
+# => 3 (delivered to: new_orders, all_orders, audit_log)
+
+count = client.produce_topic("orders.update", '{"order_id":123,"status":"shipped"}')
+# => 3 (delivered to: order_updates, all_orders, audit_log)
+
+# Send with headers and delay
+count = client.produce_topic("orders.new.priority",
+  '{"order_id":456}',
+  headers: '{"trace_id":"abc123"}',
+  delay: 0
+)
+
+# Batch send via topic routing
+results = client.produce_batch_topic("orders.new", [
+  '{"order_id":1}',
+  '{"order_id":2}',
+  '{"order_id":3}'
+])
+# => [{ queue_name: "new_orders", msg_id: "1" }, ...]
+
+# List all topic bindings
+bindings = client.list_topic_bindings
+bindings.each do |b|
+  puts "#{b[:pattern]} -> #{b[:queue_name]}"
+end
+
+# List bindings for specific queue
+bindings = client.list_topic_bindings(queue_name: "all_orders")
+
+# Test which queues a routing key would match (for debugging)
+matches = client.test_routing("orders.new.priority")
+# => [{ pattern: "orders.#", queue_name: "all_orders" }, ...]
+
+# Validate routing keys and patterns
+client.validate_routing_key("orders.new.priority")  # => true
+client.validate_routing_key("orders.*")             # => false (wildcards not allowed in keys)
+client.validate_topic_pattern("orders.*")           # => true
+client.validate_topic_pattern("orders.#")           # => true
+
+# Remove bindings when done
+client.unbind_topic("orders.new", "new_orders")
+client.unbind_topic("orders.*", "all_orders")
+```
+
+**Use Cases:**
+- **Event broadcasting**: Send events to multiple consumers based on event type
+- **Multi-tenant routing**: Route messages to tenant-specific queues
+- **Log aggregation**: Capture all messages in an audit queue while routing to specific handlers
+- **Fan-out patterns**: Deliver one message to multiple processing pipelines
+
 ## Message Object
 
 PGMQ-Ruby is a **low-level transport library** - it returns raw values from PostgreSQL without any transformation. You are responsible for parsing JSON and type conversion.
@@ -524,6 +725,7 @@ msg.msg_id          # => "123" (String, not Integer)
 msg.id              # => "123" (alias for msg_id)
 msg.read_ct         # => "1" (String, not Integer)
 msg.enqueued_at     # => "2025-01-15 10:30:00+00" (String, not Time)
+msg.last_read_at    # => "2025-01-15 10:30:15+00" (String, or nil if never read)
 msg.vt              # => "2025-01-15 10:30:30+00" (String, not Time)
 msg.message         # => "{\"data\":\"value\"}" (Raw JSONB as JSON string)
 msg.headers         # => "{\"trace_id\":\"abc123\"}" (Raw JSONB as JSON string, optional)
@@ -537,6 +739,7 @@ metadata = JSON.parse(msg.headers) if msg.headers  # => { "trace_id" => "abc123"
 id = msg.msg_id.to_i           # => 123
 read_count = msg.read_ct.to_i  # => 1
 enqueued = Time.parse(msg.enqueued_at)  # => 2025-01-15 10:30:00 UTC
+last_read = Time.parse(msg.last_read_at) if msg.last_read_at  # => Time or nil
 ```
 
 ### Message Headers
@@ -674,7 +877,13 @@ bundle install
 docker compose up -d
 
 # Run tests
-bundle exec rspec
+bundle exec rake test
+
+# Run all integration specs
+bin/integrations
+
+# Run a specific integration spec
+bin/integrations spec/integration/basic_produce_consume_spec.rb
 
 # Run console
 bundle exec bin/console

data/lib/pgmq/client/consumer.rb

@@ -33,12 +33,12 @@ module PGMQ
         result = with_connection do |conn|
           if conditional.empty?
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)",
               [queue_name, vt, 1]
             )
           else
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)",
               [queue_name, vt, 1, conditional.to_json]
             )
           end
@@ -82,12 +82,12 @@ module PGMQ
         result = with_connection do |conn|
           if conditional.empty?
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer)",
               [queue_name, vt, qty]
             )
           else
             conn.exec_params(
-              'SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)',
+              "SELECT * FROM pgmq.read($1::text, $2::integer, $3::integer, $4::jsonb)",
               [queue_name, vt, qty, conditional.to_json]
             )
           end
@@ -135,12 +135,12 @@ module PGMQ
         result = with_connection do |conn|
           if conditional.empty?
             conn.exec_params(
-              'SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)',
+              "SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, $4::integer, $5::integer)",
               [queue_name, vt, qty, max_poll_seconds, poll_interval_ms]
             )
           else
-            sql = 'SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, ' \
-                  '$4::integer, $5::integer, $6::jsonb)'
+            sql = "SELECT * FROM pgmq.read_with_poll($1::text, $2::integer, $3::integer, " \
+                  "$4::integer, $5::integer, $6::jsonb)"
             conn.exec_params(
               sql,
               [queue_name, vt, qty, max_poll_seconds, poll_interval_ms, conditional.to_json]
@@ -150,6 +150,79 @@ module PGMQ
 
         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.
+      #
+      # @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 in round-robin order
+      #
+      # @example Fair processing across users
+      #   # Queue contains: user1_msg1, user1_msg2, user2_msg1, user3_msg1
+      #   messages = client.read_grouped_rr("tasks", vt: 30, qty: 4)
+      #   # Returns in round-robin: user1_msg1, user2_msg1, user3_msg1, user1_msg2
+      #
+      # @example Prevent single entity from monopolizing worker
+      #   loop do
+      #     messages = client.read_grouped_rr("orders", vt: 30, qty: 10)
+      #     break if messages.empty?
+      #     messages.each { |msg| process(msg) }
+      #   end
+      def read_grouped_rr(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_rr($1::text, $2::integer, $3::integer)",
+            [queue_name, vt, qty]
+          )
+        end
+
+        result.map { |row| Message.new(row) }
+      end
+
+      # Reads messages using grouped round-robin with long-polling support
+      #
+      # 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
+      # @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 in round-robin order
+      #
+      # @example Long-polling with fair ordering
+      #   messages = client.read_grouped_rr_with_poll("tasks",
+      #     vt: 30,
+      #     qty: 10,
+      #     max_poll_seconds: 5,
+      #     poll_interval_ms: 100
+      #   )
+      def read_grouped_rr_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_rr_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
     end
   end
 end

data/lib/pgmq/client/maintenance.rb

@@ -19,27 +19,10 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         result = with_connection do |conn|
-          conn.exec_params('SELECT pgmq.purge_queue($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.purge_queue($1::text)", [queue_name])
         end
 
-        result[0]['purge_queue']
-      end
-
-      # Detaches the archive table from PGMQ management
-      #
-      # @param queue_name [String] name of the queue
-      # @return [void]
-      #
-      # @example
-      #   client.detach_archive("orders")
-      def detach_archive(queue_name)
-        validate_queue_name!(queue_name)
-
-        with_connection do |conn|
-          conn.exec_params('SELECT pgmq.detach_archive($1::text)', [queue_name])
-        end
-
-        nil
+        result[0]["purge_queue"]
       end
 
       # Enables PostgreSQL NOTIFY when messages are inserted into a queue
@@ -65,7 +48,7 @@ module PGMQ
 
         with_connection do |conn|
           conn.exec_params(
-            'SELECT pgmq.enable_notify_insert($1::text, $2::integer)',
+            "SELECT pgmq.enable_notify_insert($1::text, $2::integer)",
             [queue_name, throttle_interval_ms]
           )
         end
@@ -84,7 +67,7 @@ module PGMQ
         validate_queue_name!(queue_name)
 
         with_connection do |conn|
-          conn.exec_params('SELECT pgmq.disable_notify_insert($1::text)', [queue_name])
+          conn.exec_params("SELECT pgmq.disable_notify_insert($1::text)", [queue_name])
         end
 
         nil