From: Chao Li <li.evan.chao@gmail.com>
To: PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
Cc: Fujii Masao <masao.fujii@gmail.com>
Subject: doc: clarify wal_sender_shutdown_timeout behavior for small values
Date: Fri, 17 Jul 2026 13:37:02 +0800
Message-ID: <AF4FE756-A220-4DA7-87B7-A126F3F307FD@gmail.com> (raw)
Hi,
While reading the doc for wal_sender_shutdown_timeout, I felt that it does not explicitly describe the behavior of a value of 0. According to the implementation, when wal_sender_shutdown_timeout is 0, the WAL sender terminates without waiting for the receiver to catch up by calling WalSndDoneImmediate(). When the value is very small, such as 1 millisecond, the timeout expires shortly afterward if the receiver has not already caught up, so from a user's perspective, the behavior may be very similar to that of 0.
As I understand it, wal_sender_shutdown_timeout is intended to prevent shutdown from taking unexpectedly long. A value of 0 requests no waiting, while a value that is too small may provide insufficient time for the receiver to catch up. Such values should therefore be used with caution, especially for physical replication.
The attached patch clarifies that the timeout is enabled for nonnegative values, documents the behavior of 0, and cautions users against setting a value too small for the receiver to catch up.
While touching this part of the doc, I also noticed that the preceding paragraph was missing one level of indentation and that there was no blank line between paragraphs. I was previously advised that paragraphs should be separated by a blank line, so the patch fixes these formatting issues as well.
If accepted, this patch is intended for v19.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/Attachments:v1-0001-doc-Clarify-wal_sender_shutdown_timeout-behavior-.patch (application/octet-stream, 3.1K) download
From 178311692a2cab384b80a920f0a8adf7f36078b8 Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <lic@highgo.com>
Date: Fri, 17 Jul 2026 13:24:08 +0800
Subject: [PATCH v1] doc: Clarify wal_sender_shutdown_timeout behavior for
small values
Document that nonnegative 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.sgmlindex aa7b1bd75d2..b7c462e0f26 100644--- a/doc/src/sgml/config.sgml+++ b/doc/src/sgml/config.sgml@@ -4990,21 +4990,28 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows
without units, it is taken as milliseconds. A value of
<literal>-1</literal> (the default) disables the timeout mechanism.
</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 nonnegative 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. In particular, a value of+ <literal>0</literal> causes the WAL sender to terminate without waiting+ for the receiver to catch up. Therefore, <literal>0</literal> or a+ value too small to allow the receiver to catch up should be used with+ caution, especially for physical replication.
</para>
+
<para>
This parameter can be set in <varname>primary_conninfo</varname> and
in the <literal>CONNECTION</literal> clause of
--
2.50.1 (Apple Git-155)
=
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: pgsql-hackers@postgresql.org
Cc: li.evan.chao@gmail.com, pgsql-hackers@lists.postgresql.org, masao.fujii@gmail.com
Subject: Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
In-Reply-To: <AF4FE756-A220-4DA7-87B7-A126F3F307FD@gmail.com>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox