pgmq-ruby 0.4.0 → 0.5.0

data/Gemfile.lint.lock

@@ -0,0 +1,120 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    json (2.18.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    regexp_parser (2.11.3)
+    rubocop (1.84.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.28.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rspec (3.9.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.81)
+    rubocop-rspec_rails (2.32.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+      rubocop-rspec (~> 3.5)
+    ruby-progressbar (1.13.0)
+    standard (1.54.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.84.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
+    standard-rspec (0.4.0)
+      lint_roller (>= 1.0)
+      rubocop-capybara (~> 2.22)
+      rubocop-factory_bot (~> 2.27)
+      rubocop-rspec (~> 3.9)
+      rubocop-rspec_rails (~> 2.31)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    yard (0.9.38)
+    yard-lint (1.4.0)
+      yard (~> 0.9)
+      zeitwerk (~> 2.6)
+    zeitwerk (2.7.4)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  rubocop-capybara
+  rubocop-factory_bot
+  rubocop-performance
+  rubocop-rspec
+  rubocop-rspec_rails
+  standard
+  standard-performance
+  standard-rspec
+  yard-lint
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  json (2.18.1) sha256=fe112755501b8d0466b5ada6cf50c8c3f41e897fa128ac5d263ec09eedc9f986
+  language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  parallel (1.27.0) sha256=4ac151e1806b755fb4e2dc2332cbf0e54f2e24ba821ff2d3dcf86bf6dc4ae130
+  parser (3.3.10.2) sha256=6f60c84aa4bdcedb6d1a2434b738fe8a8136807b6adc8f7f53b97da9bc4e9357
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  regexp_parser (2.11.3) sha256=ca13f381a173b7a93450e53459075c9b76a10433caadcb2f1180f2c741fc55a4
+  rubocop (1.84.2) sha256=5692cea54168f3dc8cb79a6fe95c5424b7ea893c707ad7a4307b0585e88dbf5f
+  rubocop-ast (1.49.0) sha256=49c3676d3123a0923d333e20c6c2dbaaae2d2287b475273fddee0c61da9f71fd
+  rubocop-capybara (2.22.1) sha256=ced88caef23efea53f46e098ff352f8fc1068c649606ca75cb74650970f51c0c
+  rubocop-factory_bot (2.28.0) sha256=4b17fc02124444173317e131759d195b0d762844a71a29fe8139c1105d92f0cb
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  rubocop-rspec (3.9.0) sha256=8fa70a3619408237d789aeecfb9beef40576acc855173e60939d63332fdb55e2
+  rubocop-rspec_rails (2.32.0) sha256=4a0d641c72f6ebb957534f539d9d0a62c47abd8ce0d0aeee1ef4701e892a9100
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  standard (1.54.0) sha256=7a4b08f83d9893083c8f03bc486f0feeb6a84d48233b40829c03ef4767ea0100
+  standard-custom (1.0.2) sha256=424adc84179a074f1a2a309bb9cf7cd6bfdb2b6541f20c6bf9436c0ba22a652b
+  standard-performance (1.9.0) sha256=49483d31be448292951d80e5e67cdcb576c2502103c7b40aec6f1b6e9c88e3f2
+  standard-rspec (0.4.0) sha256=0fdf64c887cd6404f1c3a1435b14ba6fde2e9e80c0f4dafe4b04a67f673db262
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  yard (0.9.38) sha256=721fb82afb10532aa49860655f6cc2eaa7130889df291b052e1e6b268283010f
+  yard-lint (1.4.0) sha256=7dd88fbb08fd77cb840bea899d58812817b36d92291b5693dd0eeb3af9f91f0f
+  zeitwerk (2.7.4) sha256=2bef90f356bdafe9a6c2bd32bcd804f83a4f9b8bc27f3600fff051eb3edcec8b
+
+BUNDLED WITH
+  4.0.3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pgmq-ruby (0.4.0)
+    pgmq-ruby (0.5.0)
       connection_pool (~> 2.4)
       pg (~> 1.5)
       zeitwerk (~> 2.6)
@@ -9,9 +9,26 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    async (2.36.0)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.11)
+      metrics (~> 0.12)
+      traces (~> 0.18)
     connection_pool (2.5.4)
+    console (1.34.3)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
     diff-lcs (1.6.2)
     docile (1.4.1)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
+    io-event (1.14.2)
+    json (2.18.1)
+    metrics (0.15.0)
     pg (1.6.2)
     pg (1.6.2-aarch64-linux)
     pg (1.6.2-aarch64-linux-musl)
@@ -39,10 +56,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
-    yard (0.9.38)
-    yard-lint (1.3.0)
-      yard (~> 0.9)
-      zeitwerk (~> 2.6)
+    traces (0.18.2)
     zeitwerk (2.7.3)
 
 PLATFORMS
@@ -55,11 +69,11 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  async (~> 2.6)
   pgmq-ruby!
   rake
   rspec
   simplecov
-  yard-lint
 
 BUNDLED WITH
    2.7.2

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

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.8.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