Hi 2026年7月17日(金) 14:37 Chao Li <[email protected]>: > > 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.
Rather than warn against "too small" values, which raises the question of how you define "too small", I think it'd be better to note that you'd want a value which is sufficiently high to ensure replication terminates properly under normal circumstances (which will vary according to environment etc., so it will be up to the user to work out what is best for them). I took the liberty of revising your patch a bit (easier than trying to describe suggested changes in an email), which: - moves the description of what a value of 0 does to the first paragraph, which handles what various values do - revises the caution about small values to a note about selecting sufficiently high values (per above) - (nitpick) changed "nonnegative" to "non-negative", as that's the majority variant in the docs > 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. +1, this matches the established formatting. Regards Ian Barwick
From fb27c4a7d816bfe27614dec11dd8534b5d7e4601 Mon Sep 17 00:00:00 2001 From: Ian Barwick <[email protected]> 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 <[email protected]> --- 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
