Date: Fri, 11 Sep 2026 10:34:45 -0500
From: Nathan Bossart <nathandbossart@gmail.com>
To: =?utf-8?Q?=C3=81lvaro?= Herrera <alvherre@kurilemu.de>
Cc: Chao Li <li.evan.chao@gmail.com>, Fujii Masao <masao.fujii@gmail.com>,
	Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>,
	pgsql-hackers@postgresql.org
Subject: Re: fixes for a few GUC descriptions
Message-ID: <aqQfleGBvlEiDQbE@nathan>
References: <DB0C90EE-0485-405E-80D5-A1A6703E52C8@gmail.com>
 <aqPFjLQs5KzqAiCl@alvherre.pgsql>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="OzAxZwZk1264o+ni"
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <aqPFjLQs5KzqAiCl@alvherre.pgsql>
Archived-At: <https://www.postgresql.org/message-id/aqQfleGBvlEiDQbE%40nathan>
Precedence: bulk

--OzAxZwZk1264o+ni
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit

On Fri, Sep 11, 2026 at 11:14:03AM +0200, Álvaro Herrera wrote:
> Maybe it should say "0 means do not wait, -1 means wait indefinitely."
> This complements the short_desc,
> 
>   Sets the maximum time the server waits during shutdown for all WAL data
>   to be replicated to the receiver.
> 
> I think the words "for the receiver to catch up" is somehow at odds with
> the short_desc's "for all WAL data to be replicated".  They should be
> saying the same thing, but aren't.

WFM.  v2 uses that wording, except -1 is listed first so that the special
values stay in ascending order.

I was considering back-patching this to v19.  I'd rather not update the
descriptions in released versions, although I'm not even sure anything in
released versions need fixing.  Any concerns about this?

-- 
nathan

--OzAxZwZk1264o+ni
Content-Type: text/plain; charset=utf-8
Content-Disposition: attachment;
	filename=v2-0001-Describe-special-values-in-more-GUC-descriptions.patch
Content-Transfer-Encoding: 8bit

From 2ea9715a91a3101641e2ff8e8271eb2a6236efb4 Mon Sep 17 00:00:00 2001
From: Nathan Bossart <nathan@postgresql.org>
Date: Fri, 11 Sep 2026 10:27:16 -0500
Subject: [PATCH v2 1/1] Describe special values in more GUC descriptions.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Commit 977d865c36 established some rules for mentioning special
values (e.g., -1, 0, an empty string) in GUC descriptions.  A few
parameters either neglect to mention their special values or
describe them in a way that doesn't follow those rules.  Most of
these parameters were added after the aforementioned commit.  This
commit fixes them.

Reviewed-by: Bharath Rupireddy <bharath.rupireddyforpostgres@gmail.com>
Reviewed-by: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Chao Li <li.evan.chao@gmail.com>
Reviewed-by: Álvaro Herrera <alvherre@kurilemu.de>
Discussion: https://postgr.es/m/aqMkIpRr62cVqtCZ%40nathan
---
 src/backend/utils/misc/guc_parameters.dat | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/src/backend/utils/misc/guc_parameters.dat b/src/backend/utils/misc/guc_parameters.dat
index 93a434858bf..c57441f7d98 100644
--- a/src/backend/utils/misc/guc_parameters.dat
+++ b/src/backend/utils/misc/guc_parameters.dat
@@ -1303,6 +1303,7 @@
 
 { name => 'idle_replication_slot_timeout', type => 'int', context => 'PGC_SIGHUP', group => 'REPLICATION_SENDING',
   short_desc => 'Sets the duration a replication slot can remain idle before it is invalidated.',
+  long_desc => '0 disables the timeout.',
   flags => 'GUC_UNIT_S',
   variable => 'idle_replication_slot_timeout_secs',
   boot_val => '0',
@@ -1389,6 +1390,7 @@
 
 { name => 'io_max_concurrency', type => 'int', context => 'PGC_POSTMASTER', group => 'RESOURCES_IO',
   short_desc => 'Max number of IOs that one process can execute simultaneously.',
+  long_desc => '-1 means use a value based on "shared_buffers" and the maximum number of processes.',
   variable => 'io_max_concurrency',
   boot_val => '-1',
   min => '-1',
@@ -1876,7 +1878,7 @@
 
 { name => 'log_statement_max_length', type => 'int', context => 'PGC_SUSET', group => 'LOGGING_WHAT',
   short_desc => 'Sets the maximum length in bytes of logged statement text.',
-  long_desc => '-1 means log statement in full; 0 means log only an ellipsis.',
+  long_desc => '-1 means log statements in full. 0 means log only an ellipsis.',
   flags => 'GUC_UNIT_BYTE',
   variable => 'log_statement_max_length',
   boot_val => '-1',
@@ -2368,7 +2370,7 @@
 
 { name => 'password_expiration_warning_threshold', type => 'int', context => 'PGC_SIGHUP', group => 'CONN_AUTH_AUTH',
   short_desc => 'Threshold for password expiration warnings.',
-  long_desc => '0 means not to emit these warnings.',
+  long_desc => '0 disables these warnings.',
   flags => 'GUC_UNIT_S',
   variable => 'password_expiration_warning_threshold',
   boot_val => '604800',
@@ -3580,7 +3582,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 and waits for the receiver to catch up; 0 does not wait for the receiver to catch up.',
+  long_desc => '-1 means wait indefinitely. 0 means do not wait.',
   flags => 'GUC_UNIT_MS',
   variable => 'wal_sender_shutdown_timeout',
   boot_val => '-1',
@@ -3590,6 +3592,7 @@
 
 { name => 'wal_sender_timeout', type => 'int', context => 'PGC_USERSET', group => 'REPLICATION_SENDING',
   short_desc => 'Sets the maximum time to wait for WAL replication.',
+  long_desc => '0 disables the timeout.',
   flags => 'GUC_UNIT_MS',
   variable => 'wal_sender_timeout',
   boot_val => '60 * 1000',
-- 
2.55.0


--OzAxZwZk1264o+ni--