Database Tables Reference

None of these tables can be queried with direct SQL unless you are a superuser — use the functions described throughout this site for all access. The column descriptions below will help you interpret pgrelay.log records and diagnose problems when you do have access.

pgrelay.action_types

The action type registry. Defines the types of actions a channel can execute. Seeded at install time with 'sql'.

Column	Type	Description
action_type	text (primary key)	Action type identifier. Stored in the exact case it was registered in; lookups are case-insensitive.
description	text	Human-readable description of what this action type does.
active	boolean	Stored for future use. Has no functional effect in the current release.
run_order	integer	Dispatch priority. Lower values are processed first in a batch. NULL sorts last.

list_action_types() is granted to PUBLIC — any role can read the registry. Writing to it requires an explicit grant (via grant_user or an individual GRANT EXECUTE).

pgrelay.actions

The channel registry. One row per registered channel.

Column	Type	Description
channel	text (primary key)	Channel name, stored in the exact case it was registered in. Lookups are case-insensitive.
action	text	The action to execute. For action_type = 'sql': a SQL string where $1 is bound to the event payload.
action_type	text (foreign key)	References pgrelay.action_types. Defaults to 'sql'. Determines how the action is executed.
active	boolean	When false, events cannot be queued on this channel, and any in-flight events are processed as invalid.
notes	text	Free-form description.
max_retries	integer	Number of automatic retry attempts (0–99). See Retry Policy.
concurrency_mode	text	Dispatch concurrency: 'concurrent' (default, no restriction), 'channel' (one in-flight event per channel), or 'channel_payload' (one per channel+payload pair). Enforced by a database CHECK constraint. See Per-channel dispatch concurrency.
node_restricted	boolean	Default false. When true, queue rows for this channel are pinned to the node that created them and dispatched only there, in every --mode; they are never adopted or reassigned, and deduplication applies per node. For actions with node-local side effects. See the Multi-Master Deployment book.
created_at	timestamptz	When this channel was registered.
updated_at	timestamptz	When this row was last modified. Maintained automatically by a trigger.

pgrelay.log

The audit log. One row per processed event.

Column	Type	Description
id	bigint (primary key)	Auto-incrementing log row ID.
channel	text	The channel the event was processed on.
payload	text	The event payload passed to the action.
status	text	Outcome of processing. See the table below.
error	text	The exception message, when status = error. For retry_scheduled, contains retry_id=<n>. NULL for every other status.
elapsed_ms	bigint	Milliseconds taken to run the action. NULL for expired, invalid, and retry_scheduled rows.
queue_id	bigint	The pgrelay.queue row this log entry came from. Always populated.
actioned_at	timestamptz	When this event was processed.

Status values:

Status	Meaning
ok	The action completed without error.
error	The action raised a permanent error (not a transient class-40 conflict — see Retry Policy).
expired	The event was past its expiry time when the Processor checked it. No action was run.
invalid	The channel was disabled or unregistered by the time the event was dispatched. No action was run.
retry_scheduled	The action hit a deadlock or serialisation conflict, and a retry has been queued up.
max_retries_exceeded	The action hit the same kind of conflict, but the retry limit had already been used up.
unsupported_action_type	The channel's action type is not 'sql' and no handler exists for it. The row is marked done and logged at error level.
post_process_error	An infrastructure failure happened after the action completed (for example, writing the log row itself failed). Rare.

pgrelay.pg_relay_applications

The application registry. Tracks every application built on top of pg_relay. pg_relay writes its own row here at install time; related applications may register themselves using pgrelay.register_application(). This table is the main mechanism for checking version compatibility: a related application can query pgrelay.list_applications() to confirm a compatible version of pg_relay is installed before it proceeds. pg_relay's own upgrade scripts use the same table to warn about registered applications a new release might otherwise break.

Column	Type	Description
id	integer (primary key)	Auto-incrementing row ID.
application_name	text	Name of the application. Case-insensitive unique key.
installed_at	timestamptz	When the application was first registered. Set once by the initial call and never changed afterwards.
initial_version	text	The version string recorded when the application was first registered. Never changed after that.
latest_version	text	The most recently applied version of this application. Updated on each upgrade.
latest_version_at	timestamptz	When latest_version was last set.

This table is private. Read access is through the list_applications() function, granted to PUBLIC. Write access (register_application, update_application_version) needs an explicit grant.

pgrelay.queue

The durable event store. One row per pending or already-dispatched event.

Column	Type	Description
id	bigint (primary key)	A "snowflake" ID — time-ordered and globally unique across every node, so it is safe to replicate. See the Glossary.
channel	text	Channel name (in the canonical case from pgrelay.actions).
payload	text	Event payload.
queued_at	timestamptz	When the event was enqueued (within the producer's own transaction).
run_at	timestamptz	The earliest time this event is eligible for dispatch. Default: now() (immediate).
expire_at	timestamptz	Discard deadline. NULL means it never expires.
retry_count	integer	0 for original events. Increases by 1 for each retry row.
parent_id	bigint	References the queue row this retry was created from. NULL for original events, and set to NULL if the parent row is later deleted.
owner_node	bigint	The node responsible for dispatching this row (only meaningful with more than one database — see the Multi-Master Deployment book; always 0 on a single node).
run_in_node	bigint	The node this row is pinned to, or NULL for an unrestricted row. Only set for channels flagged node_restricted; never something the caller can set directly. A non-NULL row is only ever dispatched by its own node, in every mode, and is never reassigned.
dispatched_at	timestamptz	When this event was processed. NULL while it is still pending.

pgrelay.processor_control (v1.1)

The single-row, declarative fleet state described in The Processor. Private; changed only through request_reload() / start() / stop() / pause_for() / pause_to(), and observed by every Processor through queue_probe().

Column	Type	Description
id	boolean (primary key)	Always true; the primary key plus a CHECK constraint enforce that this table has exactly one row.
reload_token	uuid	An opaque signal. request_reload() replaces it, and every Processor that sees a value different from the one it last acted on performs a full reload. It is a UUID, not a simple counter, so no value can ever repeat and be mistaken for "unchanged".
desired_state	text	'running' or 'paused'.
pause_until	timestamptz	With 'paused': NULL pauses indefinitely (stop()); a timestamp bounds the pause, which lifts itself automatically the moment now() passes it.
updated_at	timestamptz	When the fleet state was last changed.
updated_by	text	Which session user last changed it.

pgrelay.options (v1.1)

A generic key/value settings store for pg_relay itself, and for companion applications or your own code, to persist database-administrator-configurable options. Private; access only through set_option()/get_option() (see Function Reference). pg_relay 1.1 does not read or write any option itself — this ships purely as shared infrastructure for other components to build on.

Column	Type	Description
option_name	text (primary key)	Option key. Case-sensitive.
option_value	text	Option value, stored as text. Cannot be NULL.
updated_at	timestamptz	When this option was last set.
updated_by	text	Which session user last set it.

---

Continue to Function Reference for every pg_relay function, its parameters, and what it returns.