io_combine_limit

Definition PG 18 manual

Controls the largest I/O size in operations that combine I/O. If set higher than the io_max_combine_limit 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 BLCKSZ 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.

How it works

io_combine_limit limits the byte size of one I/O request formed by combining adjacent eligible operations. It controls bytes per request, not the number of requests that may execute concurrently.

In PostgreSQL 17 it is a standalone user-settable combine-size limit with a measured Linux-Docker boot value of 128kB; io_max_combine_limit does not exist in that release. In PostgreSQL 18, the effective size is the lower of io_combine_limit and the new server-start io_max_combine_limit.

Actual requests can be smaller when adjacent work is unavailable, and operating-system plus BLCKSZ constraints bound the feasible maximum. Its user context permits session- or transaction-local changes; changing it does not alter io_max_concurrency or worker count.

Operational considerations

Applying the PG18 io_max_combine_limit clamp to PostgreSQL 17, where that GUC does not exist.

Treating a byte-size limit as I/O concurrency or queue depth.

Raising io_combine_limit above the PG18 server clamp and expecting larger requests.

Assuming every eligible operation reaches the configured size even when adjacent I/O is unavailable.

Workload guidance

OLAP: Larger combined requests can reduce syscall overhead during eligible sequential work, but may increase service time and reduce fairness. Compare throughput, latency, and actual request sizes; do not infer a useful value from device queue depth alone.

OLTP: Keep the version-appropriate default until a benchmark shows that combined-request size, rather than queue depth, is a bottleneck. In PG18, verify both io_combine_limit and io_max_combine_limit, and measure tail latency under realistic concurrency.

SMALL: Retain 128kB unless measured adjacent I/O shows a benefit from another size. On PG18, raising only io_combine_limit above io_max_combine_limit is ineffective; on PG17 there is no separate clamp GUC.