Getting Ready

Multi-master mode (multi-node or leader) requires the following, before you switch any Processor over to it.

1. Snowflake IDs (automatic)

As of pg_relay 1.1, pgrelay.queue.id and pgrelay.log.id default to globally unique "snowflake" bigint values (see the Glossary), so both tables are safe to replicate between nodes. There is nothing you need to configure for this.

2. A per-node ID — enforced at startup

Set a small, distinct integer on each node so the ownership model, leader election, and node restriction (see Node-Restricted Channels) can tell nodes apart:

ALTER SYSTEM SET pg_relay.node_id = '1';   -- distinct on each node (2, 3, ...)
SELECT pg_reload_conf();

If left unset, this defaults to 0, which is also the single-node default. Assign a value that matches your Spock node ordering. The Processor refuses to start in multi-node/leader mode when this setting resolves to 0 — two nodes both defaulting to 0 would end up owning (and, for node-restricted channels, pinning) each other's rows, causing exactly the wrong-node execution these modes exist to prevent.

3. Replicate the queue and the log

Include pgrelay.queue and pgrelay.log in your Spock replication set, so every node can see every other node's events and audit rows. (In single mode, you do not replicate the queue.)

4. Spock installed

The Processor refuses to start in multi-node/leader mode if the spock schema is not present.

5. The same pg_relay version everywhere

Run the extension install or upgrade on every node (Spock does not replicate DDL — data definition language, meaning schema changes like creating tables or functions — by default), and bring every node up to v1.1 before flagging any channel as node_restricted = true. A node still on an earlier version neither stamps nor honours the run_in_node column that feature depends on.

Note

--mode on a single node by itself is a valid, supported configuration — for example, the first node of a cluster you plan to grow later. The gate functions simply find one node, and nothing to adopt.

---

Continue to How Each Mode Works for the detail behind each of the three modes.