{"Entry":{"collection":"guc","key":"debug_io_direct","name":"debug_io_direct","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Developer Options","category_zh":"","changed_in":["18"],"changes":[{"documentation_changed":false,"fields":{},"from":"15","status":"added","to":"16"},{"documentation_changed":false,"fields":{"extra_desc":{"from":null,"to":"An empty string disables direct I/O."}},"from":"17","status":"changed","to":"18"}],"content_hash":"ffb2c067f273300934fbebe5044f784ec962a4e05b2e65ab06a8f136517420d3","context":"","default_changed_in":[],"default_history":[{"from":"16","to":"19","value":"Empty string"}],"editorial":{"advice":{"olap":"Long analytical runs can amplify debug_io_direct's debug overhead and artifacts. Prefer standard EXPLAIN and statistics first, and isolate any developer experiment from normal users.","oltp":"Do not tune production OLTP with debug_io_direct. Enable it only for a bounded reproduction with an owner, log/disk budget, rollback condition, and evidence-capture plan; restore the default immediately afterward.","small":"Keep debug_io_direct at its upstream default. A small host has less spare CPU, disk, connection, and log capacity for developer instrumentation."},"mechanism":["debug_io_direct requests cache-bypassing file access for selected operations: data, wal, and wal_init. PostgreSQL maps this to O_DIRECT, F_NOCACHE, or FILE_FLAG_NO_BUFFERING according to platform.","The empty string disables direct I/O. Unsupported kernels or file systems can reject startup or fail operations, and alignment constraints differ across platforms.","PostgreSQL documentation explicitly describes current nondefault use as performance-reducing developer testing. It is distinct from the PG18 asynchronous-I/O method and should not be presented as a production cache policy. Its postmaster context fixes the value at server start; changing it requires a restart."],"pitfalls":["Leaving debug_io_direct enabled after the bounded diagnostic or recovery task.","Running the experiment on the only copy of production data.","Underestimating log, core-file, temporary-file, WAL, CPU, or connection-slot amplification.","Treating a server that merely starts or completes a query as proof that data and behavior are correct."],"references":[{"title":"PostgreSQL 19 Beta 4: debug_io_direct","url":"https://www.postgresql.org/docs/19/runtime-config-developer.html#GUC-DEBUG-IO-DIRECT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["io_method","io_max_concurrency","wal_sync_method","shared_buffers","backend_flush_after"],"summary":"debug_io_direct — Use direct I/O for file access. Observed in PG16–19 Beta 4; its last measured boot default is empty string in PG19 Beta 4, with postmaster context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"16","group":"Developer Options","group_slug":"developer","imported_at":"2026-09-27T17:57:31.046722+08:00","intro_commit":{"authored_at":"2023-05-15T10:31:14+12:00","discussion":["https://postgr.es/m/20230430041106.GA2268796%40rfd.leadboat.com"],"hash":"319bae9a8da66678d80d862440e54cebc7b1cc24","subject":"Rename io_direct to debug_io_direct.","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=319bae9a8da66678d80d862440e54cebc7b1cc24"},"key":"debug_io_direct","last_version":"20","max_val":"","min_val":"","name":"debug_io_direct","position":87,"present_in":["16","17","18","19","20"],"short_desc":"Ask the kernel to minimize caching effects for relation data and WAL files using O_DIRECT (most Unix-like systems), F_NOCACHE (macOS) or FILE_FLAG_NO_BUFFERING (Windows).","short_desc_zh":"","source_rev":"english-manuals:3ada53439cad554f8c39b009bbbcfc7db5c3e904cec7a4f757618e5234e1289b","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"debug_io_direct","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"debug_io_direct","SourceRevision":"english-manuals:3ada53439cad554f8c39b009bbbcfc7db5c3e904cec7a4f757618e5234e1289b","Facts":{"boot_val":"","category":"Developer Options","context":"postmaster","description":"Ask the kernel to minimize caching effects for relation data and WAL files using O_DIRECT (most Unix-like systems), F_NOCACHE (macOS) or FILE_FLAG_NO_BUFFERING (Windows). May be set to an empty string (the default) to disable use of direct I/O, or a comma-separated list of operations that should use direct I/O. The valid options are data for main data files, wal for WAL files, and wal_init for WAL files when being initially allocated. This parameter can only be set at server start. Some operating systems and file systems do not support direct I/O, so non-default settings may be rejected at startup or cause errors. Currently this feature reduces performance, and is intended for developer testing only.","doc":{"anchor":"GUC-DEBUG-IO-DIRECT","file":"runtime-config-developer.html","lang":"en","sha256":"f5e7e39d176c642ac0799c87669ce2f6f60fcd97d109e290860ec74c36d7ecad","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"An empty string disables direct I/O.","lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"debug_io_direct","short_desc":"Use direct I/O for file access.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-DEBUG-IO-DIRECT","file":"runtime-config-developer.html","lang":"en","sha256":"f5e7e39d176c642ac0799c87669ce2f6f60fcd97d109e290860ec74c36d7ecad","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"debug_io_direct","SourceDatabase":"center","Version":"18","Locale":"en","Title":"debug_io_direct","Summary":"Ask the kernel to minimize caching effects for relation data and WAL files using O_DIRECT (most Unix-like systems), F_NOCACHE (macOS) or FILE_FLAG_NO_BUFFERING (Windows). May be set to an empty string (the default) to disable use of direct I/O, or a comma-separated list of operations that should use direct I/O. The valid options are data for main data files, wal for WAL files, and wal_init for WAL files when being initially allocated. This parameter can only be set at server start. Some operating systems and file systems do not support direct I/O, so non-default settings may be rejected at startup or cause errors. Currently this feature reduces performance, and is intended for developer testing only.","BodyHTML":"\u003cp\u003eAsk the kernel to minimize caching effects for relation data and WAL files using O_DIRECT (most Unix-like systems), F_NOCACHE (macOS) or FILE_FLAG_NO_BUFFERING (Windows). May be set to an empty string (the default) to disable use of direct I/O, or a comma-separated list of operations that should use direct I/O. The valid options are data for main data files, wal for WAL files, and wal_init for WAL files when being initially allocated. This parameter can only be set at server start. Some operating systems and file systems do not support direct I/O, so non-default settings may be rejected at startup or cause errors. Currently this feature reduces performance, and is intended for developer testing only.\u003c/p\u003e","SourceRevision":"english-manuals:3ada53439cad554f8c39b009bbbcfc7db5c3e904cec7a4f757618e5234e1289b","ContentHash":"0cb7ec5221c1fc9e660eadbe6fe27394615adc50c6887e75a7e5fb356d1407e2","Payload":{"description":"Ask the kernel to minimize caching effects for relation data and WAL files using O_DIRECT (most Unix-like systems), F_NOCACHE (macOS) or FILE_FLAG_NO_BUFFERING (Windows). May be set to an empty string (the default) to disable use of direct I/O, or a comma-separated list of operations that should use direct I/O. The valid options are data for main data files, wal for WAL files, and wal_init for WAL files when being initially allocated. This parameter can only be set at server start. Some operating systems and file systems do not support direct I/O, so non-default settings may be rejected at startup or cause errors. Currently this feature reduces performance, and is intended for developer testing only."}},"RequestedLocale":"zh-Hans","Fallback":true,"Versions":["16","17","18","19","20"],"Locales":["en"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}