io_max_combine_limit

io_max_combine_limit — Server-wide limit that clamps io_combine_limit. Observed in PG18–19 Beta 3; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 3, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA.

Note

Fact — official short description: “Server-wide limit that clamps io_combine_limit.”

Identity

Type , Valueinteger: Upstream pg_settings type
Context , Valuepostmaster: Requires a server restart
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	PG18
Present in	PG18–19 Beta 3
Removed in	No
Introduction commit	`10f664684751` — Introduce io_max_combine_limit.
Commit date	2025-03-19
Discussion	thread 1

Default history

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

How it works

io_max_combine_limit is the server-start ceiling that silently clamps the user-settable io_combine_limit. It protects the I/O subsystem from request sizes beyond the configured server policy.

This controls bytes per combined operation, not queue depth. The feasible maximum depends on operating system and BLCKSZ, typically 1MB on Unix and 128kB on Windows.

Raising io_combine_limit above this value has no effect until this startup parameter is also raised. Combined requests can still be smaller when adjacent work is unavailable. Its postmaster context fixes the value at server start; changing it requires a restart.

Tuning advice

Tip

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

Workload	Guidance
OLTP	Keep the PG18 server clamp at 128kB unless measurements show that larger combined requests improve eligible I/O without harming latency. Raising it alone changes nothing while io_combine_limit remains lower, and changing it requires a restart.
OLAP	A larger clamp merely permits a larger user combine limit; it does not create adjacent I/O or add concurrency. Benchmark actual request sizes, sequential throughput, and mixed-workload fairness with both parameters set intentionally.
Small nodes	Retain 128kB on small or mixed-use storage. Do not increase a restart-only global ceiling to fix queue-depth problems, which belong to the concurrency controls.

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: PG18–19 Beta 3 unmodified; OLAP: PG18–19 Beta 3 unmodified; CRIT: PG18–19 Beta 3 unmodified; TINY: PG18–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

Common pitfalls

Treating the server byte-size clamp as an I/O concurrency limit.
Raising io_max_combine_limit while io_combine_limit remains lower and expecting a change.
Expecting larger combined requests when adjacent eligible operations do not exist.
Ignoring operating-system and BLCKSZ limits, especially the smaller typical Windows maximum.
Forgetting that a change requires a server restart.

io_combine_limit · io_max_concurrency · io_method · shared_buffers