How pg_relay Works

At a high level, an event moves through pg_relay like this:

Your transaction calls pgrelay.notify('my_channel', 'some data')
        │
        ▼
A row is written to a private queue table — inside your transaction.
If you roll back, no event is created. If you commit, the event is saved.
        │
        ▼  (up to about 1 second passes)
The Processor (a lightweight background program) finds the event.
        │
        ▼
It runs the SQL action registered for 'my_channel', passing 'some data' as input.
        │
        ▼
The result (ok, error, and so on) is written to the audit log, pgrelay.log.

The background program is called the Processor. It runs alongside your database, connects using a role (a database user) called pgrelay, and checks for new events once per second. This check is extremely lightweight — it takes about 40 microseconds (0.04 milliseconds) when there is nothing to do, so it adds no meaningful load to your database even when idle.

The Processor works with self-managed PostgreSQL 15 or later on Mac, Linux, and Windows. It also works on managed cloud PostgreSQL from AWS (RDS and Aurora), Azure (Flexible Server), Google Cloud, Alibaba, and is likely to work with managed PostgreSQL services worldwide — see the Cloud Setup book for the details. The PostgreSQL extension itself is pure SQL, so it can be installed in any PostgreSQL database version 15 or later.

Continue to Core Concepts to learn the vocabulary pg_relay uses — channels, payloads, the Processor, and the audit log.