pgmq-ruby 0.3.0 → 0.5.0

data/README.md

@@ -1,7 +1,7 @@
 # PGMQ-Ruby
 
 [![Gem Version](https://badge.fury.io/rb/pgmq-ruby.svg)](https://badge.fury.io/rb/pgmq-ruby)
-[![Build Status](https://github.com/mensfeld/pgmq-ruby/workflows/ci/badge.svg)](https://github.com/mensfeld/pgmq-ruby/actions)
+[![Build Status](https://github.com/mensfeld/pgmq-ruby/workflows/CI/badge.svg)](https://github.com/mensfeld/pgmq-ruby/actions)
 
 **Ruby client for [PGMQ](https://github.com/pgmq/pgmq) - PostgreSQL Message Queue**
 
@@ -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
@@ -38,12 +44,15 @@ This gem provides complete support for all core PGMQ SQL functions. Based on the
 
 | Category | Method | Description | Status |
 |----------|--------|-------------|--------|
-| **Sending** | `send` | Send single message with optional delay | ✅ |
-| | `send_batch` | Send multiple messages atomically | ✅ |
+| **Producing** | `produce` | Send single message with optional delay and headers | ✅ |
+| | `produce_batch` | Send multiple messages atomically with headers | ✅ |
 | **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 | ✅ |
 | | `delete_batch` | Delete multiple messages | ✅ |
 | | `archive` | Archive single message for long-term storage | ✅ |
@@ -53,11 +62,20 @@ 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 | ✅ |
 | | `metrics` | Get queue metrics (length, age, total messages) | ✅ |
 | | `metrics_all` | Get metrics for all queues | ✅ |
+| | `enable_notify_insert` | Enable PostgreSQL NOTIFY on insert | ✅ |
+| | `disable_notify_insert` | Disable notifications | ✅ |
 | **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 | ✅ |
@@ -70,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:
@@ -104,7 +183,7 @@ client = PGMQ::Client.new(
 client.create('orders')
 
 # Send a message (must be JSON string)
-msg_id = client.send('orders', '{"order_id":123,"total":99.99}')
+msg_id = client.produce('orders', '{"order_id":123,"total":99.99}')
 
 # Read a message (30 second visibility timeout)
 msg = client.read('orders', vt: 30)
@@ -213,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`
@@ -224,20 +303,21 @@ client = PGMQ::Client.new(
 ### Queue Management
 
 ```ruby
-# Create a queue
-client.create("queue_name")
+# Create a queue (returns true if created, false if already exists)
+client.create("queue_name")      # => true
+client.create("queue_name")      # => false (idempotent)
 
 # Create partitioned queue (requires pg_partman)
 client.create_partitioned("queue_name",
   partition_interval: "daily",
   retention_interval: "7 days"
-)
+)  # => true/false
 
 # Create unlogged queue (faster, no crash recovery)
-client.create_unlogged("queue_name")
+client.create_unlogged("queue_name")  # => true/false
 
-# Drop queue
-client.drop_queue("queue_name")
+# Drop queue (returns true if dropped, false if didn't exist)
+client.drop_queue("queue_name")  # => true/false
 
 # List all queues
 queues = client.list_queues
@@ -277,18 +357,32 @@ client.create("a" * 48)          # ✗ Too long (48+ chars)
 
 ```ruby
 # Send single message (must be JSON string)
-msg_id = client.send("queue_name", '{"data":"value"}')
+msg_id = client.produce("queue_name", '{"data":"value"}')
 
 # Send with delay (seconds)
-msg_id = client.send("queue_name", '{"data":"value"}', delay: 60)
+msg_id = client.produce("queue_name", '{"data":"value"}', delay: 60)
+
+# Send with headers (for routing, tracing, correlation)
+msg_id = client.produce("queue_name", '{"data":"value"}',
+  headers: '{"trace_id":"abc123","priority":"high"}')
+
+# Send with headers and delay
+msg_id = client.produce("queue_name", '{"data":"value"}',
+  headers: '{"correlation_id":"req-456"}',
+  delay: 60)
 
 # Send batch (array of JSON strings)
-msg_ids = client.send_batch("queue_name", [
+msg_ids = client.produce_batch("queue_name", [
   '{"order":1}',
   '{"order":2}',
   '{"order":3}'
 ])
 # => ["101", "102", "103"]
+
+# Send batch with headers (one per message)
+msg_ids = client.produce_batch("queue_name",
+  ['{"order":1}', '{"order":2}'],
+  headers: ['{"priority":"high"}', '{"priority":"low"}'])
 ```
 
 ### Reading Messages
@@ -311,6 +405,53 @@ msg = client.read_with_poll("queue_name",
 
 # Pop (atomic read + delete)
 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
@@ -375,11 +516,33 @@ 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: 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: 120)
 
 # Purge all messages
 count = client.purge_queue("queue_name")
+
+# Enable PostgreSQL NOTIFY for a queue (for LISTEN-based consumers)
+client.enable_notify_insert("queue_name", throttle_interval_ms: 250)
+
+# Disable notifications
+client.disable_notify_insert("queue_name")
 ```
 
 ### Monitoring
@@ -409,9 +572,9 @@ Execute atomic operations across multiple queues or combine queue operations wit
 # Atomic operations across multiple queues
 client.transaction do |txn|
   # Send to multiple queues atomically
-  txn.send("orders", '{"order_id":123}')
-  txn.send("notifications", '{"user_id":456,"type":"order_created"}')
-  txn.send("analytics", '{"event":"order_placed"}')
+  txn.produce("orders", '{"order_id":123}')
+  txn.produce("notifications", '{"user_id":456,"type":"order_created"}')
+  txn.produce("analytics", '{"event":"order_placed"}')
 end
 
 # Process message and update application state atomically
@@ -431,8 +594,8 @@ end
 
 # Automatic rollback on errors
 client.transaction do |txn|
-  txn.send("queue1", '{"data":"message1"}')
-  txn.send("queue2", '{"data":"message2"}')
+  txn.produce("queue1", '{"data":"message1"}')
+  txn.produce("queue2", '{"data":"message2"}')
 
   raise "Something went wrong!"
   # Both messages are rolled back - neither queue receives anything
@@ -446,7 +609,7 @@ client.transaction do |txn|
     data = JSON.parse(msg.message)
     if data["priority"] == "high"
       # Move to high-priority queue
-      txn.send("priority_orders", msg.message)
+      txn.produce("priority_orders", msg.message)
       txn.delete("pending_orders", msg.msg_id)
     end
   end
@@ -474,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.
@@ -486,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)
@@ -499,25 +739,48 @@ 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
 
-PGMQ supports optional message headers via the `headers` JSONB column:
+PGMQ supports optional message headers via the `headers` JSONB column. Headers are useful for metadata like routing information, correlation IDs, and distributed tracing:
 
 ```ruby
-# Sending with headers requires direct SQL or a custom wrapper
-# (pgmq-ruby focuses on the core PGMQ API which doesn't have a send_with_headers function)
+# Sending a message with headers
+message = '{"order_id":123}'
+headers = '{"trace_id":"abc123","priority":"high","correlation_id":"req-456"}'
+
+msg_id = client.produce("orders", message, headers: headers)
+
+# Sending with headers and delay
+msg_id = client.produce("orders", message, headers: headers, delay: 60)
+
+# Batch produce with headers (one header object per message)
+messages = ['{"id":1}', '{"id":2}', '{"id":3}']
+headers = [
+  '{"priority":"high"}',
+  '{"priority":"medium"}',
+  '{"priority":"low"}'
+]
+msg_ids = client.produce_batch("orders", messages, headers: headers)
 
 # Reading messages with headers
-msg = client.read("queue", vt: 30)
+msg = client.read("orders", vt: 30)
 if msg.headers
   metadata = JSON.parse(msg.headers)
   trace_id = metadata["trace_id"]
+  priority = metadata["priority"]
   correlation_id = metadata["correlation_id"]
 end
 ```
 
+Common header use cases:
+- **Distributed tracing**: `trace_id`, `span_id`, `parent_span_id`
+- **Request correlation**: `correlation_id`, `causation_id`
+- **Routing**: `priority`, `region`, `tenant_id`
+- **Content metadata**: `content_type`, `encoding`, `version`
+
 ### Why Raw Values?
 
 This library follows the **rdkafka-ruby philosophy** - provide a thin, performant wrapper around the underlying system:
@@ -538,14 +801,14 @@ PGMQ stores messages as JSONB in PostgreSQL. You must handle JSON serialization
 ```ruby
 # Simple hash
 msg = { order_id: 123, status: "pending" }
-client.send("orders", msg.to_json)
+client.produce("orders", msg.to_json)
 
 # Using JSON.generate for explicit control
-client.send("orders", JSON.generate(order_id: 123, status: "pending"))
+client.produce("orders", JSON.generate(order_id: 123, status: "pending"))
 
 # Pre-serialized JSON string
 json_str = '{"order_id":123,"status":"pending"}'
-client.send("orders", json_str)
+client.produce("orders", json_str)
 ```
 
 ### Reading Messages
@@ -577,8 +840,8 @@ class QueueHelper
     @client = client
   end
 
-  def send(queue, data)
-    @client.send(queue, data.to_json)
+  def produce(queue, data)
+    @client.produce(queue, data.to_json)
   end
 
   def read(queue, vt:)
@@ -595,7 +858,7 @@ class QueueHelper
 end
 
 helper = QueueHelper.new(client)
-helper.send("orders", { order_id: 123 })
+helper.produce("orders", { order_id: 123 })
 msg = helper.read("orders", vt: 30)
 puts msg.data["order_id"]  # => 123
 ```

data/Rakefile

@@ -1,4 +1,73 @@
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'bundler/gem_tasks'
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+namespace :examples do
+  desc "Run all examples (validates gem functionality)"
+  task :run do
+    examples_dir = File.expand_path("spec/integration", __dir__)
+    example_files = Dir.glob(File.join(examples_dir, "*_spec.rb")).sort
+
+    puts "Running #{example_files.size} examples..."
+    puts
+
+    failed = []
+    example_files.each_with_index do |example, index|
+      name = File.basename(example)
+      puts "[#{index + 1}/#{example_files.size}] Running #{name}..."
+
+      success = system("bundle exec ruby #{example}")
+      if success.nil?
+        puts "Interrupted. Aborting."
+        exit(130)
+      elsif !success
+        failed << name
+        puts "FAILED: #{name}"
+      end
+      puts
+    end
+
+    puts "=" * 60
+    if failed.empty?
+      puts "All #{example_files.size} examples passed."
+    else
+      puts "#{failed.size} example(s) failed:"
+      failed.each { |f| puts "  - #{f}" }
+      exit(1)
+    end
+  end
+
+  desc "Run a specific example by name (e.g., rake examples:run_one[basic_produce_consume])"
+  task :run_one, [:name] do |_t, args|
+    examples_dir = File.expand_path("spec/integration", __dir__)
+    pattern = File.join(examples_dir, "*#{args[:name]}*_spec.rb")
+    matches = Dir.glob(pattern)
+
+    if matches.empty?
+      puts "No example found matching: #{args[:name]}"
+      exit(1)
+    end
+
+    exec("bundle exec ruby #{matches.first}")
+  end
+
+  desc "List all available examples"
+  task :list do
+    examples_dir = File.expand_path("spec/integration", __dir__)
+    example_files = Dir.glob(File.join(examples_dir, "*_spec.rb")).sort
+
+    puts "Available examples:"
+    example_files.each do |f|
+      name = File.basename(f, "_spec.rb")
+      puts "  #{name}"
+    end
+    puts
+    puts "Run with: bundle exec rake examples:run_one[NAME]"
+    puts "Example:  bundle exec rake examples:run_one[basic_produce_consume]"
+  end
+end
+
+# Shorthand task
+desc "Run all examples"
+task examples: "examples:run"

data/docker-compose.yml

@@ -2,7 +2,7 @@ version: '3.8'
 
 services:
   postgres:
-    image: ghcr.io/pgmq/pg18-pgmq:v1.7.0
+    image: ghcr.io/pgmq/pg18-pgmq:v1.9.0
     container_name: pgmq_postgres_test
     environment:
       POSTGRES_USER: postgres
@@ -11,7 +11,7 @@ services:
     ports:
       - "5433:5432"  # Use port 5433 locally to avoid conflicts
     volumes:
-      - pgmq_data:/var/lib/postgresql/data
+      - pgmq_data:/var/lib/postgresql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U postgres"]
       interval: 5s