Skip to content

Installation

Requirements

  • PostgreSQL 15 or later.
  • The pg_relay extension, version 1.1 or later, already installed in the target database, with its Processor running. See pg_relay's own documentation.
  • Superuser access for the install itself.

On a managed cloud database (RDS, Aurora, Azure, Cloud SQL, and similar), CREATE EXTENSION isn't available for third-party extensions — see the Cloud Setup book instead of this page.

Step 1 — Get the source and install the extension files

git clone https://gitlab.com/pebble-it/pg_relay_notifier.git
cd pg_relay_notifier
sudo make install          # PGXS; override with PG_CONFIG=/path/to/pg_config

Step 2 — Create the extension

CREATE EXTENSION pg_relay_notifier;

This single statement:

  1. Verifies pg_relay ≥ 1.1.0 via the application registry, failing with a clear message if it's missing or too old.
  2. Creates everything in the fixed schema pgrelay_notifier.
  3. Registers the extension and the notify action type with pg_relay.
  4. Seeds profile_defaults (see Attachment Limits and Profile Defaults) with the per-transport starting values.
  5. Grants the pg_relay Processor role (pgrelay) execute on the four interface functions.
  6. Asks the running Processor fleet to reload — notify events are serviceable within about a second, no restarts needed.

Nothing else is granted to anyone at this point — see Security and Permissions.

Step 3 — Verify

SELECT pgrelay_notifier.interface_version();   -- returns 1
SELECT * FROM pgrelay.preflight() WHERE check_name LIKE 'notifier:%';   -- all 'ok'

make test-sql             # SQL regression suite against your current database
make test-sql-utl-mail    # optional: the UTL_MAIL compatibility extension's own suite
make test-e2e             # full end-to-end: local PostgreSQL + the real Processor
                           #   + a bundled SMTP capture server (no containers)

The e2e suite needs a local pg_relay source checkout (PG_RELAY_SRC=... if it isn't at ../pg_relay_build) and a Go toolchain — it builds and runs the real Processor binary and drives genuine SMTP traffic against a bundled capture server, so nothing leaves your machine. To also smoke-test a real Microsoft 365 tenant, see the test/M365_SMOKE.md file in the repository.

Next steps

Set up at least one delivery endpoint — SMTP or Microsoft 365 — then a channel and a grant for whoever will be sending.

If migrated Oracle PL/SQL needs to call UTL_MAIL.SEND(...) unmodified, that's a separate, optional install — see the UTL_MAIL Compatibility book.