debug_io_direct

Definition PG 18 manual

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.

How it works

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.

Operational considerations

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.

Workload guidance

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.