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.
All observability functions in the default install are granted to pgque_reader. They flow up to pgque_admin but not to pgque_writer — a producer-only role cannot inspect consumer state.
get_queue_info
pgque.get_queue_info() → setof record
pgque.get_queue_info(queue text) → setof record
select * from pgque.get_queue_info();
select * from pgque.get_queue_info('orders');
| Column | Type | Description |
|---|
queue_name | text | Queue name |
queue_ntables | integer | Number of rotation tables (default 3) |
queue_cur_table | integer | Index of the currently active rotation table |
queue_rotation_period | interval | How often the hot table rotates |
queue_switch_time | timestamptz | When the last rotation occurred |
queue_external_ticker | boolean | Whether ticking is driven externally |
queue_ticker_paused | boolean | Whether the ticker is paused for this queue |
queue_ticker_max_count | integer | Force tick after N events (default 500) |
queue_ticker_max_lag | interval | Force tick after this wall time (default 3 s) |
queue_ticker_idle_period | interval | Idle tick interval (default 1 min) |
ticker_lag | interval | Wall time since the last tick — key health signal |
ev_per_sec | float8 | Recent event ingestion rate |
ev_new | bigint | Events waiting for the next tick |
last_tick_id | bigint | Most recent tick id |
get_consumer_info
pgque.get_consumer_info() → setof record
pgque.get_consumer_info(queue text) → setof record
pgque.get_consumer_info(queue text, consumer text) → setof record
NULL to widen the selection.
select * from pgque.get_consumer_info();
select * from pgque.get_consumer_info('orders');
select * from pgque.get_consumer_info('orders', 'processor');
| Column | Type | Description |
|---|
queue_name | text | Queue name |
consumer_name | text | Consumer name |
lag | interval | Age of the last finished batch — high means falling behind |
last_seen | interval | Time since the consumer last processed a batch |
last_tick | bigint | Last tick id the consumer processed |
current_batch | bigint | Active batch id (null if none open) |
next_tick | bigint | Next tick to process (null if up to date) |
pending_events | bigint | Events waiting for this consumer |
get_batch_info
pgque.get_batch_info(batch_id bigint) → record
select * from pgque.get_batch_info(42);
| Column | Type | Description |
|---|
queue_name | text | Queue name |
consumer_name | text | Consumer that owns the batch |
batch_start | timestamptz | When the batch was opened |
batch_end | timestamptz | Batch close time (null if still active) |
prev_tick_id | bigint | Start of the tick window |
tick_id | bigint | End of the tick window |
lag | interval | Age of the batch |
seq_start | bigint | Event sequence start |
seq_end | bigint | Event sequence end |
Experimental observability
These functions are not part of the default install. Load them explicitly. APIs may change before promotion to stable.
\i sql/experimental/observability.sql
| Function | Description |
|---|
pgque.queue_stats() | Per-queue depth, DLQ count, rotation age, ticker state |
pgque.consumer_stats() | Per-consumer lag, pending events, active batch info |
pgque.queue_health() | Operational checks: stuck ticker, rotation lag, DLQ growth |
pgque.otel_metrics() | OTel-compatible metric export rows (metric_name, metric_type, metric_value, labels) |
pgque.stuck_consumers(threshold interval) | Consumers idle longer than threshold (default 1 hour) |
pgque.in_flight(queue text) | Active batches per consumer with age and estimated event count |
pgque.throughput(queue, period, bucket_size) | Events/sec bucketed over a time window |
pgque.error_rate(queue, period, bucket_size) | Retries and dead letters bucketed over a time window |
