62. pepsi-queue

Inspect and repair the message workqueue.

62.1. Role

pepsi-queue is the operator’s diagnostic and repair tool for the pepsi.workqueue table. It connects through the shared [pepsi-postgres] section and has no configuration of its own. Started as root it continues as the pepsi service account before connecting, so no sudo -u pepsi is needed. Reference: pepsi-queue(1).

62.2. Features

• list — list queued messages ordered by workqueue_id, optionally as --json (workqueue_id, stage, status, mail_from, subject, received_at, state), with --limit (100 by default), --stage and --status filters, an optional WORKQUEUE_ID positional that restricts the output to one message, and --state-only to print each matching message’s full, un-abbreviated JSON state instead of the row summary. list is the default action, so its positional and options are also accepted bare (pepsi-queue 5, pepsi-queue --state-only 5).

• delete WORKQUEUE_ID — permanently remove a message.

• set-stage WORKQUEUE_ID STAGE — re-assign a message to a given stage and reset its status to pending (its state is left unchanged) so the new stage picks it up.

• clear-all — bulk “unstick”: reset every running/paused message back to pending (failed/timeout are left untouched) — the recovery used after a crash or a stalled stage.

• gc — garbage-collect the proof-of-origin nonce table (pepsi.origin_nonce), deleting entries whose expiration has passed, and the MX address cache (pepsi.dns_address), deleting rows whose DNS TTL has passed. Meant for a timer; the Debian package wires an hourly one.

The mutating subcommands act immediately and are not reversible. set-stage and clear-all also wake the dispatcher (pepsi.workqueue carries no notifying trigger, and these run outside the dispatcher’s own loop, so nothing else would). Run ``clear-all`` only while ``pepsi-dispatch`` is stopped: the running half names rows a live worker may still be holding, and resetting them means the same message is claimed and handled twice.

62.3. Relationship to the dispatcher

pepsi-queue manipulates the same stage/status/state columns the dispatcher acts on; clear-all complements the dispatcher’s own start-up reset of orphaned running rows. It does not start stage programs.

62.4. See also

pepsi-dispatch, Architecture, pepsi-queue(1), pepsi.conf(5).