Обсуждение: 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/

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/

Best regards,
Karina Litskevich
Postgres Professional: http://postgrespro.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/

> 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_POSTMASTERparameters, 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
wouldsuggest: 

```
This parameter can only be set at server start (for example, in postgresql.conf, via ALTER SYSTEM, or on the server
commandline). 
```

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.
ForPGC_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
Iwould suggest: 
>
> ```
> This parameter can only be set at server start (for example, in postgresql.conf, via ALTER SYSTEM, or on the server
commandline). 
> ```
>
> 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], so it might be
better to revive that thread and review it there.

[1] https://postgr.es/m/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