From: Chao Li <li.evan.chao@gmail.com>
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_05E377D2-E297-4775-8146-9493B808FB53"
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3864.600.51.1.1\))
Subject: doc: clarify wal_sender_shutdown_timeout behavior for small values
Message-Id: <AF4FE756-A220-4DA7-87B7-A126F3F307FD@gmail.com>
Date: Fri, 17 Jul 2026 13:37:02 +0800
Cc: Fujii Masao <masao.fujii@gmail.com>
To: PostgreSQL-development <pgsql-hackers@lists.postgresql.org>
Archived-At: 
 <https://www.postgresql.org/message-id/AF4FE756-A220-4DA7-87B7-A126F3F307FD%40gmail.com>
Precedence: bulk


--Apple-Mail=_05E377D2-E297-4775-8146-9493B808FB53
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=us-ascii

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/


--Apple-Mail=_05E377D2-E297-4775-8146-9493B808FB53
Content-Disposition: attachment;
	filename=v1-0001-doc-Clarify-wal_sender_shutdown_timeout-behavior-.patch
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="v1-0001-doc-Clarify-wal_sender_shutdown_timeout-behavior-.patch"
Content-Transfer-Encoding: quoted-printable

=46rom=20178311692a2cab384b80a920f0a8adf7f36078b8=20Mon=20Sep=2017=20=
00:00:00=202001=0AFrom:=20"Chao=20Li=20(Evan)"=20<lic@highgo.com>=0A=
Date:=20Fri,=2017=20Jul=202026=2013:24:08=20+0800=0ASubject:=20[PATCH=20=
v1]=20doc:=20Clarify=20wal_sender_shutdown_timeout=20behavior=20for=0A=20=
small=20values=0A=0ADocument=20that=20nonnegative=20values=20enable=20=
the=20timeout=20and=20that=20zero=20causes=0Athe=20WAL=20sender=20to=20=
terminate=20without=20waiting=20for=20the=20receiver=20to=20catch=20up.=0A=
Also=20caution=20against=20values=20too=20small=20to=20allow=20catch-up,=20=
especially=20for=0Aphysical=20replication.=0A=0AWhile=20here,=20fix=20=
nearby=20indentation=20and=20add=20blank=20lines=20between=20paragraphs.=0A=
=0AAuthor:=20Chao=20Li=20<lic@highgo.com>=0A---=0A=20=
doc/src/sgml/config.sgml=20|=2029=20++++++++++++++++++-----------=0A=201=20=
file=20changed,=2018=20insertions(+),=2011=20deletions(-)=0A=0Adiff=20=
--git=20a/doc/src/sgml/config.sgml=20b/doc/src/sgml/config.sgml=0Aindex=20=
aa7b1bd75d2..b7c462e0f26=20100644=0A---=20a/doc/src/sgml/config.sgml=0A=
+++=20b/doc/src/sgml/config.sgml=0A@@=20-4990,21=20+4990,28=20@@=20=
restore_command=20=3D=20'copy=20"C:\\server\\archivedir\\%f"=20"%p"'=20=20=
#=20Windows=0A=20=20=20=20=20=20=20=20=20without=20units,=20it=20is=20=
taken=20as=20milliseconds.=20=20A=20value=20of=0A=20=20=20=20=20=20=20=20=
=20<literal>-1</literal>=20(the=20default)=20disables=20the=20timeout=20=
mechanism.=0A=20=20=20=20=20=20=20=20</para>=0A+=0A=20=20=20=20=20=20=20=20=
<para>=0A-=20=20=20=20=20=20=20When=20replication=20is=20in=20use,=20the=20=
sending=20server=20normally=20waits=20until=0A-=20=20=20=20=20=20=20all=20=
WAL=20data=20has=20been=20transferred=20to=20the=20receiver=20before=20=
completing=0A-=20=20=20=20=20=20=20shutdown.=20=20This=20helps=20keep=20=
sender=20and=20receiver=20in=20sync=20after=20shutdown,=0A-=20=20=20=20=20=
=20=20which=20is=20especially=20important=20for=20physical=20replication=20=
switchovers,=0A-=20=20=20=20=20=20=20but=20it=20can=20delay=20shutdown.=0A=
+=20=20=20=20=20=20=20=20When=20replication=20is=20in=20use,=20the=20=
sending=20server=20normally=20waits=20until=0A+=20=20=20=20=20=20=20=20=
all=20WAL=20data=20has=20been=20transferred=20to=20the=20receiver=20=
before=20completing=0A+=20=20=20=20=20=20=20=20shutdown.=20=20This=20=
helps=20keep=20sender=20and=20receiver=20in=20sync=20after=20shutdown,=0A=
+=20=20=20=20=20=20=20=20which=20is=20especially=20important=20for=20=
physical=20replication=20switchovers,=0A+=20=20=20=20=20=20=20=20but=20=
it=20can=20delay=20shutdown.=0A=20=20=20=20=20=20=20=20</para>=0A+=0A=20=20=
=20=20=20=20=20=20<para>=0A-=20=20=20=20=20=20=20=20If=20this=20=
parameter=20is=20set,=20the=20server=20stops=20waiting=20and=20completes=0A=
-=20=20=20=20=20=20=20=20shutdown=20when=20the=20timeout=20expires.=20=20=
This=20can=20shorten=20shutdown=20time,=0A-=20=20=20=20=20=20=20=20for=20=
example,=20when=20replication=20is=20slow=20on=20high-latency=20networks=20=
or=0A-=20=20=20=20=20=20=20=20when=20a=20logical=20replication=20apply=20=
worker=20is=20blocked=20waiting=20for=20locks.=0A-=20=20=20=20=20=20=20=20=
However,=20in=20this=20case=20the=20sender=20and=20receiver=20may=20be=20=
out=20of=20sync=20after=0A-=20=20=20=20=20=20=20=20shutdown.=0A+=20=20=20=
=20=20=20=20=20If=20this=20parameter=20is=20set=20to=20a=20nonnegative=20=
value,=20the=20server=20stops=0A+=20=20=20=20=20=20=20=20waiting=20and=20=
completes=20shutdown=20when=20the=20timeout=20expires.=20=20This=20can=0A=
+=20=20=20=20=20=20=20=20shorten=20shutdown=20time,=20for=20example,=20=
when=20replication=20is=20slow=20on=0A+=20=20=20=20=20=20=20=20=
high-latency=20networks=20or=20when=20a=20logical=20replication=20apply=20=
worker=20is=0A+=20=20=20=20=20=20=20=20blocked=20waiting=20for=20locks.=20=
=20However,=20in=20this=20case=20the=20sender=20and=0A+=20=20=20=20=20=20=
=20=20receiver=20may=20be=20out=20of=20sync=20after=20shutdown.=20=20In=20=
particular,=20a=20value=20of=0A+=20=20=20=20=20=20=20=20=
<literal>0</literal>=20causes=20the=20WAL=20sender=20to=20terminate=20=
without=20waiting=0A+=20=20=20=20=20=20=20=20for=20the=20receiver=20to=20=
catch=20up.=20=20Therefore,=20<literal>0</literal>=20or=20a=0A+=20=20=20=20=
=20=20=20=20value=20too=20small=20to=20allow=20the=20receiver=20to=20=
catch=20up=20should=20be=20used=20with=0A+=20=20=20=20=20=20=20=20=
caution,=20especially=20for=20physical=20replication.=0A=20=20=20=20=20=20=
=20=20</para>=0A+=0A=20=20=20=20=20=20=20=20<para>=0A=20=20=20=20=20=20=20=
=20=20This=20parameter=20can=20be=20set=20in=20=
<varname>primary_conninfo</varname>=20and=0A=20=20=20=20=20=20=20=20=20=
in=20the=20<literal>CONNECTION</literal>=20clause=20of=0A--=20=0A2.50.1=20=
(Apple=20Git-155)=0A=0A=

--Apple-Mail=_05E377D2-E297-4775-8146-9493B808FB53--