From 493ee66d219025c4d9f2e32631e3cebd44c8bd18 Mon Sep 17 00:00:00 2001 From: shihao zhong Date: Tue, 20 Oct 2026 20:08:26 -0400 Subject: [PATCH REL_19 v1] doc: Note that promotion can wait for a backend stuck writing to a client With a logical slot on a standby using wal_level = replica, promotion waits for all processes to absorb a barrier. A backend blocked on a client that stopped reading cannot, so describe the wait and the ways out. --- doc/src/sgml/high-availability.sgml | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/src/sgml/high-availability.sgml b/doc/src/sgml/high-availability.sgml index 7253f9d8287..c9490050a27 100644 --- a/doc/src/sgml/high-availability.sgml +++ b/doc/src/sgml/high-availability.sgml @@ -1571,6 +1571,29 @@ postgres=# WAIT FOR LSN '0/306EE20'; read-only queries from the primary, not for high availability purposes, you don't need to promote. + + + On a standby with wal_level set to + replica that has a logical replication slot, including + a failover slot synchronized from the primary, promotion waits until every + process has seen that logical decoding stays enabled. A backend that is + blocked sending data to a client that stopped reading cannot do that, so + promotion waits until the client goes away or the kernel gives up on the + connection, which can take about 15 minutes with default TCP settings. + While it waits, the startup process logs the process ID of such a backend + every 5 seconds. + + + + To avoid the wait, set wal_level to + logical on the standby. If it happens, + pg_terminate_backend on the logged process ID lets + the promotion finish. This does not work if the backend is blocked + sending an error message, because the error is sent with interrupts held. + In that case close the client connection, or set + tcp_user_timeout on the standby so that the server + drops such a connection sooner. + -- 2.37.1 (Apple Git-137.1)