Getting started

# Overview

pgbus is PostgreSQL-native job processing and an event bus for Rails, built on PGMQ. Jobs, events, and live updates all run in the database you already have.

## One database, no Redis

The whole point.

Most Rails job backends bolt on infrastructure: Sidekiq needs Redis, and turbo-rails broadcasts need Action Cable (and Redis again). pgbus needs **one PostgreSQL** — the database your app already runs — and layers jobs, a pub/sub event bus, and Server-Sent-Event streams on top of [PGMQ](https://github.com/pgmq/pgmq), a lightweight message-queue extension.

That means one thing to provision, one thing to back up, one thing to monitor. Enqueues participate in your database transactions. And the durability guarantees are Postgres's, not a separate broker's.

> **Note:** PGMQ can run as a PostgreSQL extension or as vendored, embedded SQL (no extension required). See [Installation](https://pgbus.zoolutions.llc/docs/installation) for the schema modes.

## What you get

- **A drop-in ActiveJob adapter** — set the adapter to `:pgbus` and your existing jobs enqueue through PGMQ, with dead-letter routing and retry backoff you didn't have to write.
- **An event bus** — publish once; AMQP-style topic patterns (`orders.#`, `payments.*`) fan out to idempotent subscribers, deduplicated by event id.
- **Workers that recycle** — `max_jobs_per_worker`, `max_memory_mb`, and `max_worker_lifetime` retire a worker before it leaks, fixing the memory-bloat problem other backends leave to you.
- **Reliability primitives** — dead-letter queues, a circuit breaker, job uniqueness, concurrency limits, priority queues, and a transactional outbox.
- **Real-time streams** — a Turbo Streams transport over Postgres SSE, with no Action Cable and no lost messages on reconnect.
- **A live dashboard** — queues, jobs, processes, failures, and dead letters, auto-refreshing over Turbo Frames (no WebSocket).

## How it compares

Against the common Rails job backends.

| Feature | Sidekiq | SolidQueue | GoodJob | pgbus |
| --- | --- | --- | --- | --- |
| Infrastructure | Redis | PostgreSQL | PostgreSQL | `PostgreSQL (PGMQ)` |
| ActiveJob adapter | Yes | Yes | Yes | Yes |
| LISTEN/NOTIFY | N/A | Polling only | Yes | Yes |
| Dead letter queues | 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` | Yes | `Pgbus::Concurrency` |
| Recurring / cron jobs | `sidekiq-cron` | `recurring.yml` | Yes | Built in — [recurring tasks](https://pgbus.zoolutions.llc/docs/recurring-tasks) |
| Batches | Pro | No | `GoodJob::Batch` | `Pgbus::Batch` |
| Web dashboard | Yes | Mission Control | Yes | `Pgbus::Engine` |
| Turbo Streams transport | Cable (Redis) | Cable | Cable | Built-in SSE |
| Lost messages on reconnect | Yes | Yes | Yes | No (msg_id cursor) |
| Transactional broadcasts | No | No | No | Yes (until commit) |

> **Tip:** Coming from another backend? The migration guides cover what changes and what stays the same: [Sidekiq](https://pgbus.zoolutions.llc/docs/from-sidekiq), [SolidQueue](https://pgbus.zoolutions.llc/docs/from-solid-queue), [GoodJob](https://pgbus.zoolutions.llc/docs/from-good-job).

## Where to next

- New here? Start with [Installation](https://pgbus.zoolutions.llc/docs/installation), then the [Quick start](https://pgbus.zoolutions.llc/docs/quick-start).
- Want the mental model first? Read [Architecture](https://pgbus.zoolutions.llc/docs/architecture).
- Looking for a specific capability? The **Guide** covers the [ActiveJob adapter](https://pgbus.zoolutions.llc/docs/active-job), the [event bus](https://pgbus.zoolutions.llc/docs/event-bus), [retries & dead letters](https://pgbus.zoolutions.llc/docs/retries-dead-letters), and more.