Skip to content

Standby and Replica Databases

You can run the Processor against a hot standby (a live, continuously-updated replica database, ready to take over if the primary fails). It will connect successfully, poll every second, and find nothing to do — so it simply sits idle.

The reason there is no work: triggers do not fire while a standby is replaying WAL (Write-Ahead Log — PostgreSQL's own internal record of every change, which is what replication streams to a standby; see the Glossary). The replicated copy of pgrelay.queue on the standby only ever contains rows that had already been dispatched on the primary before they were replicated. queue_has_work() returns false on every tick, so the Processor never progresses past its cheap probe.

After failover: once the standby is promoted to primary, triggers start firing again, events begin to accumulate in the queue, and the Processor starts processing them on its very next tick — automatically, with no restart or reconfiguration needed.

The Processor itself has no awareness of whether its database is a primary or a standby. It does not check pg_is_in_recovery() (PostgreSQL's own function for "am I a standby") or look for read-only mode. It simply polls — and on a standby, there is never anything to find.

Run one Processor on each node — both primary and standby. The standby's Processor sits idle. When the standby is promoted, its Processor starts working immediately on the next tick, with no manual intervention.

If you connect through a virtual IP address or a connection manager (Patroni, Repmgr, HAProxy) that automatically points at the current primary, you only need one Processor. It will lose its connection during a failover, reconnect with its usual backoff, and resume against the new primary once the virtual IP switches over.

Preflight replication warning

The preflight() function checks whether pgrelay.queue is included in any native PostgreSQL logical replication publication, or a Spock replication set (see the Multi-Master Deployment book for what Spock is). If it is, you will see a warning:

replication:queue_in_pub | warn | pgrelay.queue is in publication my_pub

The Processor still starts — this warning is advisory only. It exists for two reasons:

  • Physical replication (Patroni/Repmgr): pgrelay.queue is already replicated by PostgreSQL's own streaming replication, so also including it in a logical publication replicates the same high-churn data twice, for no benefit.
  • Logical replication / multi-master: replicating the queue between nodes causes primary-key collisions, since each node generates its own event IDs. Keep pgrelay.queue out of every replication set — unless you are specifically running multi-master mode, which handles this differently; see the Multi-Master Deployment book.

Continue to Multi-Master Databases for a brief pointer to the dedicated Multi-Master Deployment book.