{"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"}],"derived_content_hash":"a6768380b43a0999576c3ed379d46dfd7697102eeec4e53be560d55fb9535ddd","documentation_refresh":{"batch":"20261113","original_source_rev":"wiki-repair-20261023:c186c9df03ff7a7ce954189068d33072989e6abbf6f09e62924c12154a77b254","versions":{"16":"16.16","17":"17.12","18":"18.7","19":"19rc2"}},"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"],"repair_provenance":{"original_source_revision":"english-manuals:3ada53439cad554f8c39b009bbbcfc7db5c3e904cec7a4f757618e5234e1289b","receipt_sha256":"7c7867ea54007634761714f6f56bc1ede240fbe89197897e49f63beeb8818d20","repair":"wiki-repair-20261023"},"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":"wiki-repair-20261023:c186c9df03ff7a7ce954189068d33072989e6abbf6f09e62924c12154a77b254","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"debug_io_direct","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"debug_io_direct","SourceRevision":"wiki-repair-20261023:c186c9df03ff7a7ce954189068d33072989e6abbf6f09e62924c12154a77b254","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.","description_zh":"要求内核使用 O_DIRECT（大多数类 Unix 系统）、F_NOCACHE（macOS）或 FILE_FLAG_NO_BUFFERING（Windows），尽量减小关系数据和 WAL 文件缓存的影响。 可以将其设置为空字符串（默认值）以禁用直接 I/O，也可以设置为应使用直接 I/O 的操作列表，各项之间用逗号分隔。有效选项包括 data（主数据文件）、wal（WAL 文件）和 wal_init（WAL 文件初始分配时）。这个参数只能在服务器启动时设置。 某些操作系统和文件系统不支持直接 I/O，因此非默认设置可能会在启动时被拒绝或导致错误。 目前该特性会降低性能，仅用于开发人员测试。","description_zh_html":"\u003cp\u003e\n        要求内核使用 \u003ccode class=\"literal\"\u003eO_DIRECT\u003c/code\u003e（大多数类 Unix 系统）、\u003ccode class=\"literal\"\u003eF_NOCACHE\u003c/code\u003e（macOS）或 \u003ccode class=\"literal\"\u003eFILE_FLAG_NO_BUFFERING\u003c/code\u003e（Windows），尽量减小关系数据和 WAL 文件缓存的影响。\n       \u003c/p\u003e\u003cp\u003e\n        可以将其设置为空字符串（默认值）以禁用直接 I/O，也可以设置为应使用直接 I/O 的操作列表，各项之间用逗号分隔。有效选项包括 \u003ccode class=\"literal\"\u003edata\u003c/code\u003e（主数据文件）、\u003ccode class=\"literal\"\u003ewal\u003c/code\u003e（WAL 文件）和 \u003ccode class=\"literal\"\u003ewal_init\u003c/code\u003e（WAL 文件初始分配时）。这个参数只能在服务器启动时设置。\n       \u003c/p\u003e\u003cp\u003e\n        某些操作系统和文件系统不支持直接 I/O，因此非默认设置可能会在启动时被拒绝或导致错误。\n       \u003c/p\u003e\u003cp\u003e\n        目前该特性会降低性能，仅用于开发人员测试。\n       \u003c/p\u003e","doc":{"anchor":"GUC-DEBUG-IO-DIRECT","file":"runtime-config-developer.html","lang":"en","sha256":"a3f6a107ed6ba4edaf6df03e52f4a469bd09350d545e4ff419e62844025ec1cf","slug":"18"},"doc_html":"\u003cp\u003e\n        Ask the kernel to minimize caching effects for relation data and WAL\n        files using \u003ccode class=\"literal\"\u003eO_DIRECT\u003c/code\u003e (most Unix-like systems),\n        \u003ccode class=\"literal\"\u003eF_NOCACHE\u003c/code\u003e (macOS) or\n        \u003ccode class=\"literal\"\u003eFILE_FLAG_NO_BUFFERING\u003c/code\u003e (Windows).\n       \u003c/p\u003e\u003cp\u003e\n        May be set to an empty string (the default) to disable use of direct\n        I/O, or a comma-separated list of operations that should use direct I/O.\n        The valid options are \u003ccode class=\"literal\"\u003edata\u003c/code\u003e for\n        main data files, \u003ccode class=\"literal\"\u003ewal\u003c/code\u003e for WAL files, and\n        \u003ccode class=\"literal\"\u003ewal_init\u003c/code\u003e for WAL files when being initially\n        allocated.\n        This parameter can only be set at server start.\n       \u003c/p\u003e\u003cp\u003e\n        Some operating systems and file systems do not support direct I/O, so\n        non-default settings may be rejected at startup or cause errors.\n       \u003c/p\u003e\u003cp\u003e\n        Currently this feature reduces performance, and is intended for\n        developer testing only.\n       \u003c/p\u003e","doc_same_as":"","documentation_revision":{"inputs":[{"file":"runtime-config-developer.html","kind":"same-version-reviewed-manual","locale":"en","sha256":"a3f6a107ed6ba4edaf6df03e52f4a469bd09350d545e4ff419e62844025ec1cf","version":"18.7"},{"file":"runtime-config-developer.html","kind":"same-version-reviewed-manual","locale":"zh-Hans","sha256":"e7e22aa5738a1d376b84af1adca796c5e14746266733f925eb50c3ef86a50655","version":"18.7"}],"release":"18.7","runtime_remeasured":false,"source_revision":"pgdoc:b9f0e7232f60f380d642ac9b99226606c254b552"},"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","translation_provenance":{"inputs":[{"kind":"current-pgdoc-translation","path":"/Users/vonng/pgsty/pgdoc/zh/18/html/runtime-config-developer.html","sha256":"3c08bf624188bbb0733dc7854e61c0c251c2578311ac3dc8fa626ab21b7911d1"}],"kind":"same-version-pgdoc","locale":"zh-Hans","source_revision":"b1b500221dbe5437cfca004d6b04d3f6e422765d","version":"18"},"unit":null,"vartype":"string","zh_from":"same-version-manual"},"ManualEvidence":{"doc":{"anchor":"GUC-DEBUG-IO-DIRECT","file":"runtime-config-developer.html","lang":"en","sha256":"a3f6a107ed6ba4edaf6df03e52f4a469bd09350d545e4ff419e62844025ec1cf","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\u003e\n        Ask the kernel to minimize caching effects for relation data and WAL\n        files using \u003ccode\u003eO_DIRECT\u003c/code\u003e (most Unix-like systems),\n        \u003ccode\u003eF_NOCACHE\u003c/code\u003e (macOS) or\n        \u003ccode\u003eFILE_FLAG_NO_BUFFERING\u003c/code\u003e (Windows).\n       \u003c/p\u003e\u003cp\u003e\n        May be set to an empty string (the default) to disable use of direct\n        I/O, or a comma-separated list of operations that should use direct I/O.\n        The valid options are \u003ccode\u003edata\u003c/code\u003e for\n        main data files, \u003ccode\u003ewal\u003c/code\u003e for WAL files, and\n        \u003ccode\u003ewal_init\u003c/code\u003e for WAL files when being initially\n        allocated.\n        This parameter can only be set at server start.\n       \u003c/p\u003e\u003cp\u003e\n        Some operating systems and file systems do not support direct I/O, so\n        non-default settings may be rejected at startup or cause errors.\n       \u003c/p\u003e\u003cp\u003e\n        Currently this feature reduces performance, and is intended for\n        developer testing only.\n       \u003c/p\u003e","SourceRevision":"wiki-repair-20261023:c186c9df03ff7a7ce954189068d33072989e6abbf6f09e62924c12154a77b254","ContentHash":"e36aa97b4e20d082631f59db81c323541b3acee2aa8c58dd803e36882cd07e11","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":"en","Fallback":false,"Versions":["16","17","18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}