I wrote: > > On Thu, Oct 30, 2025 at 4:31 PM Fujii Masao <[email protected]> wrote: > > > > I also noticed another issue in the io_max_combine_limit docs. > > Since its context is PGC_POSTMASTER, shouldn't the following > > description be updated to say "This parameter can only be set at server > > start"? > > > > This parameter can only be set in > > the <filename>postgresql.conf</filename> file or on the server > > command line. > > > > Nice catch! I am going to check if there are other GUCs with > PGC_POSTMASTER and wrong documentation. I'll come back with an > updated version of the patch. >
I looked through all parameters in guc_parameters.dat that have PGC_POSTMASTER context. I lack the patience to go through all the GUCs, so I only checked those with PGC_POSTMASTER context for now. Here is the list of the parameters whose descriptions don't say "This parameter can only be set at server start." 1. Parameters with "This parameter can only be set in <filename>postgresql.conf</filename> file or on the server command line" instead of "This parameter can only be set at server start". I fixed these. * track_commit_timestamp * io_max_combine_limit * event_source 2. Parameters that have no description in the docs specifying when they could be set. I added "This parameter can only be set at server start" to their description. * wal_decode_buffer_size * max_notify_queue_pages * shared_memory_type * dynamic_shared_memory_type * debug_io_direct 3. The following parameters have one phrase "These parameters can only be set at server start" for the whole group before their descriptions. So they are okay. * recovery_target * recovery_target_name * recovery_target_time * recovery_target_xid * recovery_target_lsn * recovery_target_inclusive * recovery_target_timeline * recovery_target_action 4. Other * config_file It has GUC_DISALLOW_IN_FILE flag, so its doc looks ok to me: "This parameter can only be set on the <command>postgres</command> command line." * trace_connection_negotiation It is not documented at all. Should it be fixed? * huge_pages It has a phrase "With on, failure to request huge pages will prevent the server from starting up." from which it could be concluded that this parameter must be set at server start, but I added this explicitly anyway. I'm attaching these changes as a separate patch just in case. You can squash them if you like. Not sure what to do with the commitfest entry. Should I change it back to Needs review? Best regards, Karina Litskevich Postgres Professional: http://postgrespro.com/
From ca3fb8b600e8d4b7c2291c4aa86daecf416f863f Mon Sep 17 00:00:00 2001 From: Karina Litskevich <[email protected]> Date: Wed, 5 Nov 2025 16:32:36 +0300 Subject: [PATCH v2 2/2] doc: Fix description of GUCs with PGC_POSTMASTER context --- doc/src/sgml/config.sgml | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index e432c43449b..68023580021 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1760,7 +1760,8 @@ include_dir 'conf.d' <para> Controls whether huge pages are requested for the main shared memory area. Valid values are <literal>try</literal> (the default), - <literal>on</literal>, and <literal>off</literal>. With + <literal>on</literal>, and <literal>off</literal>. + This parameter can only be set at server start. With <varname>huge_pages</varname> set to <literal>try</literal>, the server will try to request huge pages, but fall back to the default if that fails. With <literal>on</literal>, failure to request huge pages @@ -2273,6 +2274,7 @@ include_dir 'conf.d' platform, is generally discouraged because it typically requires non-default kernel settings to allow for large allocations (see <xref linkend="sysvipc"/>). + This parameter can only be set at server start. </para> </listitem> </varlistentry> @@ -2300,6 +2302,7 @@ include_dir 'conf.d' however, it may be useful for debugging, when the <literal>pg_dynshmem</literal> directory is stored on a RAM disk, or when other shared memory facilities are not available. + This parameter can only be set at server start. </para> </listitem> </varlistentry> @@ -2413,6 +2416,7 @@ include_dir 'conf.d' <xref linkend="sql-notify"/> / <xref linkend="sql-listen"/> queue. The default value is 1048576. For 8 KB pages it allows to consume up to 8 GB of disk space. + This parameter can only be set at server start. </para> </listitem> </varlistentry> @@ -2694,9 +2698,7 @@ include_dir 'conf.d' <para> Controls the largest I/O size in operations that combine I/O, and silently limits the user-settable parameter <varname>io_combine_limit</varname>. - This parameter can only be set in - the <filename>postgresql.conf</filename> file or on the server - command line. + This parameter can only be set at server start. If this value is specified without units, it is taken as blocks, that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. The maximum possible size depends on the operating system and block @@ -3967,6 +3969,7 @@ include_dir 'conf.d' blocks to prefetch. If this value is specified without units, it is taken as bytes. The default is 512kB. + This parameter can only be set at server start. </para> </listitem> </varlistentry> @@ -4692,9 +4695,9 @@ restore_command = 'copy "C:\\server\\archivedir\\%f" "%p"' # Windows </term> <listitem> <para> - Record commit time of transactions. This parameter - can only be set in <filename>postgresql.conf</filename> file or on the server - command line. The default value is <literal>off</literal>. + Record commit time of transactions. + This parameter can only be set at server start. + The default value is <literal>off</literal>. </para> </listitem> </varlistentry> @@ -7043,8 +7046,7 @@ local0.* /var/log/postgresql determines the program name used to identify <productname>PostgreSQL</productname> messages in the log. The default is <literal>PostgreSQL</literal>. - This parameter can only be set in the <filename>postgresql.conf</filename> - file or on the server command line. + This parameter can only be set at server start. </para> </listitem> </varlistentry> @@ -12273,6 +12275,7 @@ dynamic_library_path = '/usr/local/lib/postgresql:$libdir' main data files, <literal>wal</literal> for WAL files, and <literal>wal_init</literal> for WAL files when being initially allocated. + This parameter can only be set at server start. </para> <para> Some operating systems and file systems do not support direct I/O, so -- 2.34.1
From b1f11c026fde0b8a2de5b95cc3abed72004cdc41 Mon Sep 17 00:00:00 2001 From: Karina Litskevich <[email protected]> Date: Wed, 8 Oct 2025 14:06:29 +0300 Subject: [PATCH v2 1/2] doc: Improve description of io_combine_limit and io_max_combine_limit --- doc/src/sgml/config.sgml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 06d1e4403b5..e432c43449b 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -2697,6 +2697,8 @@ include_dir 'conf.d' This parameter can only be set in the <filename>postgresql.conf</filename> file or on the server command line. + If this value is specified without units, it is taken as blocks, + that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. The maximum possible size depends on the operating system and block size, but is typically 1MB on Unix and 128kB on Windows. The default is 128kB. @@ -2716,6 +2718,8 @@ include_dir 'conf.d' higher than the <varname>io_max_combine_limit</varname> parameter, the lower value will silently be used instead, so both may need to be raised to increase the I/O size. + If this value is specified without units, it is taken as blocks, + that is <symbol>BLCKSZ</symbol> bytes, typically 8kB. The maximum possible size depends on the operating system and block size, but is typically 1MB on Unix and 128kB on Windows. The default is 128kB. -- 2.34.1
