Skip to content

Function Reference: Fleet Control, Options, and Registry

The functions that pause, resume, and reload the Processor fleet, the options store, and the application registry. See also Channels and Events and Monitoring and Operations.

Fleet control functions (v1.1)

All five require explicit grants (grant_user() covers all of them; grant_relay() covers queue_probe and request_reload for the Processor role). See The Processor for the full explanation and examples.

pgrelay.queue_probe()

The Processor's combined per-tick probe: a table of (has_work boolean, reload_token uuid, paused boolean) in one round trip. has_work is identical to queue_has_work(); paused is the effective state (combining desired_state and pause_until expiry, worked out inside the database). Select named columns, never * — future versions may add columns.

pgrelay.request_reload()

Replaces the reload token; every Processor performs a full reload at its next probe. Returns the new token (uuid).

pgrelay.start() / pgrelay.stop()

Resume / indefinitely pause the fleet. Both return the updated control row.

pgrelay.pause_for(p_seconds integer) / pgrelay.pause_to(p_until timestamptz)

Pause the fleet for a duration from now, or until an absolute time. A pause_to value in the past has no effect; pause_for rejects non-positive values. Both return the updated control row. The last write always wins — calling any control function overwrites the previous intent.

Options store functions (v1.1)

Both require explicit grants (grant_user() covers them; neither is granted to PUBLIC). See pgrelay.options in Database Tables Reference for the underlying schema.

pgrelay.set_option(p_option_name text, p_option_value text)

Creates the option if it does not exist yet, otherwise updates its value and audit columns — an "upsert" (a single operation that inserts if missing or updates if present), so the first call for a given name creates it with no separate registration step needed. Raises an error if p_option_name is empty or p_option_value is NULL.

Returns: the resulting pgrelay.options row.

SELECT pgrelay.set_option('maintenance_window_hours', '2');

pgrelay.get_option(p_option_name text)

Returns the option's current value, or NULL if it has never been set — this mirrors PostgreSQL's own current_setting(name, missing_ok) pattern, so callers can use COALESCE() to supply their own default, rather than having to catch an exception for the ordinary "not configured yet" case.

Returns: text.

SELECT COALESCE(pgrelay.get_option('maintenance_window_hours'), '1');

pgrelay.grant_relay(p_role_name)

Grants the complete Processor operating set (schema usage plus EXECUTE on every queue and processing function) to the named role. Run this after CREATE EXTENSION, and after any pg_restore that re-creates functions.

Returns: nothing (void).

pgrelay.grant_user(p_role_name)

Grants the full application-user privilege set to the named role: schema usage, all channel management functions (register, update, enable, disable, unregister, get, list), action type management functions (register_action_type, update_action_type, delete_action_type), maintenance functions (purge, purge_queue), application registry management (register_application, update_application_version), the fleet-control functions (request_reload, start, stop, pause_for, pause_to), and the options store functions (set_option, get_option). Callable by superusers only. Run this after CREATE EXTENSION, after any pg_restore that re-creates functions, and again after upgrading to 1.1 (the upgrade recreates register/update with a new parameter, which resets their per-role grants).

notify() and list_action_types() are already granted to PUBLIC and are not included.

Returns: nothing (void).

Application registry functions

pgrelay.list_applications()

Returns every row in pgrelay.pg_relay_applications, ordered by application_name. Callable by PUBLIC — no extra grant needed.

Returns: a set of pgrelay.pg_relay_applications rows.

Common use — checking pg_relay's own version:

SELECT latest_version FROM pgrelay.list_applications()
WHERE lower(application_name) = 'pg_relay';

pgrelay.register_application(p_name, p_version)

Adds a new application to the registry. Sets both initial_version and latest_version to p_version. Raises an error if p_name or p_version is empty, or if a case-insensitive duplicate already exists. Requires an explicit grant.

Parameter Type Description
p_name text Application name. Must be non-empty and unique (case-insensitive).
p_version text Initial version string (for example, '2.0.0').

Returns: the new pgrelay.pg_relay_applications row.

pgrelay.update_application_version(p_name, p_version)

Updates latest_version and latest_version_at for an existing application. initial_version and installed_at are never changed. Case-insensitive name match. Raises an error if the application is not found, or p_version is empty. Requires an explicit grant.

Parameter Type Description
p_name text Application name. Case-insensitive.
p_version text The new version string.

Returns: the updated pgrelay.pg_relay_applications row.

Typical use — on upgrading a related application:

SELECT pgrelay.update_application_version('my_app', '2.1.0');

Continue to Retry Policy for exactly which failures are retried, and how the backoff schedule works.