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