Running workers

Supervisor#run logs a one-block banner right after the heartbeat starts and before queues bootstrap — every "[Pgbus] boot:"-prefixed line renders cleanly under both the :text and :json log formatters:

It states the version, the connection target (host/dbname only — never the password, across the database_url, connection_params, and ActiveRecord-derived connection forms), the resolved pool size, the PGMQ schema mode and installed version, LISTEN/NOTIFY status, the roles that will actually boot, and one line per worker capsule and event consumer.

Workers wake instantly on job inserts via a persistent LISTEN connection. That connection must bypass a transaction-pooling PgBouncer (LISTEN does not survive transaction boundaries), so it lands on the direct port's scarce max_connections budget.

By default (worker_notify_scope = :supervisor) the supervisor owns one shared listener for the whole host: it LISTENs on the union of every capsule's and consumer's queue channels and wakes the right fork(s) over a per-fork pipe. A job host pins exactly one direct LISTEN connection, regardless of how many capsules and consumers it runs.

Health is fail-safe in both directions: if the shared connection dies, the supervisor broadcasts a degraded signal and every fork drops to fast polling until the listener reconnects (typically well under a second); if the supervisor itself disappears, the pipes reach EOF and forks keep processing on plain polling. pgbus doctor's Connection budget check prints the pinned count for the current config, and the connections are census-tagged for capacity audits:

By default pgbus start boots every role in one supervisor. For containerized deployments where each role is its own process, use the role flags (mutually exclusive) and, optionally, a single capsule:

pgbus workers retire themselves before they leak — the main reliability difference from backends that leave workers alive forever. When a limit is hit, the worker drains its thread pool, exits, and the supervisor forks a fresh process:

RSS is sampled from /proc/self/statm on Linux and ps -o rss on macOS.

A capsule can set its own limits. They apply to that capsule's workers only; any limit it leaves unset (or nil) falls back to the global value:

Ruby threads in one process share the GVL. Threads help when jobs wait on I/O; they do not help when jobs burn CPU (rendering, reports, PDFs, images), where a capsule with threads: 8 still uses about one core. processes: N forks N identical workers for one capsule, each with its own GVL:

• I/O-bound jobs: threads: (or execution_mode: :async), processes: 1.
• CPU-bound jobs: processes: up to the cores you can give the capsule, threads: 1–2.

All forks read the same queues with FOR UPDATE SKIP LOCKED, so uniqueness and concurrency controls behave as with one process. Each fork has its own restart backoff, liveness pipe and pgbus_processes row; a crashed fork restarts alone. The boot banner prints processes=N, readiness counts every fork, and the Processes page labels each row capsule render · process 2/4.

Budget boot RSS + peak job RSS per process; the forks share the booted app copy-on-write until they write to it. Every process has its own pool, so a host holds about processes × pool_size connections for the capsule. Under the default worker_notify_scope: :supervisor the host still holds one LISTEN connection; under :fork each fork holds its own. With single_active_consumer: true each queue is locked by one fork at a time; a fork can still process the capsule's other queues, so in a single-queue capsule the extra forks are hot standbys.

When to reach for which, with worked examples: Sizing capsules.

A queue that fails repeatedly is auto-paused with exponential backoff, so a broken dependency doesn't burn the whole fleet retrying. It auto-resumes after the backoff and resets; continued failures double the backoff:

The circuit breaker above (Pgbus::CircuitBreaker) is per-queue and persists its pause state in the database — so it's useless when the database itself is down; its check_paused rescues and returns false, tripping nothing. Pgbus::Client::ConnectionHealth is a separate, in-memory, process-local latch owned by Pgbus::Client for exactly that case: it trips on repeated connection failures, not job failures, and needs no database access to operate (it can't — the database is down).

ConnectionHealth trips open after 5 consecutive connection errors across any operation. Once open, read paths (read_message, read_batch, read_multi, read_grouped*, read_with_poll) fail fast with Pgbus::ConnectionCircuitOpenError without checking out a pool connection — no wasted connection attempt, no ErrorReporter noise per poll. A single half-open probe is admitted after a monotonic backoff (1s base, doubling per re-open, capped at 60s); its success closes the breaker, its failure re-opens it with a doubled window. Enqueues (send_message / send_batch) are never short-circuited — callers must see enqueue failures rather than have them silently swallowed.

config.read_timeout (default 30 seconds) caps how long a single PGMQ read can block. On a dedicated connection (database_url or connection_params), pgbus bakes two libpq-native bounds into the connection at boot — no Ruby Timeout.timeout, which can interrupt mid-libpq-call and leave a pooled connection corrupted for the next checkout:

The client-side bound only applies on Linux with libpq ≥ 12 (older libpq rejects the tcp_user_timeout conninfo keyword; non-Linux hosts no-op it), detected automatically at connection init — no configuration needed. Ruby Timeout remains only as a narrow last resort on a dedicated connection where libpq can't bound the socket (non-Linux or libpq < 12).

Cap the number of in-flight (claimed but unfinished) messages per worker to keep a burst from overwhelming a slow downstream:

By default a worker reads as many messages as it has free threads. Once the pool is busy, threads free one at a time, so the worker makes one read round trip per job. Next to the database that is free. Across a network, that round trip becomes the ceiling. read_ahead claims up to N messages beyond the free threads and holds them until a thread frees, so one read feeds many jobs:

Start with read_ahead equal to threads. Buffered messages stay invisible (the visibility heartbeat holds them) until their job starts. On drain, recycle, pause or shutdown they go straight back to the queue, with read_ct already counted. They also count as in flight, so prefetch_limit still caps the total. The hold needs visibility_heartbeat (on by default); with it off, a message buffered past visibility_timeout can run twice.

Workers can run jobs as fibers instead of threads — ideal for I/O-bound workloads (HTTP calls, email, LLM APIs) where jobs spend their time waiting. Because fibers yield during I/O, many share a handful of connections: