postgres.git / summary / log / commit / refs
commit 1aaca5ab8ffb7f9387dce2a2de128eff006ac1c4
Author: Fujii Masao <fujii@postgresql.org>
Date: Wed Aug 05 02:29:15 2026 +0000
doc: Clarify wal_sender_shutdown_timeout values
Clarify how special wal_sender_shutdown_timeout values affect shutdown
waiting. A value of -1 disables the shutdown timeout and lets the
WAL sender wait for the receiver to catch up, while 0 causes immediate
termination without waiting for catch-up. Positive values bound how long
shutdown waits, so document that they should be high enough for WAL data
to be replicated under normal circumstances.
Update the main documentation, the GUC long description, and
postgresql.conf.sample consistently. While here, fix nearby paragraph
indentation and spacing.
Backpatch to v19, where wal_sender_shutdown_timeout was introduced.
Author: Chao Li <lic@highgo.com>
Reviewed-by: Ian Barwick <barwick@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Discussion: https://postgr.es/m/AF4FE756-A220-4DA7-87B7-A126F3F307FD@gmail.com
Backpatch-through: 19
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 124f62e6e8f..0a2afe88ea0 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
- <literal>-1</literal> (the default) disables the timeout mechanism.
+ <literal>-1</literal> (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 <literal>0</literal> causes the WAL sender to
+ terminate without waiting for the receiver to catch up.
</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 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.
</para>
+
<para>
This parameter can be set in <varname>primary_conninfo</varname> and
in the <literal>CONNECTION</literal> clause of
diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat
index 3c1e6b31bf8..2cd115deaee 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -3558,7 +3558,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 and waits for the receiver to catch up; 0 does not wait for the receiver to catch up.',
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 86f2e16eba0..23dd27957be 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 the timeout and waits for catch-up
+ # 0 does not wait for catch-up
#track_commit_timestamp = off # collect timestamp of transaction commit
# (change requires restart)
[parent: 2f768dda531c]