From fb27c4a7d816bfe27614dec11dd8534b5d7e4601 Mon Sep 17 00:00:00 2001
From: Ian Barwick <barwick@gmail.com>
Date: Fri, 17 Jul 2026 17:45:35 +0900
Subject: [PATCH v2] doc: improve description for wal_sender_shutdown_timeout

Document that non-negative values enable the timeout and that zero causes
the WAL sender to terminate without waiting for the receiver to catch up.
Also caution against values too small to allow catch-up, especially for
physical replication.

While here, fix nearby indentation and add blank lines between paragraphs.

Author: Chao Li <lic@highgo.com>
---
 doc/src/sgml/config.sgml | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index aa7b1bd75d2..3aff683235a 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -4989,22 +4989,29 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"'  # Windows
         WAL data to be replicated to the receiver.  If this value is specified
         without units, it is taken as milliseconds.  A value of
         <literal>-1</literal> (the default) disables the timeout mechanism.
+        A value of <literal>0</literal> will cause the WAL sender to shut down
+        immediately.
        </para>
+
        <para>
-       When replication is in use, the sending server normally waits until
-       all WAL data has been transferred to the receiver before completing
-       shutdown.  This helps keep sender and receiver in sync after shutdown,
-       which is especially important for physical replication switchovers,
-       but it can delay shutdown.
+        When replication is in use, the sending server normally waits until
+        all WAL data has been transferred to the receiver before completing
+        shutdown.  This helps keep sender and receiver in sync after shutdown,
+        which is especially important for physical replication switchovers,
+        but it can delay shutdown.
        </para>
+
        <para>
-        If this parameter is set, the server stops waiting and completes
-        shutdown when the timeout expires.  This can shorten shutdown time,
-        for example, when replication is slow on high-latency networks or
-        when a logical replication apply worker is blocked waiting for locks.
-        However, in this case the sender and receiver may be out of sync after
-        shutdown.
+        If this parameter is set to a non-negative value, the server stops
+        waiting and completes shutdown when the timeout expires.  This can
+        shorten shutdown time, for example, when replication is slow on
+        high-latency networks or when a logical replication apply worker is
+        blocked waiting for locks.  However, in this case the sender and
+        receiver may be out of sync after shutdown. Care should be taken to
+        select a value which is high enough for data to be replicated to
+        the receiving node under normal circumstances.
        </para>
+
        <para>
         This parameter can be set in <varname>primary_conninfo</varname> and
         in the <literal>CONNECTION</literal> clause of
-- 
2.43.0