io_combine_limit

io_combine_limit — Limit on the size of data reads and writes. Observed in PG17–19 Beta 3; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 3, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Limit on the size of data reads and writes.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valueuser: Settable by an ordinary user
Unit , Value8kB: Raw unit
Range , Value1 – 128: Raw limits in the last observed version
Enum values , Value—: — for non-enum types
Category , ValueResource Usage / I/O: Upstream classification
Latest boot value , Value16: 128 KiB (16 × 8kB)

Lifecycle

Fact	Value
First observed	PG17
Present in	PG17–19 Beta 3
Removed in	No
Introduction commit	`210622c60e1a` — Provide vectored variant of ReadBuffer().
Commit date	2024-04-03
Discussion	thread 1

Default history

Measured PG9.0–19 Beta 3 boot defaults
Versions	Raw `boot_val`	Unit	Human value
PG17–19 Beta 3	`16`	`8kB`	128 KiB (16 × 8kB)

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.

Tuning advice

Tip

Advice. These are workload-specific starting points and must be validated with measurements.

Workload	Guidance
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.
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.
Small nodes	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.

Pigsty

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

Template	Effective value	Versus upstream boot	Source expression
OLTP	Unmodified	—	—
OLAP	Unmodified	—	—
CRIT	Unmodified	—	—
TINY	Unmodified	—	—

Caution

Advice — pending human review. Fact from the current Pigsty template projection: OLTP: PG17–19 Beta 3 unmodified; OLAP: PG17–19 Beta 3 unmodified; CRIT: PG17–19 Beta 3 unmodified; TINY: PG17–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

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.

io_max_combine_limit · io_max_concurrency · io_method · effective_io_concurrency · maintenance_io_concurrency