pg_relay Documentation¶
pg_relay lets your PostgreSQL database say "when this happens, run that" — reliably, and with every outcome written down.
Your code calls one function, pgrelay.notify('channel', data), inside its own transaction. If the transaction commits, the event exists; if it rolls back, the event never happened. A small background program, the Processor, checks the queue once a second, runs the action you registered for that channel, and records what happened in an audit log.
Your transaction:
INSERT INTO orders ...
SELECT pgrelay.notify('order_placed', order_id)
COMMIT
│
▼
pg_relay's durable queue — a database table. The event now safely exists.
│
▼ (about one second later)
The Processor runs the action registered for 'order_placed'
and writes the outcome to the audit log.
That one mechanism gives you event-driven SQL, notifications (email, Slack, webhooks), scheduled jobs (a pg_cron replacement), metrics, and files in a spool directory — all with the same queue, retries, and audit trail.
pg_relay is built by Pebble IT Solutions Pty Ltd in Australia and released under the MIT Licence. The current release is described in the Release Notes.
Where to start¶
| If you… | Read |
|---|---|
| are new to pg_relay | the User Guide — what it is, how it works, install it, use it |
| want to try it hands-on | the Worked Example — a complete setup you can follow in a test database |
| are deploying it for real | Cloud Setup for a managed database, and the Security Guide for where the Processor should run and how to lock it down |
| want notifications, schedules, metrics, or files | the Features tab — Notifications, Scheduled Jobs, OTLP Metrics, File Spool |
| need the details | the Reference tab — Technical Guide, Glossary, Release Notes |
| run more than one active database | Multi-Master Deployment — most people can skip it |
Every acronym and technical term on this site is explained in the Glossary, and hovering over one shows a short definition.
How this site is organised¶
The tabs across the top group the books by purpose — Start Here, Deploy, Features, Reference, About. Pick a book from the left-hand menu, a section from the "On this page" panel on the right, or search everything at once from the box at the top.
Other Pebble IT PostgreSQL solutions¶
pg_relay is one of a family. Each has its own documentation site:
Source code and releases: gitlab.com/pebble-it/pg_relay.