doc: clarify wal_sender_shutdown_timeout behavior for small values

From: Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com>
To: PostgreSQL-development <pgsql-hackers(at)lists(dot)postgresql(dot)org>
Cc: Fujii Masao <masao(dot)fujii(at)gmail(dot)com>
Subject: doc: clarify wal_sender_shutdown_timeout behavior for small values
Date: 2026-07-17 05:37:02
Message-ID: AF4FE756-A220-4DA7-87B7-A126F3F307FD@gmail.com
Views: Whole Thread | Raw Message | Download mbox | Resend email
Thread:
Lists: pgsql-hackers

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/

Attachment Content-Type Size
v1-0001-doc-Clarify-wal_sender_shutdown_timeout-behavior-.patch application/octet-stream 3.1 KB

Responses

Browse pgsql-hackers by date

  From Date Subject
Next Message Rafia Sabih 2026-07-17 06:38:35 Re: Available disk space per tablespace
Previous Message Tom Lane 2026-07-17 05:33:57 Re: sequencesync worker race with REFRESH SEQUENCES