doc: clarify wal_sender_shutdown_timeout behavior for small values

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

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

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

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/

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

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

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/

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

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/