pg.ddx.io pgsql-hackers@postgresql.org mailing list archive
help / color / mirror / Atom feeddoc: clarify wal_sender_shutdown_timeout behavior for small values
10+ messages / 4 participants
[nested] [flat]
* doc: clarify wal_sender_shutdown_timeout behavior for small values
@ 2026-07-17 05:37 Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
0 siblings, 1 reply; 10+ messages in thread
From: Chao Li @ 2026-07-17 05:37 UTC (permalink / raw)
To: PostgreSQL-development <pgsql-hackers@lists.postgresql.org>; +Cc: Fujii Masao <masao.fujii@gmail.com>
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.sgml
index 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)
=
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
@ 2026-07-17 09:00 ` Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
0 siblings, 1 reply; 10+ messages in thread
From: Ian Lawrence Barwick @ 2026-07-17 09:00 UTC (permalink / raw)
To: Chao Li <li.evan.chao@gmail.com>; +Cc: PostgreSQL-development <pgsql-hackers@lists.postgresql.org>; Fujii Masao <masao.fujii@gmail.com>
Hi
2026年7月17日(金) 14:37 Chao Li <li.evan.chao@gmail.com>:
>
> 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
Attachments:
v2-0001-doc-improve-description-for-wal_sender_shutdown_t.patch (text/x-patch, 3.1K) download
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
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
@ 2026-07-17 10:00 ` Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 10+ messages in thread
From: Fujii Masao @ 2026-07-17 10:00 UTC (permalink / raw)
To: Ian Lawrence Barwick <barwick@gmail.com>; +Cc: Chao Li <li.evan.chao@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
On Fri, Jul 17, 2026 at 6:01 PM Ian Lawrence Barwick <barwick@gmail.com> wrote:
> 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
This is docs, not error message, but as error message style guide suggests,
the word "non-negative" basically should be avoided since it's ambiguous
about whether it accepts zero?
If we document what a value of 0 means, isn't it better to add a brief
description about the value 0 to postgresql.conf.sample and guc_parameters.dat
as well?
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
@ 2026-07-17 10:41 ` Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
0 siblings, 1 reply; 10+ messages in thread
From: Daniel Gustafsson @ 2026-07-17 10:41 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: Ian Lawrence Barwick <barwick@gmail.com>; Chao Li <li.evan.chao@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
> On 17 Jul 2026, at 12:00, Fujii Masao <masao.fujii@gmail.com> wrote:
> This is docs, not error message, but as error message style guide suggests,
> the word "non-negative" basically should be avoided since it's ambiguous
> about whether it accepts zero?
Yes, "non-negative" should absolutely be avoided.
> If we document what a value of 0 means, isn't it better to add a brief
> description about the value 0 to postgresql.conf.sample and guc_parameters.dat
> as well?
I think the bigger picture here is that IMO a user can be forgiven for thinking
at -1 and 0 are equal based on this sentence:
"A value of <literal>-1</literal> (the default) disables the timeout
mechanism"
To me as a non-native speaker reading that a timeout is disabled can be
interpreted as if there is no waiting done, just like the in the case of 0. +1
on documenting that 0 means immediate shutdown (though that is sort of implied)
but I think we at the same time should expand the above sentence to clarify
that -1 means waiting. After reading the docs I had to read the code to be
sure I had it right.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
@ 2026-07-17 22:38 ` Chao Li <li.evan.chao@gmail.com>
2026-08-04 15:11 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
0 siblings, 1 reply; 10+ messages in thread
From: Chao Li @ 2026-07-17 22:38 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Fujii Masao <masao.fujii@gmail.com>; Ian Lawrence Barwick <barwick@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
> On Jul 17, 2026, at 18:41, Daniel Gustafsson <daniel@yesql.se> wrote:
>
>> On 17 Jul 2026, at 12:00, Fujii Masao <masao.fujii@gmail.com> wrote:
>
>> This is docs, not error message, but as error message style guide suggests,
>> the word "non-negative" basically should be avoided since it's ambiguous
>> about whether it accepts zero?
>
> Yes, "non-negative" should absolutely be avoided.
>
>> If we document what a value of 0 means, isn't it better to add a brief
>> description about the value 0 to postgresql.conf.sample and guc_parameters.dat
>> as well?
>
> I think the bigger picture here is that IMO a user can be forgiven for thinking
> at -1 and 0 are equal based on this sentence:
>
> "A value of <literal>-1</literal> (the default) disables the timeout
> mechanism"
>
> To me as a non-native speaker reading that a timeout is disabled can be
> interpreted as if there is no waiting done, just like the in the case of 0. +1
> on documenting that 0 means immediate shutdown (though that is sort of implied)
> but I think we at the same time should expand the above sentence to clarify
> that -1 means waiting. After reading the docs I had to read the code to be
> sure I had it right.
>
> --
> Daniel Gustafsson
>
Thanks, everyone, for your comments. PFA v3 that attempts to address them all.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Attachments:
v3-0001-doc-Clarify-wal_sender_shutdown_timeout-behavior-.patch (application/octet-stream, 5.3K) download
From 1c3e2beea4da5cf60be9709064181a6de4527488 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 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 <lic@highgo.com>
Reviewed-by: Ian Barwick <barwick@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
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
- <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 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)
=
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
@ 2026-08-04 15:11 ` Fujii Masao <masao.fujii@gmail.com>
2026-08-04 16:54 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
2026-08-05 00:36 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
0 siblings, 2 replies; 10+ messages in thread
From: Fujii Masao @ 2026-08-04 15:11 UTC (permalink / raw)
To: Chao Li <li.evan.chao@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Ian Lawrence Barwick <barwick@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
On Sat, Jul 18, 2026 at 7:39 AM Chao Li <li.evan.chao@gmail.com> wrote:
> Thanks, everyone, for your comments. PFA v3 that attempts to address them all.
Thanks for updating the patch!
I made a few small adjustments on top of v3:
- Revised the commit message to better reflect the current wording.
- Clarified the GUC long description so that pg_settings explains
the difference between -1 and 0.
- Updated the postgresql.conf.sample comments to clarify that -1 disables
the timeout but still waits for catch-up, whereas 0 does not wait for
catch-up.
The main config.sgml documentation is unchanged from v3.
I've attached the updated version. Barring any objections, I'll commit it.
Regards,
--
Fujii Masao
Attachments:
v4-0001-doc-Clarify-wal_sender_shutdown_timeout-values.patch (application/octet-stream, 5.6K) download
From bdc5eacfa92f6ef0efe964f75f0119c856878656 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 v4] 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: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Daniel Gustafsson <daniel@yesql.se>
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 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
- <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 adb72361ce0..e2b48ea69e9 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -3572,7 +3572,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 7958653077b..493f57409e1 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)
--
2.55.0
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-08-04 15:11 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
@ 2026-08-04 16:54 ` Daniel Gustafsson <daniel@yesql.se>
1 sibling, 0 replies; 10+ messages in thread
From: Daniel Gustafsson @ 2026-08-04 16:54 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: Chao Li <li.evan.chao@gmail.com>; Ian Lawrence Barwick <barwick@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
> On 4 Aug 2026, at 17:11, Fujii Masao <masao.fujii@gmail.com> wrote:
> I've attached the updated version. Barring any objections, I'll commit it.
LGTM.
--
Daniel Gustafsson
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-08-04 15:11 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
@ 2026-08-05 00:36 ` Chao Li <li.evan.chao@gmail.com>
2026-08-05 02:44 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
1 sibling, 1 reply; 10+ messages in thread
From: Chao Li @ 2026-08-05 00:36 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Ian Lawrence Barwick <barwick@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
> On Aug 4, 2026, at 23:11, Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Sat, Jul 18, 2026 at 7:39 AM Chao Li <li.evan.chao@gmail.com> wrote:
>> Thanks, everyone, for your comments. PFA v3 that attempts to address them all.
>
> Thanks for updating the patch!
>
> I made a few small adjustments on top of v3:
>
> - Revised the commit message to better reflect the current wording.
> - Clarified the GUC long description so that pg_settings explains
> the difference between -1 and 0.
> - Updated the postgresql.conf.sample comments to clarify that -1 disables
> the timeout but still waits for catch-up, whereas 0 does not wait for
> catch-up.
>
> The main config.sgml documentation is unchanged from v3.
>
> I've attached the updated version. Barring any objections, I'll commit it.
>
> Regards,
>
> --
> Fujii Masao
> <v4-0001-doc-Clarify-wal_sender_shutdown_timeout-values.patch>
Thanks for updating the patch. V4 LGTM.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-08-04 15:11 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-08-05 00:36 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
@ 2026-08-05 02:44 ` Fujii Masao <masao.fujii@gmail.com>
2026-08-05 03:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
0 siblings, 1 reply; 10+ messages in thread
From: Fujii Masao @ 2026-08-05 02:44 UTC (permalink / raw)
To: Chao Li <li.evan.chao@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Ian Lawrence Barwick <barwick@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
On Wed, Aug 5, 2026 at 9:37 AM Chao Li <li.evan.chao@gmail.com> wrote:
> Thanks for updating the patch. V4 LGTM.
I've pushed the patch. Thanks!
Regards,
--
Fujii Masao
^ permalink raw reply [nested|flat] 10+ messages in thread
* Re: doc: clarify wal_sender_shutdown_timeout behavior for small values
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-08-04 15:11 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
2026-08-05 00:36 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-08-05 02:44 ` Re: doc: clarify wal_sender_shutdown_timeout behavior for small values Fujii Masao <masao.fujii@gmail.com>
@ 2026-08-05 03:38 ` Chao Li <li.evan.chao@gmail.com>
0 siblings, 0 replies; 10+ messages in thread
From: Chao Li @ 2026-08-05 03:38 UTC (permalink / raw)
To: Fujii Masao <masao.fujii@gmail.com>; +Cc: Daniel Gustafsson <daniel@yesql.se>; Ian Lawrence Barwick <barwick@gmail.com>; PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
> On Aug 5, 2026, at 10:44, Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Wed, Aug 5, 2026 at 9:37 AM Chao Li <li.evan.chao@gmail.com> wrote:
>> Thanks for updating the patch. V4 LGTM.
>
> I've pushed the patch. Thanks!
>
> Regards,
>
> --
> Fujii Masao
Thank you very much for taking care of this patch.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
^ permalink raw reply [nested|flat] 10+ messages in thread
end of thread, other threads:[~2026-08-05 03:38 UTC | newest]
Thread overview: 10+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-07-17 05:37 doc: clarify wal_sender_shutdown_timeout behavior for small values Chao Li <li.evan.chao@gmail.com>
2026-07-17 09:00 ` Ian Lawrence Barwick <barwick@gmail.com>
2026-07-17 10:00 ` Fujii Masao <masao.fujii@gmail.com>
2026-07-17 10:41 ` Daniel Gustafsson <daniel@yesql.se>
2026-07-17 22:38 ` Chao Li <li.evan.chao@gmail.com>
2026-08-04 15:11 ` Fujii Masao <masao.fujii@gmail.com>
2026-08-04 16:54 ` Daniel Gustafsson <daniel@yesql.se>
2026-08-05 00:36 ` Chao Li <li.evan.chao@gmail.com>
2026-08-05 02:44 ` Fujii Masao <masao.fujii@gmail.com>
2026-08-05 03:38 ` Chao Li <li.evan.chao@gmail.com>
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