# I/O waits

> File reads, writes, synchronization, allocation, and asynchronous I/O completion.
---

`IO` means PostgreSQL has instrumented a file operation and the backend cannot continue until the kernel or another I/O worker makes progress. It says *which PostgreSQL file path* is involved; it does not, by itself, prove the storage is slow.

## Read event + operation + workload phase {#how-to-read}

Names usually encode both object and operation: `DataFileRead`, `WalSync`, `SlruWrite`, `ReorderBufferRead`. Ask whether the workload should be performing that operation now, then compare duration and concurrency with `pg_stat_io` (PG16+) and operating-system latency.

- **Normal:** scans read data files, checkpoints sync dirty files, backups read/write, recovery reads WAL.
- **Watch:** the same foreground I/O event persists in consecutive samples and device latency or query latency rises.
- **Urgent:** many backends queue behind sync/write completion, errors appear, or the affected path reaches saturation/throttling.

## Events to recognize {#top-events}

| Event | First interpretation |
| --- | --- |
| [DataFileRead](data-file-read/) | Cache miss or scan reading relation data |
| [DataFileWrite](data-file-write/) | Backend/checkpoint path writing relation data |
| [DataFileSync](data-file-sync/) | Relation changes are being made durable |
| [WalWrite](wal-write/) | WAL bytes are being written |
| [WalSync](wal-sync/) | WAL durability boundary is waiting on fsync/fdatasync |
| [SlruRead](slru-read/) | Transaction-related SLRU page read |
| [BuffileRead](buffile-read/) | Temp/spill file read |
| [AioIoCompletion](aio-io-completion/) | PG18 AIO work has not completed yet |

## PG16+ I/O context {#pg-stat-io}

```sql
SELECT backend_type, object, context,
       reads, read_time, writes, write_time,
       writebacks, fsyncs, fsync_time
FROM pg_stat_io
ORDER BY coalesce(read_time, 0) + coalesce(write_time, 0) + coalesce(fsync_time, 0) DESC;
```

## Common misreads {#misreads}

- A high count of `DataFileRead` during an intentional sequential scan can be healthy throughput.
- `WalWrite` and LWLock `WALWrite` are different: one is a file operation, the other internal coordination.
- Average device latency can hide a saturated single WAL volume or tail-latency spikes.
- Raising cache size cannot fix every read wait; poor plans and cold one-time scans may simply displace useful pages.

---

Section pages:

- [IO: AioIoCompletion](/io/aio-io-completion/): Waiting for another process to complete IO
- [IO: AioIoUringExecution](/io/aio-io-uring-execution/): Waiting for IO execution via io_uring
- [IO: AioIoUringSubmit](/io/aio-io-uring-submit/): Waiting for IO submission via io_uring
- [IO: BasebackupRead](/io/basebackup-read/): Waiting for base backup to read from a file
- [IO: BasebackupSync](/io/basebackup-sync/): Waiting for data written by a base backup to reach durable storage
- [IO: BasebackupWrite](/io/basebackup-write/): Waiting for base backup to write to a file
- [IO: BuffileRead](/io/buffile-read/): Waiting for a read from a buffered file
- [IO: BuffileTruncate](/io/buffile-truncate/): Waiting for a buffered file to be truncated
- [IO: BuffileWrite](/io/buffile-write/): Waiting for a write to a buffered file
- [IO: ControlFileRead](/io/control-file-read/): Waiting for a read from the pg_control file
- [IO: ControlFileSync](/io/control-file-sync/): Waiting for the pg_control file to reach durable storage
- [IO: ControlFileSyncUpdate](/io/control-file-sync-update/): Waiting for an update to the pg_control file to reach durable storage
- [IO: ControlFileWrite](/io/control-file-write/): Waiting for a write to the pg_control file
- [IO: ControlFileWriteUpdate](/io/control-file-write-update/): Waiting for a write to update the pg_control file
- [IO: CopyFileCopy](/io/copy-file-copy/): Waiting for a file copy operation
- [IO: CopyFileRead](/io/copy-file-read/): Waiting for a read during a file copy operation
- [IO: CopyFileWrite](/io/copy-file-write/): Waiting for a write during a file copy operation
- [IO: DataFileExtend](/io/data-file-extend/): Waiting for a relation data file to be extended
- [IO: DataFileFlush](/io/data-file-flush/): Waiting for a relation data file to reach durable storage
- [IO: DataFileImmediateSync](/io/data-file-immediate-sync/): Waiting for an immediate synchronization of a relation data file to durable storage
- [IO: DataFilePrefetch](/io/data-file-prefetch/): Waiting for an asynchronous prefetch from a relation data file
- [IO: DataFileRead](/io/data-file-read/): Waiting for a read from a relation data file
- [IO: DataFileSync](/io/data-file-sync/): Waiting for changes to a relation data file to reach durable storage
- [IO: DataFileTruncate](/io/data-file-truncate/): Waiting for a relation data file to be truncated
- [IO: DataFileWrite](/io/data-file-write/): Waiting for a write to a relation data file
- [IO: DsmAllocate](/io/dsm-allocate/): Waiting for a dynamic shared memory segment to be allocated
- [IO: DsmFillZeroWrite](/io/dsm-fill-zero-write/): Waiting to fill a dynamic shared memory backing file with zeroes
- [IO: LockFileAddtodatadirRead](/io/lock-file-addtodatadir-read/): Waiting for a read while adding a line to the data directory lock file
- [IO: LockFileAddtodatadirSync](/io/lock-file-addtodatadir-sync/): Waiting for data to reach durable storage while adding a line to the data directory lock file
- [IO: LockFileAddtodatadirWrite](/io/lock-file-addtodatadir-write/): Waiting for a write while adding a line to the data directory lock file
- [IO: LockFileCreateRead](/io/lock-file-create-read/): Waiting to read while creating the data directory lock file
- [IO: LockFileCreateSync](/io/lock-file-create-sync/): Waiting for data to reach durable storage while creating the data directory lock file
- [IO: LockFileCreateWrite](/io/lock-file-create-write/): Waiting for a write while creating the data directory lock file
- [IO: LockFileRecheckdatadirRead](/io/lock-file-recheckdatadir-read/): Waiting for a read during recheck of the data directory lock file
- [IO: LogicalChangesRead](/io/logical-changes-read/): Waiting for a read from a logical changes file.
- [IO: LogicalChangesWrite](/io/logical-changes-write/): Waiting for a write to a logical changes file.
- [IO: LogicalRewriteCheckpointSync](/io/logical-rewrite-checkpoint-sync/): Waiting for logical rewrite mappings to reach durable storage during a checkpoint
- [IO: LogicalRewriteMappingSync](/io/logical-rewrite-mapping-sync/): Waiting for mapping data to reach durable storage during a logical rewrite
- [IO: LogicalRewriteMappingWrite](/io/logical-rewrite-mapping-write/): Waiting for a write of mapping data during a logical rewrite
- [IO: LogicalRewriteSync](/io/logical-rewrite-sync/): Waiting for logical rewrite mappings to reach durable storage
- [IO: LogicalRewriteTruncate](/io/logical-rewrite-truncate/): Waiting for truncate of mapping data during a logical rewrite
- [IO: LogicalRewriteWrite](/io/logical-rewrite-write/): Waiting for a write of logical rewrite mappings
- [IO: LogicalSubxactRead](/io/logical-subxact-read/): Waiting for a read from a logical subxact file.
- [IO: LogicalSubxactWrite](/io/logical-subxact-write/): Waiting for a write to a logical subxact file.
- [IO: RelationMapRead](/io/relation-map-read/): Waiting for a read of the relation map file
- [IO: RelationMapReplace](/io/relation-map-replace/): Waiting for durable replacement of a relation map file
- [IO: RelationMapSync](/io/relation-map-sync/): Waiting for the relation map file to reach durable storage.
- [IO: RelationMapWrite](/io/relation-map-write/): Waiting for a write to the relation map file
- [IO: ReorderBufferRead](/io/reorder-buffer-read/): Waiting for a read during reorder buffer management
- [IO: ReorderBufferWrite](/io/reorder-buffer-write/): Waiting for a write during reorder buffer management
- [IO: ReorderLogicalMappingRead](/io/reorder-logical-mapping-read/): Waiting for a read of a logical mapping during reorder buffer management
- [IO: ReplicationSlotRead](/io/replication-slot-read/): Waiting for a read from a replication slot control file
- [IO: ReplicationSlotRestoreSync](/io/replication-slot-restore-sync/): Waiting for a replication slot control file to reach durable storage while restoring it to memory
- [IO: ReplicationSlotSync](/io/replication-slot-sync/): Waiting for a replication slot control file to reach durable storage
- [IO: ReplicationSlotWrite](/io/replication-slot-write/): Waiting for a write to a replication slot control file
- [IO: SlruFlushSync](/io/slru-flush-sync/): Waiting for SLRU data to reach durable storage during a checkpoint or database shutdown
- [IO: SlruRead](/io/slru-read/): Waiting for a read of an SLRU page
- [IO: SlruSync](/io/slru-sync/): Waiting for SLRU data to reach durable storage following a page write
- [IO: SlruWrite](/io/slru-write/): Waiting for a write of an SLRU page
- [IO: SnapbuildRead](/io/snapbuild-read/): Waiting for a read of a serialized historical catalog snapshot
- [IO: SnapbuildSync](/io/snapbuild-sync/): Waiting for a serialized historical catalog snapshot to reach durable storage
- [IO: SnapbuildWrite](/io/snapbuild-write/): Waiting for a write of a serialized historical catalog snapshot
- [IO: TimelineHistoryFileSync](/io/timeline-history-file-sync/): Waiting for a timeline history file received via streaming replication to reach durable storage
- [IO: TimelineHistoryFileWrite](/io/timeline-history-file-write/): Waiting for a write of a timeline history file received via streaming replication
- [IO: TimelineHistoryRead](/io/timeline-history-read/): Waiting for a read of a timeline history file
- [IO: TimelineHistorySync](/io/timeline-history-sync/): Waiting for a newly created timeline history file to reach durable storage
- [IO: TimelineHistoryWrite](/io/timeline-history-write/): Waiting for a write of a newly created timeline history file
- [IO: TwophaseFileRead](/io/twophase-file-read/): Waiting for a read of a two phase state file
- [IO: TwophaseFileSync](/io/twophase-file-sync/): Waiting for a two phase state file to reach durable storage
- [IO: TwophaseFileWrite](/io/twophase-file-write/): Waiting for a write of a two phase state file
- [IO: VersionFileSync](/io/version-file-sync/): Waiting for the version file to reach durable storage while creating a database
- [IO: VersionFileWrite](/io/version-file-write/): Waiting for the version file to be written while creating a database
- [IO: WalBootstrapSync](/io/wal-bootstrap-sync/): Waiting for WAL to reach durable storage during bootstrapping
- [IO: WalBootstrapWrite](/io/wal-bootstrap-write/): Waiting for a write of a WAL page during bootstrapping
- [IO: WalCopyRead](/io/wal-copy-read/): Waiting for a read when creating a new WAL segment by copying an existing one
- [IO: WalCopySync](/io/wal-copy-sync/): Waiting for a new WAL segment created by copying an existing one to reach durable storage
- [IO: WalCopyWrite](/io/wal-copy-write/): Waiting for a write when creating a new WAL segment by copying an existing one
- [IO: WalInitSync](/io/wal-init-sync/): Waiting for a newly initialized WAL file to reach durable storage
- [IO: WalInitWrite](/io/wal-init-write/): Waiting for a write while initializing a new WAL file
- [IO: WalRead](/io/wal-read/): Waiting for a read from a WAL file
- [IO: WalSummaryRead](/io/wal-summary-read/): Waiting for a read from a WAL summary file
- [IO: WalSummaryWrite](/io/wal-summary-write/): Waiting for a write to a WAL summary file
- [IO: WalSync](/io/wal-sync/): Waiting for a WAL file to reach durable storage
- [IO: WalSyncMethodAssign](/io/wal-sync-method-assign/): Waiting for data to reach durable storage while assigning a new WAL sync method
- [IO: WalWrite](/io/wal-write/): Waiting for a write to a WAL file
- [IO: WalsenderTimelineHistoryRead](/io/walsender-timeline-history-read/): Waiting for a read from a timeline history file during a walsender timeline command