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.

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.

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.

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

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.

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.

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

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.

Run these after db:schema:load, which drops ALTER TABLE settings. See Performance & tuning.