Core Concepts

pg_relay uses four ideas throughout its documentation. Once these make sense, everything else follows.

Channels

A channel is a named event type that you define. You choose the name. Each channel has exactly one registered SQL action attached to it. When the Processor finds an event on that channel, it runs that action.

Channel names are case-insensitive — 'Orders', 'orders', and 'ORDERS' all refer to the same channel.

Payloads

A payload is the piece of text you send along with an event. Inside your registered action's SQL, it is available as $1 (a placeholder PostgreSQL fills in for you). It can be a plain number, a status flag, or a JSON (JavaScript Object Notation — a common text format for structured data) object containing several values at once.

-- Simple: pass an order ID
SELECT pgrelay.notify('new_order', NEW.id::text);
-- Action: SELECT warehouse.reserve_stock($1::bigint)

-- Complex: pass multiple values as JSON
SELECT pgrelay.notify('order_shipped',
    json_build_object('order_id', NEW.id, 'tracking', NEW.tracking_code)::text);
-- Action: SELECT notify_customer.send_shipment_email($1)

The Processor

The Processor is a small program (a single binary file called pg_relay) that you run as a system service alongside your database. It connects using standard PostgreSQL connection settings (environment variables), checks for events once per second, and runs them. You start it once and leave it running. It writes its own log output, which can be collected by whatever logging system you already use.

The Audit Log

Every event the Processor handles is recorded in a table called pgrelay.log. You can query it at any time to see what ran, when it ran, whether it succeeded, and how long it took. By default, you need to be specifically granted permission to view this log (see Granting Permissions in the Technical Guide).

SELECT channel, status, elapsed_ms, actioned_at
FROM pgrelay.log
ORDER BY actioned_at DESC
LIMIT 20;

---

With the vocabulary out of the way, the next chapter looks at some real-world situations where pg_relay is a good fit.