Re: doc: Improve description of io_combine_limit and io_max_combine_limit GUCs

Hi,

On Wed, Oct 8, 2025 at 7:38 PM Karina Litskevich
<litskevichkarina(at)gmail(dot)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