wal_buffers

Definition PG 18 manual

The amount of shared memory used for WAL data that has not yet been written to disk. The default setting of -1 selects a size equal to 1/32nd (about 3%) of shared_buffers, but not less than 64kB nor more than the size of one WAL segment, typically 16MB. This value can be set manually if the automatic choice is too large or too small, but any positive value less than 32kB will be treated as 32kB. If this value is specified without units, it is taken as WAL blocks, that is XLOG_BLCKSZ bytes, typically 8kB. This parameter can only be set at server start.

The contents of the WAL buffers are written out to disk at every transaction commit, so extremely large values are unlikely to provide a significant benefit. However, setting this value to at least a few megabytes can improve write performance on a busy server where many clients are committing at once. The auto-tuning selected by the default setting of -1 should give reasonable results in most cases.

How it works

Sets the number of disk-page buffers in shared memory for WAL. The value is fixed when the server starts, so changing it requires a restart.

The automatic -1 value chooses about 1/32 of shared_buffers, bounded below and by one WAL segment. The buffer absorbs WAL records before writes; too little can add WALWrite pressure during bursts, while oversized allocation consumes startup shared memory without replacing durable flushes.

Monitor and change wal_buffers together with fsync, full_page_writes, wal_sync_method. Validate on the relevant server role and real workload, then use its postmaster context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Reading -1 as a negative allocation rather than automatic sizing.

Forgetting that the automatic choice is based on shared_buffers and capped at one WAL segment.

Reading an unqualified positive value as bytes rather than WAL blocks; very small positives are raised to the minimum.

Allocating a large manual buffer without evidence of WALInsert/WALWrite pressure.

Expecting more WAL buffers to replace durable flushes or improve a storage-bound WALSync path.

Workload guidance

OLAP: Provision WAL, archive bandwidth, and recovery I/O for bulk-load peaks. Coordinate load pacing and checkpoints when reducing spikes; never break the recovery chain for throughput.

OLTP: Establish durability and recovery objectives first, then tune wal_buffers from WAL rate, flush latency, checkpoints, and peak pg_wal usage. Validate every change with crash/recovery and archive monitoring.

SMALL: Start from safe defaults and set explicit alerts for limited disk capacity. Do not disable durability or break the recovery chain merely to save modest I/O.