pgbus 0.0.1

data/app/views/pgbus/jobs/show.html.erb

@@ -0,0 +1,57 @@
+<div class="mb-6">
+  <%= link_to "&larr; Back to Jobs".html_safe, pgbus.jobs_path, class: "text-sm text-indigo-600 hover:text-indigo-500" %>
+</div>
+
+<% if @job %>
+  <h1 class="text-2xl font-bold text-gray-900 mb-6">Failed Job #<%= @job["id"] %></h1>
+
+  <div class="rounded-lg bg-white shadow ring-1 ring-gray-200 p-6 mb-6">
+    <dl class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Queue</dt>
+        <dd class="text-sm text-gray-900"><%= @job["queue_name"] %></dd>
+      </div>
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Failed At</dt>
+        <dd class="text-sm text-gray-900"><%= @job["failed_at"] %></dd>
+      </div>
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Error Class</dt>
+        <dd class="text-sm text-red-600 font-medium"><%= @job["error_class"] %></dd>
+      </div>
+      <div>
+        <dt class="text-sm font-medium text-gray-500">Retry Count</dt>
+        <dd class="text-sm text-gray-900"><%= @job["retry_count"] %></dd>
+      </div>
+    </dl>
+  </div>
+
+  <div class="rounded-lg bg-white shadow ring-1 ring-gray-200 p-6 mb-6">
+    <h2 class="text-sm font-medium text-gray-500 mb-2">Error Message</h2>
+    <p class="text-sm text-red-700"><%= @job["error_message"] %></p>
+  </div>
+
+  <% if @job["backtrace"].present? %>
+    <div class="rounded-lg bg-white shadow ring-1 ring-gray-200 p-6 mb-6">
+      <h2 class="text-sm font-medium text-gray-500 mb-2">Backtrace</h2>
+      <pre class="text-xs text-gray-600 bg-gray-50 rounded p-4 overflow-x-auto max-h-96"><%= @job["backtrace"] %></pre>
+    </div>
+  <% end %>
+
+  <div class="rounded-lg bg-white shadow ring-1 ring-gray-200 p-6 mb-6">
+    <h2 class="text-sm font-medium text-gray-500 mb-2">Payload</h2>
+    <pre class="text-xs text-gray-600 bg-gray-50 rounded p-4 overflow-x-auto"><%= JSON.pretty_generate(JSON.parse(@job["payload"])) rescue @job["payload"] %></pre>
+  </div>
+
+  <div class="flex space-x-2">
+    <%= button_to "Retry", pgbus.retry_job_path(@job["id"]), method: :post,
+          class: "rounded-md bg-indigo-600 px-4 py-2 text-sm font-medium text-white hover:bg-indigo-500" %>
+    <%= button_to "Discard", pgbus.discard_job_path(@job["id"]), method: :post,
+          class: "rounded-md bg-red-600 px-4 py-2 text-sm font-medium text-white hover:bg-red-500",
+          data: { turbo_confirm: "Discard this job permanently?" } %>
+  </div>
+<% else %>
+  <div class="text-center py-12">
+    <p class="text-gray-400">Job not found</p>
+  </div>
+<% end %>

data/app/views/pgbus/processes/_processes_table.html.erb

@@ -0,0 +1,37 @@
+<turbo-frame id="processes-list" data-auto-refresh src="<%= pgbus.processes_path(frame: 'list') %>">
+  <div class="overflow-hidden rounded-lg bg-white shadow ring-1 ring-gray-200">
+    <table class="min-w-full divide-y divide-gray-200">
+      <thead class="bg-gray-50">
+        <tr>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Kind</th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Hostname</th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">PID</th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Status</th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Last Heartbeat</th>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Metadata</th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-100">
+        <% @processes.each do |p| %>
+          <tr class="hover:bg-gray-50">
+            <td class="px-4 py-3 text-sm font-medium text-gray-900"><%= p[:kind] %></td>
+            <td class="px-4 py-3 text-sm text-gray-700"><%= p[:hostname] %></td>
+            <td class="px-4 py-3 text-sm font-mono text-gray-700"><%= p[:pid] %></td>
+            <td class="px-4 py-3 text-sm"><%= pgbus_status_badge(p[:healthy]) %></td>
+            <td class="px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(p[:last_heartbeat_at]) %></td>
+            <td class="px-4 py-3 text-sm text-gray-500 font-mono text-xs max-w-xs truncate">
+              <% if p[:metadata].is_a?(Hash) %>
+                <% p[:metadata].each do |k, v| %>
+                  <span class="inline-flex items-center rounded bg-gray-100 px-1.5 py-0.5 text-xs mr-1"><%= k %>: <%= v %></span>
+                <% end %>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
+        <% if @processes.empty? %>
+          <tr><td colspan="6" class="px-4 py-8 text-center text-sm text-gray-400">No processes running</td></tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</turbo-frame>

data/app/views/pgbus/processes/index.html.erb

@@ -0,0 +1,3 @@
+<h1 class="text-2xl font-bold text-gray-900 mb-6">Processes</h1>
+
+<%= render "pgbus/processes/processes_table" %>

data/app/views/pgbus/queues/_queues_list.html.erb

@@ -0,0 +1,41 @@
+<turbo-frame id="queues-list" data-auto-refresh src="<%= pgbus.queues_path(frame: 'list') %>">
+  <div class="overflow-hidden rounded-lg bg-white shadow ring-1 ring-gray-200">
+    <table class="min-w-full divide-y divide-gray-200">
+      <thead class="bg-gray-50">
+        <tr>
+          <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Queue</th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Depth</th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Visible</th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Oldest (s)</th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Newest (s)</th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Total Ever</th>
+          <th class="px-4 py-3 text-right text-xs font-medium uppercase text-gray-500">Actions</th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-gray-100">
+        <% @queues.each do |q| %>
+          <tr class="hover:bg-gray-50">
+            <td class="px-4 py-3 text-sm">
+              <%= link_to q[:name], pgbus.queue_path(name: q[:name]), class: "font-medium text-indigo-600 hover:text-indigo-500", data: { turbo_frame: "_top" } %>
+              <%= pgbus_queue_badge(q[:name]) %>
+            </td>
+            <td class="px-4 py-3 text-sm text-right font-mono text-gray-700"><%= pgbus_number(q[:queue_length]) %></td>
+            <td class="px-4 py-3 text-sm text-right font-mono text-gray-700"><%= pgbus_number(q[:queue_visible_length]) %></td>
+            <td class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:oldest_msg_age_sec] || "—" %></td>
+            <td class="px-4 py-3 text-sm text-right text-gray-500"><%= q[:newest_msg_age_sec] || "—" %></td>
+            <td class="px-4 py-3 text-sm text-right text-gray-500"><%= pgbus_number(q[:total_messages]) %></td>
+            <td class="px-4 py-3 text-sm text-right">
+              <%= button_to "Purge", pgbus.purge_queue_path(name: q[:name]),
+                    method: :post,
+                    class: "text-xs text-red-600 hover:text-red-800 font-medium",
+                    data: { turbo_confirm: "Purge all messages from #{q[:name]}?", turbo_frame: "_top" } %>
+            </td>
+          </tr>
+        <% end %>
+        <% if @queues.empty? %>
+          <tr><td colspan="7" class="px-4 py-8 text-center text-sm text-gray-400">No queues found</td></tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+</turbo-frame>

data/app/views/pgbus/queues/index.html.erb

@@ -0,0 +1,3 @@
+<h1 class="text-2xl font-bold text-gray-900 mb-6">Queues</h1>
+
+<%= render "pgbus/queues/queues_list" %>

data/app/views/pgbus/queues/show.html.erb

@@ -0,0 +1,49 @@
+<div class="flex items-center justify-between mb-6">
+  <div>
+    <h1 class="text-2xl font-bold text-gray-900"><%= @queue&.dig(:name) || params[:name] %></h1>
+    <% if @queue %>
+      <p class="text-sm text-gray-500 mt-1">
+        Depth: <span class="font-mono"><%= @queue[:queue_length] %></span> |
+        Visible: <span class="font-mono"><%= @queue[:queue_visible_length] %></span> |
+        Total: <span class="font-mono"><%= pgbus_number(@queue[:total_messages]) %></span>
+      </p>
+    <% end %>
+  </div>
+  <div class="flex space-x-2">
+    <%= button_to "Purge Queue", pgbus.purge_queue_path(name: params[:name]),
+          method: :post,
+          class: "rounded-md bg-red-600 px-3 py-2 text-sm font-medium text-white hover:bg-red-500",
+          data: { turbo_confirm: "Purge all messages?" } %>
+  </div>
+</div>
+
+<!-- Messages in Queue -->
+<div class="overflow-hidden rounded-lg bg-white shadow ring-1 ring-gray-200">
+  <table class="min-w-full divide-y divide-gray-200">
+    <thead class="bg-gray-50">
+      <tr>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">ID</th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Enqueued</th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Reads</th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">VT</th>
+        <th class="px-4 py-3 text-left text-xs font-medium uppercase text-gray-500">Payload</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-100">
+      <% @messages.each do |m| %>
+        <tr class="hover:bg-gray-50">
+          <td class="px-4 py-3 text-sm font-mono text-gray-900"><%= m[:msg_id] %></td>
+          <td class="px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(m[:enqueued_at]) %></td>
+          <td class="px-4 py-3 text-sm text-gray-500"><%= m[:read_ct] %></td>
+          <td class="px-4 py-3 text-sm text-gray-500"><%= pgbus_time_ago(m[:vt]) %></td>
+          <td class="px-4 py-3 text-sm text-gray-600 font-mono text-xs max-w-md truncate">
+            <%= pgbus_json_preview(m[:message]) %>
+          </td>
+        </tr>
+      <% end %>
+      <% if @messages.empty? %>
+        <tr><td colspan="5" class="px-4 py-8 text-center text-sm text-gray-400">Queue is empty</td></tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/bun.lock

@@ -0,0 +1,18 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 0,
+  "workspaces": {
+    "": {
+      "devDependencies": {
+        "playwright": "^1.50.0",
+      },
+    },
+  },
+  "packages": {
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
+    "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": "cli.js" }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
+
+    "playwright-core": ["playwright-core@1.58.2", "", { "bin": "cli.js" }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
+  }
+}

data/config/routes.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+Pgbus::Engine.routes.draw do
+  root to: "dashboard#show"
+
+  resources :queues, only: %i[index show], param: :name do
+    member do
+      post :purge
+    end
+  end
+
+  resources :jobs, only: %i[index show] do
+    member do
+      post :retry
+      post :discard
+    end
+    collection do
+      post :retry_all
+      post :discard_all
+    end
+  end
+
+  resources :processes, only: [:index]
+
+  resources :events, only: %i[index show] do
+    member do
+      post :replay
+    end
+  end
+
+  resources :dead_letter, only: %i[index show], path: "dlq" do
+    member do
+      post :retry
+      post :discard
+    end
+    collection do
+      post :retry_all
+      post :discard_all
+    end
+  end
+
+  namespace :api do
+    get :stats, to: "stats#show"
+  end
+end

data/docs/README.md

@@ -0,0 +1,28 @@
+# Pgbus Documentation
+
+## Migration guides
+
+Switching to Pgbus from another job backend? These guides cover what changes, what stays the same, and what to watch out for.
+
+| Guide | Backend | Key differences |
+|-------|---------|-----------------|
+| [Switch from Sidekiq](switch_from_sidekiq.md) | Sidekiq (+ Pro/Enterprise) | Remove Redis, convert native workers to ActiveJob, replace middleware with callbacks |
+| [Switch from SolidQueue](switch_from_solid_queue.md) | SolidQueue | Similar architecture (PostgreSQL + `SKIP LOCKED`), swap config format, gain LISTEN/NOTIFY + worker recycling |
+| [Switch from GoodJob](switch_from_good_job.md) | GoodJob | Both PostgreSQL-native with LISTEN/NOTIFY, swap advisory locks for PGMQ visibility timeouts, gain worker recycling |
+
+## Feature comparison
+
+| Feature | Sidekiq | SolidQueue | GoodJob | Pgbus |
+|---------|---------|------------|---------|-------|
+| Infrastructure | Redis | PostgreSQL | PostgreSQL | PostgreSQL (PGMQ) |
+| ActiveJob adapter | Yes | Yes | Yes | Yes |
+| Bulk enqueue | No | Yes | Yes | Yes |
+| LISTEN/NOTIFY | N/A | No (polling only) | Yes | Yes |
+| Dead letter queues | No (retries only) | No | No | Yes |
+| Worker recycling | No | No | No | Yes |
+| Event bus | No | No | No | Yes |
+| Idempotent events | No | No | No | Yes |
+| Concurrency controls | Enterprise | `limits_concurrency` | `good_job_control_concurrency_with` | `Pgbus::Concurrency` |
+| Recurring/cron jobs | `sidekiq-cron` gem | `config/recurring.yml` | `config.good_job.cron` | Planned |
+| Batches | Pro | No | `GoodJob::Batch` | `Pgbus::Batch` |
+| Web dashboard | `Sidekiq::Web` | Mission Control | `GoodJob::Engine` | `Pgbus::Engine` |

data/docs/switch_from_good_job.md

@@ -0,0 +1,279 @@
+# Switch from GoodJob to Pgbus
+
+## Overview
+
+GoodJob and Pgbus are both PostgreSQL-native job processors with LISTEN/NOTIFY support. The biggest architectural difference: GoodJob uses advisory locks and a `good_jobs` table, while Pgbus uses PGMQ (a dedicated message queue extension) with visibility timeouts. Both are pure ActiveJob adapters.
+
+**Effort estimate:** Low if you use standard ActiveJob. Medium if you rely on GoodJob's concurrency controls, batches, or cron.
+
+## Step 1: Update dependencies
+
+```ruby
+# Gemfile
+
+# Remove
+gem "good_job"
+
+# Add
+gem "pgbus"
+```
+
+```bash
+bundle install
+rails generate pgbus:install
+rails db:migrate
+```
+
+## Step 2: Switch the adapter
+
+```ruby
+# config/application.rb
+
+# Before
+config.active_job.queue_adapter = :good_job
+
+# After
+config.active_job.queue_adapter = :pgbus
+```
+
+Remove GoodJob configuration:
+
+```ruby
+# Before: Remove this block
+config.good_job = {
+  execution_mode: :async,
+  queues: "critical:5;default:3;*:1",
+  max_threads: 5,
+  poll_interval: 10,
+  enable_cron: true,
+  enable_listen_notify: true,
+  # ...
+}
+```
+
+## Step 3: Convert worker configuration
+
+```ruby
+# Before: GoodJob config (in application.rb or environment files)
+config.good_job = {
+  execution_mode: :external,  # or :async
+  queues: "critical:5;default:3;low:1",
+  poll_interval: 10,
+  max_threads: 5,
+  shutdown_timeout: 30,
+}
+```
+
+```yaml
+# After: config/pgbus.yml
+production:
+  workers:
+    - queues: [critical]
+      threads: 5
+    - queues: [default]
+      threads: 3
+    - queues: [low]
+      threads: 1
+  max_retries: 5
+  max_jobs_per_worker: 10000
+  max_memory_mb: 512
+  max_worker_lifetime: 3600
+```
+
+### Configuration mapping
+
+| GoodJob | Pgbus | Notes |
+|---------|-------|-------|
+| `execution_mode: :external` | `bundle exec pgbus start` | Separate process (recommended for production) |
+| `execution_mode: :async` | N/A | Pgbus always runs as separate processes |
+| `queues: "critical:5;default:3"` | `workers:` array | One entry per worker process |
+| `max_threads` | `threads` per worker | Per-worker, not global |
+| `poll_interval` | `polling_interval` | Pgbus defaults to 0.1s; LISTEN/NOTIFY is primary |
+| `enable_listen_notify` | `listen_notify` | Both support LISTEN/NOTIFY |
+| `shutdown_timeout` | Handled by supervisor | Graceful shutdown on SIGTERM |
+| `on_thread_error` | Configure via `Pgbus.logger` | Error reporting via logging |
+| `preserve_job_records` | Always archived | PGMQ archives completed messages |
+
+## Step 4: Remove concurrency controls
+
+GoodJob's concurrency extensions are GoodJob-specific. Remove them:
+
+```ruby
+# Before
+class ProcessOrderJob < ApplicationJob
+  include GoodJob::ActiveJobExtensions::Concurrency
+
+  good_job_control_concurrency_with(
+    total_limit: 1,
+    enqueue_limit: 2,
+    perform_limit: 1,
+    enqueue_throttle: [10, 1.minute],
+    perform_throttle: [100, 1.hour],
+    key: -> { "ProcessOrder-#{arguments.first.id}" }
+  )
+
+  def perform(order)
+    # ...
+  end
+end
+```
+
+```ruby
+# After
+class ProcessOrderJob < ApplicationJob
+  def perform(order)
+    # ...
+  end
+end
+```
+
+> Pgbus supports concurrency controls via `Pgbus::Concurrency`:
+> ```ruby
+> class ProcessOrderJob < ApplicationJob
+>   include Pgbus::Concurrency
+>   limits_concurrency to: 1,
+>                      key: -> { "ProcessOrder-#{arguments.first.id}" },
+>                      duration: 15.minutes,
+>                      on_conflict: :block
+>   def perform(order)
+>     # ...
+>   end
+> end
+> ```
+
+## Step 5: Migrate batches
+
+If you use `GoodJob::Batch`:
+
+```ruby
+# Before: GoodJob batches
+GoodJob::Batch.enqueue(
+  on_finish: BatchCallbackJob,
+  on_success: SuccessNotifyJob,
+  description: "Import users"
+) do
+  users.each { |u| ImportUserJob.perform_later(u) }
+end
+```
+
+Pgbus does not yet have batch support. Workaround using a coordinator job:
+
+```ruby
+# After: Coordinator pattern
+class ImportUsersJob < ApplicationJob
+  def perform(user_ids)
+    user_ids.each { |id| ImportUserJob.perform_later(id) }
+    # Track completion via a counter in the database or Redis
+  end
+end
+```
+
+## Step 6: Migrate cron / recurring jobs
+
+```ruby
+# Before: GoodJob cron
+config.good_job.enable_cron = true
+config.good_job.cron = {
+  daily_cleanup: {
+    cron: "0 2 * * *",
+    class: "CleanupJob",
+    set: { priority: -10, queue: "maintenance" },
+  },
+  hourly_sync: {
+    cron: "0 * * * *",
+    class: "SyncJob",
+    args: [42],
+  }
+}
+```
+
+Pgbus does not yet have built-in recurring task support. Options:
+
+1. **Use the `whenever` gem**:
+   ```ruby
+   # config/schedule.rb
+   every 1.day, at: "2:00 am" do
+     runner "CleanupJob.perform_later"
+   end
+   every :hour do
+     runner "SyncJob.perform_later(42)"
+   end
+   ```
+
+2. **Use system cron** directly:
+   ```cron
+   0 2 * * * cd /app && bin/rails runner "CleanupJob.perform_later"
+   0 * * * * cd /app && bin/rails runner "SyncJob.perform_later(42)"
+   ```
+
+3. Wait for Pgbus recurring task support (planned).
+
+## Step 7: Replace the dashboard
+
+```ruby
+# Before: config/routes.rb
+mount GoodJob::Engine => "good_job"
+
+# After:
+mount Pgbus::Engine => "/pgbus"
+```
+
+## Step 8: Update process management
+
+```bash
+# Before (external mode)
+bundle exec good_job start
+
+# After
+bundle exec pgbus start
+```
+
+If you ran GoodJob in `async` mode (in-process), note that Pgbus always runs as separate forked processes managed by a supervisor. Update your deployment accordingly -- you need `bundle exec pgbus start` as a separate process.
+
+## Step 9: Clean up GoodJob tables
+
+After verifying Pgbus is processing correctly and GoodJob's tables are drained:
+
+```ruby
+class RemoveGoodJob < ActiveRecord::Migration[7.1]
+  def up
+    drop_table :good_jobs, if_exists: true
+    drop_table :good_job_batches, if_exists: true
+    drop_table :good_job_executions, if_exists: true
+    drop_table :good_job_processes, if_exists: true
+    drop_table :good_job_settings, if_exists: true
+  end
+end
+```
+
+## What you gain
+
+- **Dead letter queues** -- GoodJob retries in-place and marks jobs as discarded. Pgbus routes failures to dedicated `_dlq` queues for clear operational visibility.
+- **Worker recycling** -- GoodJob workers run indefinitely. Pgbus recycles by job count, memory, or lifetime to prevent memory bloat.
+- **Event bus** -- AMQP-style pub/sub with topic routing and idempotent handlers.
+- **PGMQ** -- purpose-built message queue extension with atomic read/archive/delete, visibility timeouts, and `SKIP LOCKED` under the hood.
+- **Supervisor/fork model** -- isolated worker processes. A memory leak or crash in one worker doesn't affect others.
+
+## What you lose (for now)
+
+| GoodJob feature | Status in Pgbus |
+|-----------------|-----------------|
+| Concurrency controls (`good_job_control_concurrency_with`) | `Pgbus::Concurrency` with `limits_concurrency` DSL |
+| Throttling (`enqueue_throttle`, `perform_throttle`) | Planned |
+| Batches (`GoodJob::Batch`) | `Pgbus::Batch` with on_finish/on_success/on_discard callbacks |
+| Cron / recurring jobs | Planned |
+| Async execution mode (in-process) | Not planned (forked processes only) |
+| Capsules (isolated thread pools) | Workers are isolated by design (forked processes) |
+| Advisory locks | Replaced by PGMQ visibility timeouts |
+
+## Gotchas
+
+1. **PgBouncer**: Both GoodJob and Pgbus use LISTEN/NOTIFY, which requires session-mode PgBouncer or direct connections. If you already had GoodJob working with PgBouncer, the same configuration applies.
+
+2. **No async mode**: GoodJob can run in-process (`:async` mode) alongside your Rails app server. Pgbus requires a separate supervisor process. Make sure your deployment runs `bundle exec pgbus start` alongside your web server.
+
+3. **Advisory locks vs. visibility timeouts**: GoodJob uses PostgreSQL advisory locks to claim jobs. Pgbus uses PGMQ's visibility timeout -- a claimed message becomes invisible for `visibility_timeout` seconds. If a worker crashes without archiving the message, it automatically becomes available again after the timeout expires. This is more resilient than advisory locks, which release on disconnect.
+
+4. **Job record preservation**: GoodJob has `preserve_job_records` for keeping completed job records. PGMQ automatically archives completed messages to `a_pgbus_*` tables, which serve a similar purpose for debugging and auditing.
+
+5. **Queue naming**: GoodJob uses bare queue names. Pgbus prefixes all queues (`pgbus_default`). Your `queue_as` declarations work unchanged -- the prefix is applied automatically.