From 1c3e2beea4da5cf60be9709064181a6de4527488 Mon Sep 17 00:00:00 2001 From: "Chao Li (Evan)" Date: Fri, 17 Jul 2026 13:24:08 +0800 Subject: [PATCH v3] 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 Reviewed-by: Ian Barwick Reviewed-by: Fujii Masao Reviewed-by: Daniel Gustafsson Discussion: https://postgr.es/m/AF4FE756-A220-4DA7-87B7-A126F3F307FD@gmail.com --- doc/src/sgml/config.sgml | 32 ++++++++++++------- src/backend/utils/misc/guc_parameters.dat | 2 +- src/backend/utils/misc/postgresql.conf.sample | 4 ++- 3 files changed, 24 insertions(+), 14 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index aa7b1bd75d2..236ee067f40 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -4988,23 +4988,31 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows Specifies the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver. If this value is specified without units, it is taken as milliseconds. A value of - -1 (the default) disables the timeout mechanism. + -1 (the default) disables the timeout mechanism, + allowing the WAL sender to wait as long as necessary for the receiver + to catch up. A value of 0 causes the WAL sender to + terminate without waiting for the receiver to catch up. + - 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. + - 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 zero or a positive 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 high enough to allow all WAL data to be replicated to + the receiver under normal circumstances. + This parameter can be set in primary_conninfo and in the CONNECTION clause of diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat index d421cdbde76..482d761f945 100644 --- a/src/backend/utils/misc/guc_parameters.dat +++ b/src/backend/utils/misc/guc_parameters.dat @@ -3575,7 +3575,7 @@ { name => 'wal_sender_shutdown_timeout', type => 'int', context => 'PGC_USERSET', group => 'REPLICATION_SENDING', short_desc => 'Sets the maximum time the server waits during shutdown for all WAL data to be replicated to the receiver.', - long_desc => '-1 disables the timeout', + long_desc => '-1 disables the timeout (keeps waiting); 0 means no waiting.', flags => 'GUC_UNIT_MS', variable => 'wal_sender_shutdown_timeout', boot_val => '-1', diff --git a/src/backend/utils/misc/postgresql.conf.sample b/src/backend/utils/misc/postgresql.conf.sample index 7958653077b..e6ea90ce0cc 100644 --- a/src/backend/utils/misc/postgresql.conf.sample +++ b/src/backend/utils/misc/postgresql.conf.sample @@ -362,7 +362,9 @@ #max_slot_wal_keep_size = -1 # in megabytes; -1 disables #idle_replication_slot_timeout = 0 # in seconds; 0 disables #wal_sender_timeout = 60s # in milliseconds; 0 disables -#wal_sender_shutdown_timeout = -1 # in milliseconds; -1 disables +#wal_sender_shutdown_timeout = -1 # in milliseconds + # -1 disables (keeps waiting) + # 0 means no waiting #track_commit_timestamp = off # collect timestamp of transaction commit # (change requires restart) -- 2.50.1 (Apple Git-155)