Skip to content

pg_relay Documentation

pg_relay is a durable event processor for PostgreSQL, built by Pebble IT Solutions Pty Ltd in Australia. This is version 1.1, the current and only supported release.

In plain terms: pg_relay lets your database say "when this happens, run that" — reliably, with everything that happens written down in an audit trail. You call one function, pgrelay.notify(), inside your own database transaction, and a small helper program called the Processor takes it from there, running the action you registered and recording the result.

If a term on this site is unfamiliar — an acronym, a PostgreSQL concept, a piece of jargon — check the Glossary. Every book on this site links to it the first time a tricky term comes up.

Where to start

If you are new to pg_relay, read the books in this order:

  1. User Guide — what pg_relay is, how it works, and how to install and use it. Start here.
  2. Worked Example — a complete, hands-on example you can follow step by step in your own test database.
  3. Technical Guide — the detailed reference: architecture, security, every function, and every configuration option.
  4. Cloud Setup — if your database runs on AWS, Azure, Google Cloud, or another managed provider.
  5. Multi-Master Deployment — only needed if you run pg_relay across more than one active database at once.

The remaining books are reference material you can dip into at any time:

Book What it covers
Changelog What changed in each release.
Contributing How to report a bug or propose a change.
Licence What you are allowed to do with pg_relay, in plain English and in full legal text.
Glossary Every acronym and technical term used across this site, explained.

How this site is organised

This site is arranged like a small library:

Book  (top tab, e.g. "User Guide")
 └── Chapter  (left-hand menu, e.g. "Installing the Extension")
      └── Section  (right-hand "On this page" menu, e.g. "Upgrading from an earlier version")
  • Pick a book from the tabs across the top of the page.
  • Pick a chapter from the menu on the left — this changes depending on which book you are in.
  • Use the "On this page" menu on the right to jump to a section within the current chapter.
  • Use the search box at the top of the page to find anything by keyword, across every book at once.

A quick one-sentence summary

Your code calls pgrelay.notify('channel', data) inside a database transaction; pg_relay writes that as a durable event; and the Processor — a lightweight background program — runs the SQL action you registered for that channel, outside your transaction, in its own clean transaction, and records exactly what happened.

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 finds the event, runs the action you registered for
'order_placed', and writes the outcome to the audit log.

Read the User Guide for the full explanation.

pg_relay is published and maintained by Pebble IT Solutions Pty Ltd, Australia. Source code and releases: gitlab.com/pebble-it/pg_relay. Licensed under the MIT Licence.