{"Entry":{"collection":"guc","key":"io_combine_limit","name":"io_combine_limit","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Resource Usage / I/O","category_zh":"","changed_in":["18"],"changes":[{"documentation_changed":false,"fields":{},"from":"16","status":"added","to":"17"},{"documentation_changed":true,"fields":{"category":{"from":"Resource Usage / Asynchronous Behavior","to":"Resource Usage / I/O"},"max_val":{"from":"32","to":"128"}},"from":"17","status":"changed","to":"18"}],"content_hash":"d3472901a58ff0c7e2bbb669e96cfd337f584642cda796b3a87eb02d4b14f4ef","context":"","default_changed_in":[],"default_history":[{"from":"17","to":"19","value":"128 KiB (16 × 8kB)"}],"editorial":{"advice":{"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."},"mechanism":["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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: io_combine_limit","url":"https://www.postgresql.org/docs/19/runtime-config-resource.html#GUC-IO-COMBINE-LIMIT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["io_max_combine_limit","io_max_concurrency","io_method","effective_io_concurrency","maintenance_io_concurrency"],"summary":"io_combine_limit — Limit on the size of data reads and writes. Observed in PG17–19 Beta 4; its last measured boot default is 128 KiB (16 × 8kB) in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"17","group":"Resource Usage","group_slug":"resource","imported_at":"2026-09-27T17:57:31.401056+08:00","intro_commit":{"authored_at":"2024-04-03T00:03:08+13:00","discussion":["https://postgr.es/m/CA+hUKGJkOiOCa+mag4BF+zHo7qo=o9CFheB8=g6uT5TUm2gkvA@mail.gmail.com"],"hash":"210622c60e1a9db2e2730140b8106ab57d259d15","subject":"Provide vectored variant of ReadBuffer().","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=210622c60e1a9db2e2730140b8106ab57d259d15"},"key":"io_combine_limit","last_version":"20","max_val":"","min_val":"","name":"io_combine_limit","position":181,"present_in":["17","18","19","20"],"short_desc":"Controls the largest I/O size in operations that combine I/O.","short_desc_zh":"","source_rev":"english-manuals:12aac3e95d7b6631b86606f7caed7e393bf490ec820eef133d858e574a688f4a","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"io_combine_limit","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"io_combine_limit","SourceRevision":"english-manuals:12aac3e95d7b6631b86606f7caed7e393bf490ec820eef133d858e574a688f4a","Facts":{"boot_val":"16","category":"Resource Usage / I/O","context":"user","description":"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.","doc":{"anchor":"GUC-IO-COMBINE-LIMIT","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":"128","metadata_version":"18","min_val":"1","name":"io_combine_limit","short_desc":"Limit on the size of data reads and writes.","source":"pg-settings-source-snapshot","unit":"8kB","vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-IO-COMBINE-LIMIT","file":"runtime-config-resource.html","lang":"en","sha256":"2e207c599f0884dfbe594558c478a2c7c132578981071e980e2015f31dfce28c","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"io_combine_limit","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"io_combine_limit","Summary":"","BodyHTML":"\u003cp\u003e控制合并 I/O 操作时允许的最大 I/O 大小。如果设置值高于 \u003ccode\u003eio_max_combine_limit\u003c/code\u003e 参数，则会静默使用较低的那个值，因此如果要增大 I/O 大小，可能需要同时提高这两个参数。如果该值未指定单位，则按块计算，也就是 \u003ccode\u003eBLCKSZ\u003c/code\u003e 字节，通常为 8kB。最大可能值取决于操作系统和块大小，但在 Unix 上通常为 1MB，在 Windows 上通常为 128kB。默认值是 128kB。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"7468ae50933a51691b088a5f85ccdc3386918804d0eb739e1bef2f3aadf8c5fb","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e控制合并 I/O 操作时允许的最大 I/O 大小。如果设置值高于 \u003ccode class=\"varname\"\u003eio_max_combine_limit\u003c/code\u003e 参数，则会静默使用较低的那个值，因此如果要增大 I/O 大小，可能需要同时提高这两个参数。如果该值未指定单位，则按块计算，也就是 \u003ccode class=\"symbol\"\u003eBLCKSZ\u003c/code\u003e 字节，通常为 8kB。最大可能值取决于操作系统和块大小，但在 Unix 上通常为 1MB，在 Windows 上通常为 128kB。默认值是 128kB。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}