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.

These are the raw PgQ primitives that the modern send/receive/ack/nack API wraps. Most callers should use the modern API instead. Primitives are useful for advanced integrations, custom batch logic, or when you need direct access to tick boundaries.
Prefer pgque.send(), pgque.receive(), pgque.ack(), and pgque.nack() for new code. The primitives are available for advanced use cases and are what the modern API delegates to internally.

​
insert_event

pgque.insert_event(queue_name text, ev_type text, ev_data text) → bigint
pgque.insert_event(queue_name text, ev_type text, ev_data text,
                   ev_extra1 text, ev_extra2 text, ev_extra3 text, ev_extra4 text) → bigint
Inserts one event. The 3-argument form leaves all ev_extra* columns null. Returns the event id. Grant: pgque_writer.

​
register_consumer / unregister_consumer

pgque.register_consumer(queue_name text, consumer_id text) → integer
pgque.register_consumer_at(queue_name text, consumer_name text, tick_pos bigint) → integer
pgque.unregister_consumer(queue_name text, consumer_name text) → integer
register_consumer starts the consumer from the most recent tick. register_consumer_at positions it at a specific historical tick id. unregister_consumer removes the subscription and its retry-queue entries — cooperative-aware: raises if the consumer is a coop_main with registered subconsumers. Grant: pgque_reader for all three.

​
next_batch / next_batch_info / next_batch_custom

pgque.next_batch(queue_name text, consumer_name text) → bigint
pgque.next_batch_info(queue_name text, consumer_name text) → record
pgque.next_batch_custom(queue_name text, consumer_name text,
                        min_lag interval, min_count int4, min_interval interval) → record
next_batch activates the next batch and returns its id, or NULL if no events are ready. next_batch_info returns the same plus tick bounds. next_batch_custom adds size and age constraints. Out columns for next_batch_info and next_batch_custom: batch_id, cur_tick_id, prev_tick_id, cur_tick_time, prev_tick_time, cur_tick_event_seq, prev_tick_event_seq. Grant: pgque_reader.

​
get_batch_events

pgque.get_batch_events(batch_id bigint) → setof record
Streams all events in a batch. Out columns: ev_id bigint, ev_time timestamptz, ev_txid bigint, ev_retry int4, ev_type text, ev_data text, ev_extra1 text, ev_extra2 text, ev_extra3 text, ev_extra4 text. Grant: pgque_reader.

​
get_batch_cursor

pgque.get_batch_cursor(batch_id bigint, cursor_name text, quick_limit int4) → setof record
pgque.get_batch_cursor(batch_id bigint, cursor_name text, quick_limit int4, extra_where text) → setof record
Declares a server-side cursor over the batch and returns the first quick_limit events. Fetch remaining events with FETCH … FROM <cursor_name>. Grant: pgque_admin only.
The extra_where argument is a trusted SQL fragment concatenated verbatim into the cursor query — not a parameter. Never pass user-controlled input as extra_where. If you need application-driven filtering, use get_batch_events() and filter in application code or a separate parameterized query.

​
finish_batch

pgque.finish_batch(batch_id bigint) → integer
Closes the batch and advances the consumer’s last_tick. Returns 1 on success, 0 with a warning if the batch was not found. Cooperative-aware: coop_member batches clear the member cursor; coop_main batches are rejected. Grant: pgque_reader.

​
event_retry / batch_retry

pgque.event_retry(batch_id bigint, event_id bigint, retry_time timestamptz) → integer
pgque.event_retry(batch_id bigint, event_id bigint, retry_seconds integer) → integer
pgque.batch_retry(batch_id bigint, retry_seconds integer) → integer
event_retry puts one event back onto the retry queue. batch_retry re-queues every event in the batch. Returns 1 on success per event, 0 if already queued. Grant: pgque_reader for event_retry; pgque_admin for batch_retry.

​
CDC trigger helpers

Attach these trigger functions to any table to automatically enqueue an event on every INSERT/UPDATE/DELETE. Grant: pgque_admin. 
-- Attach jsontriga to a table
create trigger orders_pgque
after insert or update or delete on orders
for each row execute procedure pgque.jsontriga('events');

​
jsontriga

Emits row data as JSON. ev_data is the JSON blob; ev_extra1 is the fully-qualified table name. Supports optional trigger args: SKIP, backup, ignore=col, pkey=col, when=expr, ev_type=expr, ev_extra1..4=expr.

​
logutriga

Emits row data as URL-encoded key/value pairs (key1=v1&key2=v2). Useful for legacy pipelines that already consume logutriga format.

​
sqltriga

Emits row data as ready-to-apply SQL: INSERT … VALUES …, UPDATE … SET … WHERE …, or DELETE FROM … WHERE … in ev_data.

​
Cooperative consumer primitives

Cooperative consumers are experimental. APIs may change before promotion to stable.
pgque.register_subconsumer(queue, consumer, subconsumer, convert_normal boolean default false) → integer
pgque.unregister_subconsumer(queue, consumer, subconsumer, batch_handling integer default 0) → integer
pgque.receive_coop(queue, consumer, subconsumer, max_return int default 100, dead_interval interval default null) → setof pgque.message
pgque.next_batch(queue, consumer, subconsumer, dead_interval interval default null) → bigint
pgque.next_batch_custom(queue, consumer, subconsumer, min_lag, min_count, min_interval, dead_interval default null) → record
pgque.touch_subconsumer(queue, consumer, subconsumer) → integer
subscribe_subconsumer and unsubscribe_subconsumer are aliases for register_subconsumer and unregister_subconsumer. See the fan-out guide for usage patterns. Grant: pgque_reader.

Build docs developers (and LLMs) love

Get started for freeTalk to us