Glossary¶
Terms used throughout this documentation, in plain English. If you're new to pg_relay or pg_relay_notifier, read this page first — the rest of the documentation assumes these words.
_env:VAR_NAME reference¶
The only way a secret (an SMTP password, a Microsoft 365 client secret) may appear in a profile. It's a reference, not a value — the pg_relay Processor resolves it by reading the named environment variable from its own host, at send time, before using the profile for anything. The literal secret is never stored in the database. See SMTP Endpoints.
at-least-once delivery¶
The delivery guarantee pg_relay's held-transaction design provides: a crash mid-send re-offers the notification on a later poll, so a message is never silently lost. In the narrow window between the mail provider accepting a message and the Processor's transaction committing, a rare duplicate is possible — but never a loss.
channel¶
The pg_relay queue lane a profile's notifications travel through, registered with action_type = 'notify'. Most senders never think about it — every profile has a default. Channels matter when a DBA wants to control dispatch behaviour for a group of messages, such as serializing everything through one rate-limited relay. See Channels and Concurrency.
compose() / dispatch()¶
The two-phase send API. compose() creates a draft (invisible to the Processor, attachments still addable); dispatch() enqueues it. send() is compose() + dispatch() in one call, for messages with no attachments.
debug trace¶
A step-by-step record of one delivery attempt (claimed, fetched, sent/send_failed, committed), written by the Processor on a separate autocommit connection — visible in real time while a send is in flight, and preserved even if the attempt itself rolls back. Turned on with p_debug => true on a send, or a profile-wide default. See Debug Tracing.
default profile¶
A database-wide fallback profile name, configured via pgrelay.set_option('pg_relay_notifier.default_profile', '<name>'). Any function taking p_profile accepts NULL/'' and resolves it through this option instead — raising only if neither an explicit profile nor the option is set. See The Default Profile.
draft¶
A notification that's been compose()d but not yet dispatch()ed. Invisible to the Processor; attachments may still be added. Becomes pending at dispatch.
held transaction¶
The core of pg_relay's delivery design: the Processor claims a queue row, fetches the message, sends it, and records the outcome, all inside one database transaction that stays open — and the row row-locked — for the whole delivery. This is what makes concurrency_mode work and what guarantees at-least-once delivery.
interface contract¶
The formal specification of the four functions (interface_version, fetch, set_status, debug_log) that pg_relay and pg_relay_notifier meet at, and nothing more. See The Interface Contract.
node-restricted¶
A pg_relay 1.1 per-channel flag that pins a channel's queue rows to the node that created them, for companion applications with node-local side effects. Does not apply to notify channels — email delivery has no node-local state. See Multi-Master and Notification IDs.
notification¶
One message you've composed — a row in pgrelay_notifier.notifications. Moves through a small set of states (draft → pending → sent/retry/failed/expired/invalid) — see Core Concepts.
notification_id¶
The primary key of a notification, and the only value that ever travels through the pg_relay queue (as the payload). Generated by pgrelay._next_id(), the same snowflake-style generator pg_relay's own queue/log ids use — globally unique across nodes without coordination.
pg_relay¶
The companion extension pg_relay_notifier is built on. It provides the durable queue, retry machinery, concurrency control, the audit log, and the Go Processor that actually performs SMTP/Microsoft Graph delivery. pg_relay_notifier writes what to send; pg_relay delivers it. Documentation: https://pg-relay.pebbleit.com.au/
pgrelay.options / set_option / get_option¶
pg_relay's generic key/value settings store, shared across every pg_relay-based application. The default profile is configured through it.
priority¶
An Oracle UTL_MAIL-style value, 1 (highest) to 5 (lowest), stored on every notification and emitted forward-compatibly in the message JSON. The current pg_relay Processor doesn't yet put it on the wire as an X-Priority header.
profile¶
A named delivery endpoint — the connection details for one SMTP relay or one Microsoft 365 tenant, plus per-endpoint defaults (default channel, attachment limits, default sender/reply-to). See Core Concepts.
provider_ref¶
The mail provider's own reference for a specific delivery attempt — the generated SMTP Message-ID, or the Microsoft Graph request-id. What to quote when following up with the provider about a message that shows sent but didn't arrive.
transport¶
Which delivery mechanism a profile uses: smtp or m365 (Microsoft 365 via Graph). Routes the pg_relay Processor's Go handler; determined once per profile, never per message.
UTL_MAIL¶
Oracle's built-in package for sending email from PL/SQL. pg_relay_notifier's core extension has UTL_MAIL-shaped functions (send_mail, send_mail_attach_raw, send_mail_attach_text); a separate, optional extension provides the literal utl_mail schema for migrated code that calls UTL_MAIL.SEND(...) unmodified. See the UTL_MAIL Compatibility book.