The Processor's Security Posture

Who needs this book

Anyone deploying pg_relay somewhere that matters — and anyone who has to answer a security team's questions about it. If you are only trying pg_relay out in a sandbox, you can skip it for now, but read Where to Run the Processor before that sandbox becomes anything else.

This book is about one question: where should the Processor run, and how should it be set up, so that connecting a database to the outside world through pg_relay never weakens the database's own security?

It is written for the person who has to answer to a security team. The short version — and the reason the answer is reassuring — is that pg_relay was designed from the start so that the Processor is the only thing that ever touches the database on pg_relay's behalf, that it only ever makes outbound connections, and that the database role it uses can do very little. Everything in the following chapters builds on those three facts.

What the Processor is, from a security point of view

The Processor is a single, statically compiled binary with no configuration file, no listening port, and no state on disk. Its whole life is:

1. Connect outbound to the database as the deliberately limited pgrelay role.
2. Poll once a second for eligible events.
3. For each event, do the registered work — run a SQL action inside the database, or make an outbound call to an external service (an SMTP server, Microsoft Graph, Azure Communication Services, Gmail, a webhook, an OTLP metrics receiver).
4. Record the outcome in the database.

Three things follow directly, and they are what the rest of this book relies on:

• Nothing ever connects in to the Processor. There is no HTTP server, no webhook receiver, no LISTEN/NOTIFY, no callback of any kind. Every connection the Processor is involved in, it initiates. A firewall in front of it needs no inbound rules at all.
• Nothing ever connects in to the database except the Processor (on pg_relay's behalf). The database initiates nothing outbound. Whether the database is on-premises or a managed cloud instance, its exposure to the outside world through pg_relay is exactly one inbound connection from one role, from one place you choose.
• The Processor's power is the pgrelay role's power, and no more. That role is granted a short, fixed list of functions — the "operating set" — and nothing else. It cannot read pg_relay's own tables directly, cannot change channel configuration, cannot execute a registered action as anyone but itself, and holds no superuser or ownership privileges. What a Compromised Processor Can Do walks through exactly what an attacker holding that role could and could not do; the honest summary is not much.

The one rule this book insists on

Co-locating the Processor on the PostgreSQL server is for sandboxes and development only. Every other deployment runs the Processor on its own VM or server.

The shipped example service files run the Processor as the postgres OS user over the local Unix socket, because that is the zero-configuration way to try pg_relay out. It is exactly the wrong shape for anything that matters, for reasons Where to Run the Processor spells out: on the database host, the Processor's OS user is the database superuser's OS user, its process sits beside the data files, and the host that holds your data now has internet egress. A separate host costs one small VM and removes all three concerns at once.

Managed cloud databases (Amazon RDS and Aurora, Azure Database for PostgreSQL, Google Cloud SQL) make this rule automatic — you cannot run anything on the database host — but bring their own questions about private networking, identity-based credentials, and where the Processor lives in your cloud account. Cloud-Managed Databases covers them.

How the book is organised

Chapter	Question it answers
Where to Run the Processor	On-premises: which host, which network zone, which firewall rules — and why not the database server.
Cloud-Managed Databases	RDS, Aurora, Azure, Cloud SQL: private connectivity, identity-based credentials, and the Processor's own hosting.
What a Compromised Processor Can Do	The blast radius, honestly assessed — what the pgrelay role can and cannot do, what to keep small, and how to detect and contain.
Hardening the Service	The Linux service itself: a dedicated non-login user, systemd sandboxing, /proc visibility, core dumps, file permissions, and credential rotation.
Database-Side Controls	pg_hba.conf, TLS, the pgrelay role's shape, PUBLIC grants, and the run_as opt-in.
Checklist	Everything above as a tick-list, by deployment tier.

The Technical Guide's Security Model chapter explains the database-internal design — private tables, SECURITY DEFINER helpers, the SECURITY INVOKER action runner — that this book takes as given. Read it first if you want to know why the pgrelay role is as limited as it is; read this book to deploy on top of that.

---

Continue to Where to Run the Processor.