Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NikolayS/PgQue/llms.txt

Use this file to discover all available pages before exploring further.

The dead letter queue (DLQ) stores messages that have exhausted their retry budget. When nack() is called and retry_count >= max_retries, the event is routed to pgque.dead_letter instead of being re-queued. This reference covers the table schema and all DLQ management functions.

​
pgque.dead_letter table

ColumnTypeNullableNotes
dl_idbigserialnoPrimary key
dl_queue_idint4noFK to pgque.queue, ON DELETE CASCADE
dl_consumer_idint4noFK to pgque.consumer, ON DELETE CASCADE
dl_timetimestamptznoWhen the message was dead-lettered (default now())
dl_reasontextyesReason passed to nack()
ev_idbigintnoOriginal event id
ev_timetimestamptznoOriginal event creation time
ev_txidxid8yesTransaction id of the original insert
ev_retryint4yesRetry count when dead-lettered
ev_typetextyesEvent type
ev_datatextyesEvent payload
ev_extra1textyesExtra column 1
ev_extra2textyesExtra column 2
ev_extra3textyesExtra column 3
ev_extra4textyesExtra column 4
pgque_reader has SELECT on this table. pgque_admin has full access.

​
dlq_inspect

pgque.dlq_inspect(queue text, limit_count int default 100) → setof pgque.dead_letter
Returns the most recent dead-letter rows for queue, newest first. Grant: pgque_reader. 
select dl_id, dl_reason, ev_type, ev_data
from pgque.dlq_inspect('orders');

-- Inspect more rows
select * from pgque.dlq_inspect('orders', 500);

​
dlq_replay

pgque.dlq_replay(dead_letter_id bigint) → bigint
Re-inserts one dead-letter entry into its original queue and removes it from pgque.dead_letter. Returns the new event id. Grant: pgque_writer. 
select pgque.dlq_replay(42);  -- returns the new ev_id
The replayed event is a fresh insert — it gets a new ev_id and will be delivered on the next tick.

​
dlq_replay_all

pgque.dlq_replay_all(queue text) → (replayed bigint, failed bigint, first_error text)
Replays every dead-letter entry for queue. Per-event failures are isolated — one bad row does not abort the rest. Grant: pgque_writer. 
select replayed, failed, first_error
from pgque.dlq_replay_all('orders');
first_error carries the first failure’s dl_id and sqlerrm for diagnostics. Failed entries are counted in failed and remain in the DLQ.

​
dlq_purge

pgque.dlq_purge(queue text, older_than interval default '30 days') → integer
Deletes dead-letter rows older than older_than for queue. Returns the row count deleted. Grant: pgque_admin.
dlq_purge is destructive. Inspect entries with dlq_inspect before purging.
-- Delete entries older than 7 days
select pgque.dlq_purge('orders', interval '7 days');

-- Delete all entries for a queue
select pgque.dlq_purge('orders', interval '0 seconds');

​
event_dead (internal)

pgque.event_dead(batch_id, event_id, reason, ev_time, ev_txid, ev_retry, ev_type, ev_data, ...) → integer
Inserts one row into pgque.dead_letter. Called internally by pgque.nack() when retries are exhausted — direct calls are rarely needed. Grant: pgque_admin.

Build docs developers (and LLMs) love

Get started for freeTalk to us