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.
Lifecycle functions manage the ticker, scheduled maintenance jobs, and installation state. All require pgque_admin except version() (granted to pgque_reader). uninstall() is restricted to the schema owner / superuser.
start
Schedules four pg_cron jobs in the current database. Requires pg_cron. Idempotent — calls stop() first.
| Job name | Schedule | Purpose |
|---|
pgque_ticker | every 1 s | Calls CALL pgque.ticker_loop(), ticking every 100 ms by default |
pgque_retry_events | every 30 s | Moves nack’d events back into the main stream |
pgque_maint | every 30 s | Rotation step 1 and queue maintenance hooks |
pgque_rotate_step2 | every 10 s | Rotation step 2 (must run in its own transaction) |
stop
Unschedules the four pg_cron jobs set up by start() and clears stored job IDs. Safe to call when pg_cron is absent.
ticker_loop
pgque.ticker_loop() → (procedure)
pgque_ticker pg_cron job. Invokes pgque.ticker() every pgque.config.tick_period_ms ms inside one 1-second pg_cron slot, committing between iterations. Defined as a PROCEDURE (not a function) because only procedures support COMMIT mid-execution.
Not normally called directly. Use set_tick_period_ms() to change cadence.
set_tick_period_ms
pgque.set_tick_period_ms(ms integer) → integer
select pgque.set_tick_period_ms(50); -- 20 ticks/sec, ~25 ms median e2e
select pgque.set_tick_period_ms(100); -- 10 ticks/sec (default)
select pgque.set_tick_period_ms(1000); -- 1 tick/sec, ~500 ms median e2e
ticker
pgque.ticker() → bigint
pgque.ticker(queue text) → bigint
-- Tick all queues (used by ticker_loop)
select pgque.ticker();
-- Tick one queue
select pgque.ticker('orders');
ticker(queue, tick_id, timestamp, event_seq) exists for queues with external_ticker = true. External ticks must be monotonic.
force_next_tick
pgque.force_next_tick(queue text) → bigint
ticker_max_count and ticker_max_lag thresholds so the next ticker() call materializes a tick immediately. Does not insert a tick itself. Useful in tests and demos. Returns the current last tick id.
-- Canonical idiom: must be separate transactions
select pgque.force_next_tick('orders');
select pgque.ticker();
pgque.force_tick(queue) is an alias retained for PgQ compatibility. Prefer force_next_tick in new code.
maint
Runs one maintenance cycle: rotation step 1 plus any queue extra-maint hooks. Does not process the retry queue (call maint_retry_events() separately). Returns the count of operations performed.
maint_retry_events
pgque.maint_retry_events() → integer
pgque.retry_queue back into queue event tables so they appear in the next tick. Must be called periodically when using nack().
-- Call these in the listed order; each is its own transaction in psql autocommit
select pgque.maint_retry_events(); -- re-insert retry events
select pgque.ticker(); -- separate transaction — snapshot must be after re-insert
status
pgque.status() → table(component text, status text, detail text)
select * from pgque.status();
version
Returns the installed PgQue version string. Grant: pgque_reader.
uninstall
uninstall() calls stop() then runs DROP SCHEMA pgque CASCADE. The three roles (pgque_reader, pgque_writer, pgque_admin) are not dropped — remove them manually if desired. This function is revoked from pgque_admin and PUBLIC; only the schema/install owner (superuser) can run it.
-- Superuser only
select pgque.uninstall();
-- Remove roles manually afterward if needed
drop role pgque_reader;
drop role pgque_writer;
drop role pgque_admin;
