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) checks the queue once a second and picks up 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 connects to your database as a role (a database user) called pgrelay and checks the queue once a second. That check is extremely lightweight — about 40 microseconds when there is nothing to do — so an idle Processor adds no meaningful load. For anything beyond a sandbox, the Processor runs on its own host, not the database server; the Security Guide explains why.

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.