54. pepsi-queue

Inspect and repair the ingress message queue.

54.1. Role

pepsi-queue is the operator’s diagnostic and repair tool for the pepsi.ingress 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).

54.2. Features

• list — list queued messages ordered by ingress_id, optionally as --json (ingress_id, stage, status, mail_from, subject, received_at, state), with --limit, --stage and --status filters.

• delete — permanently remove a message by ingress_id.

• set-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.

The mutating subcommands act immediately, are not reversible, and emit no database notification (so they are safe to run while the pipeline is idle).

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

54.4. See also

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