Do You Need This Book?¶
This book is the complete technical reference for running pg_relay across more than one PostgreSQL database at once. It assumes you are already familiar with how pg_relay works on a single database, and with logical multi-master replication — specifically pgEdge Spock (an extension that lets several PostgreSQL databases all accept writes at the same time, keeping each other in sync). If you have not yet read the User Guide, start there instead.
Who needs this book
Operators running pg_relay on a Spock active-active cluster (where more than one node accepts writes at the same time), or on single-primary high availability where the Processor should follow a failover. If you run one database, the default --mode=single already does the right thing, and you can skip this book entirely.
The --mode parameter¶
The Processor's cluster behaviour is chosen with one startup flag, --mode (default single). It is a process argument — you change it by restarting the Processor. It is independent of --workers (the concurrency within a single node still applies under any mode).
| Mode | Topology | What the Processor does |
|---|---|---|
single (default) |
single-primary (with optional HA) | Dispatches only when its own database is a writable primary. On a read-only standby, it idles and waits for promotion, then takes over automatically. Run it on every HA node — only the primary's copy is ever active. |
multi-node |
Spock active-active | Each node dispatches its own queue rows in parallel with every other node. A conservative per-tick watcher adopts a dead node's eligible rows onto the lowest-numbered live write-master. |
leader |
Spock active-active | The lowest-numbered live write-master dispatches every unrestricted row, regardless of which node created it. Every other node keeps dispatching too, but only its own node-restricted rows (see Node-Restricted Channels) — with no restricted channels registered, a non-leader's tick simply finds nothing, and it behaves like an idle stand-by, ready to take over leadership. |
The Processor binary itself stays "topology-blind": for each mode, it just calls one SQL gate function per tick and acts on the result. All the Spock-aware and recovery logic lives entirely in SQL, not in the Go program.
Choosing a mode¶
single— you have one writable primary (with or without streaming standbys). This describes almost everyone. Zero multi-master machinery involved.leader— you run active-active for high availability or geographic distribution, but your dispatch volume is comfortably handled by one node at a time. This is the simplest mode to reason about: there is one dispatcher for the whole cluster, so per-channelconcurrency_mode(see Workers in the Technical Guide) holds globally, and there is no owner-partitioning to think through. The cost is that there is no cross-node dispatch parallelism, and a larger duplicate "blast radius" if the network partitions (see The Split-Brain Risk).multi-node— you genuinely need dispatch throughput spread across several nodes. Work is partitioned by which node created each event;concurrency_modethen serialises per node, not across the whole cluster. Under a network partition, only the isolated node's own rows are at risk of running twice.
Continue to Getting Ready for what to set up before switching to a multi-master mode.