doc: Improve description of io_combine_limit and io_max_combine_limit GUCs
Hi hackers,
I noticed that GUCs io_combine_limit and io_max_combine_limit are marked
as GUC_UNIT_BLOCKS, but in the documentation nothing is said about that.
Other GUCs marked as GUC_UNIT_BLOCKS have a phrase "If this value is
specified without units, it is taken as blocks, that is BLCKSZ bytes,
typically 8kB" in their descriptions in the documentation. Please find
the attached patch that adds the same phrase for io_combine_limit and
io_max_combine_limit. This will need backpatching: io_combine_limit has
been present since PostgreSQL 17, and io_max_combine_limit since
PostgreSQL 18.
I also have a question about the main part of the description of these
GUCs. It says, "Controls the largest I/O size in operations that combine
I/O." From what I can see, these GUCs really only affect read operations,
and this description looks misleading to me. Am I wrong?
Best regards,
Karina Litskevich
Postgres Professional: http://postgrespro.com/
Attachments:
v1-0001-doc-Improve-description-of-io_combine_limit-and-i.patchtext/x-patch; charset=US-ASCII; name=v1-0001-doc-Improve-description-of-io_combine_limit-and-i.patchDownload
From b1d0b0f83523312d7b28759d79212ecb6a229f29 Mon Sep 17 00:00:00 2001
From: Karina Litskevich <litskevichkarina@gmail.com>
Date: Wed, 8 Oct 2025 14:06:29 +0300
Subject: [PATCH v1] 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 39e658b7808..5007698671e 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
On Oct 8, 2025, at 19:38, Karina Litskevich <litskevichkarina@gmail.com> wrote:
Hi hackers,
I noticed that GUCs io_combine_limit and io_max_combine_limit are marked
as GUC_UNIT_BLOCKS, but in the documentation nothing is said about that.
Other GUCs marked as GUC_UNIT_BLOCKS have a phrase "If this value is
specified without units, it is taken as blocks, that is BLCKSZ bytes,
typically 8kB" in their descriptions in the documentation. Please find
the attached patch that adds the same phrase for io_combine_limit and
io_max_combine_limit. This will need backpatching: io_combine_limit has
been present since PostgreSQL 17, and io_max_combine_limit since
PostgreSQL 18.I also have a question about the main part of the description of these
GUCs. It says, "Controls the largest I/O size in operations that combine
I/O." From what I can see, these GUCs really only affect read operations,
and this description looks misleading to me. Am I wrong?Best regards,
Karina Litskevich
Postgres Professional: http://postgrespro.com/
<v1-0001-doc-Improve-description-of-io_combine_limit-and-i.patch>
I agree that is a good catch.
I verified that, if I set in postgresql.conf:
```
io_combine_limit = 1 # usually 1-128 blocks (depends on OS)
```
Then I get:
```
evantest=# show io_combine_limit;
io_combine_limit
------------------
8kB
(1 row)
```
And if I set:
```
io_combine_limit = 12bkB # usually 1-128 blocks (depends on OS)
```
Then I get:
```
evantest=# show io_combine_limit;
io_combine_limit
------------------
128kB
(1 row)
```
So, this patch looks good to me. Please any committer takes care of this patch.
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Thu, Oct 9, 2025 at 6:05 AM Chao Li <li.evan.chao@gmail.com> wrote:
So, this patch looks good to me. Please any committer takes care of this patch.
Thank you for the review!
Could you please change the status of the commitfest entry [1]https://commitfest.postgresql.org/patch/6115/ to
Ready for Commiter if you believe it's ready?
[1]: https://commitfest.postgresql.org/patch/6115/
Best regards,
Karina Litskevich
Postgres Professional: http://postgrespro.com/
On Oct 13, 2025, at 19:33, Karina Litskevich <litskevichkarina@gmail.com> wrote:
On Thu, Oct 9, 2025 at 6:05 AM Chao Li <li.evan.chao@gmail.com> wrote:
So, this patch looks good to me. Please any committer takes care of this patch.
Thank you for the review!
Could you please change the status of the commitfest entry [1] to
Ready for Commiter if you believe it's ready?
Done.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Hi,
On Wed, Oct 8, 2025 at 7:38 PM Karina Litskevich
<litskevichkarina@gmail.com> wrote:
Hi hackers,
I noticed that GUCs io_combine_limit and io_max_combine_limit are marked
as GUC_UNIT_BLOCKS, but in the documentation nothing is said about that.
Other GUCs marked as GUC_UNIT_BLOCKS have a phrase "If this value is
specified without units, it is taken as blocks, that is BLCKSZ bytes,
typically 8kB" in their descriptions in the documentation. Please find
the attached patch that adds the same phrase for io_combine_limit and
io_max_combine_limit. This will need backpatching: io_combine_limit has
been present since PostgreSQL 17, and io_max_combine_limit since
PostgreSQL 18.I also have a question about the main part of the description of these
GUCs. It says, "Controls the largest I/O size in operations that combine
I/O." From what I can see, these GUCs really only affect read operations,
and this description looks misleading to me. Am I wrong?
+1 for this — it seems a useful addition, and the wording is
consistent with existing parameters like pg_multixact, shared_buffers,
and others.
During a benchmark run, I once set io_combine_limit to 256, mistakenly
assuming it represented 256 kB. As a result, the server in ubuntu
failed to start with the following log message:
LOG: 256 8kB is outside the valid range for parameter
"io_combine_limit" (1 8kB .. 128 8kB)
Only then did I realize my misunderstanding — and I imagine this could
happen to other users as well.
Best,
Xuneng
On Mon, Oct 13, 2025 at 10:33 PM Chao Li <li.evan.chao@gmail.com> wrote:
On Oct 13, 2025, at 19:33, Karina Litskevich <litskevichkarina@gmail.com> wrote:
On Thu, Oct 9, 2025 at 6:05 AM Chao Li <li.evan.chao@gmail.com> wrote:
So, this patch looks good to me. Please any committer takes care of this patch.
Thank you for the review!
Could you please change the status of the commitfest entry [1] to
Ready for Commiter if you believe it's ready?[1] https://commitfest.postgresql.org/patch/6115/
Done.
The patch looks good to me.
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.
Regards,
--
Fujii Masao
On Thu, Oct 30, 2025 at 4:31 PM Fujii Masao <masao.fujii@gmail.com> 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.
Best regards,
Karina Litskevich
Postgres Professional: http://postgrespro.com/
I wrote:
On Thu, Oct 30, 2025 at 4:31 PM Fujii Masao <masao.fujii@gmail.com> 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/
Attachments:
v2-0002-doc-Fix-description-of-GUCs-with-PGC_POSTMASTER-c.patchtext/x-patch; charset=US-ASCII; name=v2-0002-doc-Fix-description-of-GUCs-with-PGC_POSTMASTER-c.patchDownload
From ca3fb8b600e8d4b7c2291c4aa86daecf416f863f Mon Sep 17 00:00:00 2001
From: Karina Litskevich <litskevichkarina@gmail.com>
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
v2-0001-doc-Improve-description-of-io_combine_limit-and-i.patchtext/x-patch; charset=US-ASCII; name=v2-0001-doc-Improve-description-of-io_combine_limit-and-i.patchDownload
From b1f11c026fde0b8a2de5b95cc3abed72004cdc41 Mon Sep 17 00:00:00 2001
From: Karina Litskevich <litskevichkarina@gmail.com>
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
On Nov 5, 2025, at 21:58, Karina Litskevich <litskevichkarina@gmail.com> wrote:
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/
<v2-0002-doc-Fix-description-of-GUCs-with-PGC_POSTMASTER-c.patch><v2-0001-doc-Improve-description-of-io_combine_limit-and-i.patch>
```
- 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.
```I think this change will lose information. Actually, I think that even the original message is not accurate enough. For PGC_POSTMASTER parameters, there are 3 ways to update their values:
* Editing postgres.conf
* server command line
* ALTER SYSTEM, updating postgres.auto.conf
But all require a server restart. The original doc misses “ALTER SYSTEM”, and your change just hides all methods. So I would suggest:
```
This parameter can only be set at server start (for example, in postgresql.conf, via ALTER SYSTEM, or on the server command line).
```
Fujii-san, what do you think?
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
On Thu, Nov 6, 2025 at 9:00 AM Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 5, 2025, at 21:58, Karina Litskevich <litskevichkarina@gmail.com> wrote:
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/
<v2-0002-doc-Fix-description-of-GUCs-with-PGC_POSTMASTER-c.patch><v2-0001-doc-Improve-description-of-io_combine_limit-and-i.patch>``` - 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. ```I think this change will lose information. Actually, I think that even the original message is not accurate enough. For PGC_POSTMASTER parameters, there are 3 ways to update their values:
* Editing postgres.conf
* server command line
* ALTER SYSTEM, updating postgres.auto.confBut all require a server restart. The original doc misses “ALTER SYSTEM”, and your change just hides all methods. So I would suggest:
```
This parameter can only be set at server start (for example, in postgresql.conf, via ALTER SYSTEM, or on the server command line).
```Fujii-san, what do you think?
The general information about how to set GUC parameters is already explained
at the top of config.sgml, which seems sufficient to me. So I don't think it's
an improvement to update the description this way for each parameter.
Regards,
--
Fujii Masao
On Wed, Nov 5, 2025 at 10:59 PM Karina Litskevich
<litskevichkarina@gmail.com> wrote:
* trace_connection_negotiation
It is not documented at all. Should it be fixed?
Since other developer parameters like trace_* are already documented,
it seems good to also add trace_connection_negotiation to the docs.
I noticed that a patch for this was already proposed in [1]/messages/by-id/CABV9wwPMuKfPf_u36hZmYmbnyZ9e8QvjSCO=EfeyrU+c+=xehA@mail.gmail.com, so it might be
better to revive that thread and review it there.
[1]: /messages/by-id/CABV9wwPMuKfPf_u36hZmYmbnyZ9e8QvjSCO=EfeyrU+c+=xehA@mail.gmail.com
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?
Thanks for the patches! I've pushed them and marked the CF entry as "Committed".
Regards,
--
Fujii Masao