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 publishing API lets producers insert events into any PgQue queue. Single-message send wrappers delegate to pgque.insert_event; batch send_batch wrappers delegate to the internal set-based pgque.insert_event_bulk primitive. The text overloads are the fast path — bytes flow through verbatim with no JSON parse. The jsonb overloads validate and canonicalize the payload via Postgres before storing. All publishing functions require the pgque_writer role.

​
Argument names and types

Argument names are part of the SQL API because PostgreSQL supports named calls (arg := value).
ArgumentSQL typeMeaning
queue_nametextPgQue queue name.
type_nametextApplication event type stored in ev_type ('default' for 2-arg send). Free-form text such as order.created; this is not a PostgreSQL type.
payloadtext or jsonbSingle event payload. text is opaque/verbatim; jsonb validates and stores canonical JSON text.
payloadstext[] or jsonb[]Batch payload array. Result array positions correspond to input positions.

​
Overload summary

FunctionPayload typeReturn
send(queue_name, payload)text or jsonbbigint event id
send(queue_name, type_name, payload)text or jsonbbigint event id
send_batch(queue_name, payloads)text[] or jsonb[]bigint[] event ids, event type 'default'
send_batch(queue_name, type_name, payloads)text[] or jsonb[]bigint[] event ids
Use explicit casts (::jsonb, ::jsonb[], ::text[]) when overload resolution would otherwise be ambiguous. Untyped string literals choose the text fast path.

​
send — 2-argument forms

​
pgque.send(queue_name text, payload jsonb) → bigint

Inserts payload into queue_name with event type 'default'. The jsonb overload validates and canonicalizes the payload via Postgres before storing. Returns the new event id. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
payload
jsonb
required
Event payload. Validated as JSON; stored in canonical text form.
select pgque.send('orders', '{"order_id": 42}'::jsonb);

​
pgque.send(queue_name text, payload text) → bigint

Fast-path send: stores the payload bytes verbatim, no JSON parse. Untyped string literals ('…') resolve to this overload. Returns the event id. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
payload
text
required
Event payload stored verbatim. No JSON validation is performed.
Postgres text cannot store NUL bytes (\x00). Raw binary payloads must be base64- or hex-encoded by the caller before passing them to any send overload.
-- untyped literal resolves to the text fast path
select pgque.send('orders', '{"order_id": 42}');

​
send — 3-argument forms

​
pgque.send(queue_name text, type_name text, payload jsonb) → bigint

Same as the 2-argument jsonb overload, but records an explicit event type in ev_type. Returns the event id. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
type_name
text
required
Free-form application event type label (e.g. order.created). Stored in ev_type.
​
payload
jsonb
required
Event payload. Validated as JSON; stored in canonical text form.
select pgque.send('orders', 'order.created', '{"order_id": 42}'::jsonb);

​
pgque.send(queue_name text, type_name text, payload text) → bigint

Fast-path send with an explicit event type. Payload bytes are stored verbatim. Returns the event id. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
type_name
text
required
Free-form application event type label. Stored in ev_type.
​
payload
text
required
Event payload stored verbatim. No JSON validation is performed.

​
send_batch — 2-argument forms

​
pgque.send_batch(queue_name text, payloads jsonb[]) → bigint[]

Default-type JSON batch send. Equivalent to pgque.send_batch(queue_name, 'default', payloads). Returns event ids aligned to input order. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
payloads
jsonb[]
required
Array of JSON payloads. Each element is validated and stored in canonical form. NULL arrays raise payloads must not be null; NULL elements inside a non-null array are stored as NULL ev_data.

​
pgque.send_batch(queue_name text, payloads text[]) → bigint[]

Default-type text batch send. Equivalent to pgque.send_batch(queue_name, 'default', payloads). Returns event ids aligned to input order. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
payloads
text[]
required
Array of opaque text payloads stored verbatim. NULL arrays raise payloads must not be null.

​
send_batch — 3-argument forms

​
pgque.send_batch(queue_name text, type_name text, payloads jsonb[]) → bigint[]

Set-based batch send for JSON payloads. Validates each element as jsonb, stores its canonical text form, and returns event ids aligned to input order. Do not rely on the numeric ids being monotonically increasing inside one batch — use array position for input/result correlation. Empty arrays return {} without a queue lookup. Non-empty batches validate queue state once up front: unknown queues raise queue not found: <queue>, and write-disabled queues raise Insert into queue disallowed. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
type_name
text
required
Free-form application event type label applied to every event in the batch. Stored in ev_type.
​
payloads
jsonb[]
required
Array of JSON payloads. Each element is validated. NULL arrays raise payloads must not be null; NULL elements are stored as NULL ev_data.
select pgque.send_batch('orders', 'order.created',
    array['{"id":1}', '{"id":2}']::jsonb[]);

-- Named-argument calls are supported; argument names are part of the API.
select pgque.send_batch(
    queue_name := 'orders',
    type_name  := 'order.created',
    payloads   := array['{"id":1}', '{"id":2}']::jsonb[]
);

​
pgque.send_batch(queue_name text, type_name text, payloads text[]) → bigint[]

Set-based fast-path batch send for opaque text payloads. Returns event ids aligned to input order. Empty arrays return {} without a queue lookup. NULL arrays raise payloads must not be null. Unknown or write-disabled queues raise on non-empty batches. Grant: pgque_writer. Source: sql/pgque-api/send.sql.
​
queue_name
text
required
Name of the destination queue.
​
type_name
text
required
Free-form application event type label applied to every event in the batch.
​
payloads
text[]
required
Array of opaque text payloads stored verbatim. NULL arrays raise payloads must not be null.

​
Named-argument calls

All publishing argument names (queue_name, type_name, payload, payloads) are part of the stable SQL API. Positional calls are unchanged. 
-- positional
select pgque.send('orders', 'order.updated', '{"id":7}'::jsonb);

-- named
select pgque.send(
    queue_name := 'orders',
    type_name  := 'order.updated',
    payload    := '{"id":7}'::jsonb
);

Build docs developers (and LLMs) love

Get started for freeTalk to us