Reference

# CLI & generators

The pgbus command-line interface and every Rails generator, at a glance.

## The CLI

| Command | Does |
| --- | --- |
| `pgbus start` | Boot the supervisor (workers, dispatcher, scheduler, consumers). |
| `pgbus status` | Show running processes. |
| `pgbus queues` | List queues with depth and metrics. |
| `pgbus dlq` | Inspect and drain dead-letter queues (see below). |
| `pgbus doctor` | Preflight diagnostics — gates a deploy or CI run (see below). |
| `pgbus mcp` | Start the read-only MCP diagnostic server over stdio. |
| `pgbus version` | Print the version. |
| `pgbus help` | Show help. |

## start flags

Split roles and capsules across processes.

| Flag | Does |
| --- | --- |
| `--workers-only` | Run only worker processes. |
| `--scheduler-only` | Run only the recurring-task scheduler. |
| `--dispatcher-only` | Run only the maintenance dispatcher. |
| `--capsule NAME` | Boot a single named capsule. |
| `--execution-mode async` | Run jobs as fibers instead of threads. |

> **Note:** The role flags are mutually exclusive, and the auto-tuned `pool_size` follows the role — a scheduler-only process opens only the connections it needs. See [Running workers](https://pgbus.zoolutions.llc/docs/running-workers).

## pgbus doctor

One preflight command for deploy/CI gating.

`pgbus doctor` (and the equivalent `rake pgbus:doctor`) runs six checks and prints a report — config validity, database connectivity, PGMQ schema version, configured-queue existence, LISTEN/NOTIFY triggers, and process liveness (the same `OK` / `DEGRADED` / `STALLED` verdict as the MCP `pgbus_health` tool). It never touches PGMQ or PostgreSQL directly outside `Pgbus::Client`, and it never raises — a broken environment turns every probe into a failed check instead of a crash.

| Check | Fails when |
| --- | --- |
| Configuration | `Configuration#validate!` raises. |
| Database | The DB is unreachable (a plain `SELECT 1` via `Client#ping`). |
| PGMQ schema | The schema is missing, untracked, or behind the vendored version (warn). |
| Queues | A configured queue has no PGMQ table. |
| LISTEN/NOTIFY | A configured queue is missing its insert trigger (warn — falls back to polling). |
| Process liveness | `STALLED` (silent worker wedge); `DEGRADED` only warns. |

The report ends with a resolved-config summary (queue prefix, pool size, roles, capsules) with any password redacted from `database_url` / `connection_params`.

```shell
pgbus doctor        # prints the report; exit 1 if any check failed
rake pgbus:doctor   # same checks, for a Rake-based deploy pipeline
```

> **Tip:** Warnings (an outdated PGMQ schema, a missing NOTIFY trigger) don't fail the exit code — only a failed check does. Wire `pgbus doctor` into your deploy pipeline or CI to gate on a broken environment before it reaches production.

## pgbus dlq

Dead-letter management from a headless deployment.

Every subcommand routes through `Web::DataSource`, so retry/discard semantics are identical to the dashboard — origin-queue re-enqueue, transactional produce+delete, lock release on discard — with zero raw SQL and no direct PGMQ calls.

| Subcommand | Does |
| --- | --- |
| `pgbus dlq list [--page N] [--per-page N]` | Table of msg_id / DLQ queue / origin queue / read_ct / enqueued_at, plus a total count. Never prints payloads. |
| `pgbus dlq show MSG_ID` | Message metadata plus the payload, passed through the dashboard's sensitive-data filter. |
| `pgbus dlq retry MSG_ID` | Re-enqueue one message to its origin queue. |
| `pgbus dlq retry-all` | Re-enqueue every dead-letter message; prints the count. |
| `pgbus dlq purge MSG_ID` | Discard a single message. |
| `pgbus dlq purge --all --yes` | Discard every dead-letter message. Omitting --yes makes no changes and exits 1. |

> **Warning:** An unknown `msg_id` or an unknown subcommand exits 1. `purge --all` without `--yes` is a deliberate safety rail — it refuses to purge and exits 1 rather than prompting.

## Core generators

Every generator accepts `--database=pgbus` to route its migration to `db/pgbus_migrate/` for a [separate database](https://pgbus.zoolutions.llc/docs/separate-database).

| Generator | Does |
| --- | --- |
| `pgbus:install` | Full setup — the metadata migrations, the batches table, and a starter initializer. |
| `pgbus:update` | Convert a legacy YAML config and add any missing migrations, detecting a separate DB automatically. |
| `pgbus:upgrade_pgmq` | Upgrade the embedded PGMQ schema to the latest vendored version. |

## Feature generators

Add the table for an optional feature.

| Generator | Adds |
| --- | --- |
| `pgbus:add_recurring` | Recurring-task tables + a starter `recurring.yml`. |
| `pgbus:add_outbox` | The transactional-outbox table. |
| `pgbus:add_presence` | The stream-presence table. |
| `pgbus:add_queue_states` | The queue pause/resume + circuit-breaker state table. |
| `pgbus:add_uniqueness_keys` | The job-uniqueness lock table. |
| `pgbus:add_job_stats` | The job-stats table for the Insights dashboard. |
| `pgbus:add_stream_stats` | The stream-stats table (opt-in metrics). |

> **Note:** A few migration-maintenance generators also ship for existing installs: `add_failed_events_index`, `add_job_stats_latency`, `add_job_stats_queue_index`, and `migrate_job_locks`. The `pgbus:update` generator adds whichever of these your database is missing.

## Tuning generators

Re-apply table settings a schema load drops.

| Generator | Does |
| --- | --- |
| `pgbus:tune_autovacuum` | Apply aggressive autovacuum settings to the high-churn queue tables. |
| `pgbus:tune_fillfactor` | Tune table fillfactor for existing installations. |

> **Tip:** Run these after `db:schema:load`, which drops `ALTER TABLE` settings. See [Performance & tuning](https://pgbus.zoolutions.llc/docs/performance-tuning).