If Postgres crashes mid-transaction — power failure, kernel panic, out-of-memory kill — how does it guarantee that committed data isn't lost? The answer is WAL: Write-Ahead Logging.

The rule is simple: every change must be written to the WAL before it's written to the actual data files. When Postgres commits a transaction, it flushes the WAL record to disk. The data pages themselves can be written later, lazily, in the background. If the system crashes before those data pages hit disk, Postgres replays the WAL on startup and reconstructs the missing changes.

This design works because WAL writes are sequential — append-only to the end of a log file. Sequential I/O is dramatically faster than the random I/O required to update scattered data pages across the heap. It's the same principle behind every database's transaction log, but Postgres's implementation also serves double duty for replication and point-in-time recovery.

WAL is not a single growing file. It's divided into segments — 16 MB files by default — stored in the pg_wal/ directory of your data directory. Each segment is named with a combination of timeline ID and segment number in hexadecimal.

The current position in the WAL stream is identified by a Log Sequence Number (LSN) — a hexadecimal pointer in the format file/offset:

You can convert an LSN to the underlying WAL filename:

That filename breaks down as: timeline 00000001, segment 0000000000000003. The timeline changes on recovery or promotion (more on that later).

WAL alone doesn't solve durability — you also need a way to limit how much WAL must be replayed after a crash. That's what checkpoints do.

A checkpoint flushes all dirty pages from shared buffers to the data files on disk, then writes a checkpoint record to the WAL. After a checkpoint, all WAL before that record is no longer needed for crash recovery — those segments can be recycled or archived.

The frequency of checkpoints is controlled by two settings: time and WAL volume. Whichever threshold is hit first triggers a checkpoint.

checkpoints_timed is the count triggered by timeout; checkpoints_req is the count triggered by reaching max_wal_size. If checkpoints_req is climbing, your WAL volume is exceeding the configured size between checkpoints.

Postgres tracks WAL activity in the pg_stat_wal view:

Key columns: wal_fpi is full-page images (entire pages written to WAL after each checkpoint, to protect against torn writes). A high wal_buffers_full suggests wal_buffers is too small — WAL is being flushed before the buffer fills.

WAL behavior is controlled by a handful of settings in postgresql.conf. Getting these right matters for both performance and recoverability.

The most important WAL setting determines how much information is recorded:

Changing wal_level requires a restart. If you need replication or point-in-time recovery — and you almost certainly do — leave it at replica or higher.

For write-heavy workloads, increasing max_wal_size to 4-8 GB and checkpoint_timeout to 15-30 minutes reduces checkpoint frequency. The tradeoff: longer crash recovery time.

When set to on (or a specific algorithm like lz4 or zstd in PG 15+), Postgres compresses full-page images in WAL records. This reduces WAL volume — often by 30-50% — at the cost of some CPU. On I/O-bound systems, the net result is usually positive.

WAL segments are normally recycled after a checkpoint — the old data is gone. But if you archive those segments before recycling, you can combine them with a base backup to restore your database to any point in time. This is the foundation of Postgres disaster recovery.

When archive_mode is enabled, Postgres calls archive_command for each completed WAL segment. The %p placeholder is the full path to the segment file; %f is just the filename. The command must return exit code 0 on success — Postgres will retry indefinitely until archiving succeeds.

In production, you'd replace cp with something that ships WAL to durable storage — S3, GCS, a remote server:

A base backup is a physical copy of the data directory at a moment in time. On its own, it restores to that exact moment. Combined with archived WAL, it restores to any moment between the backup and the most recent WAL segment.

The key insight: a data directory copy without WAL is not a backup. If you snapshot the filesystem without ensuring WAL continuity, you have no guarantee of consistency or the ability to recover to a specific point.

The -X stream flag ensures WAL generated during the backup is included. This gives you a self-contained starting point — the archived WAL from that point forward extends your recovery window.

To restore to a specific moment — say, just before an accidental DROP TABLE at 2025-01-15 14:32:00:

1. Restore the most recent base backup before that time
2. Configure recovery to stop at the target time
3. Start Postgres — it replays WAL up to the target and stops

Create the recovery.signal file in the data directory, then start Postgres. It will replay WAL from the base backup through to 14:31:55 and then promote to a normal read-write server.

Every time you perform a recovery, Postgres creates a new timeline — incrementing the timeline ID in subsequent WAL filenames. This prevents confusion between WAL generated before and after a recovery event.

Timeline history files (e.g., 00000002.history) record when and why a new timeline was created. They're essential for understanding which WAL sequence to follow when you have multiple recovery points or standby promotions in your history.

A higher timeline number doesn't necessarily mean "more recent data" — it means "a different recovery branch." When planning PITR, you need to know which timeline contains the data you want.

WAL isn't only for crash recovery. Postgres's replication system is built directly on top of WAL — standbys receive and replay the same WAL stream that a recovering server would use.

In streaming replication, a standby connects to the primary and receives WAL records in real time over a TCP connection. The standby replays them continuously, staying seconds (or less) behind the primary.

Requirements on the primary:

For guaranteed WAL retention, use replication slots:

A replication slot prevents Postgres from recycling any WAL that the consumer hasn't received yet. This guarantees the standby can always catch up — but it also means an inactive slot can cause unbounded WAL accumulation. Monitor retained_bytes and drop slots for decommissioned standbys.

When wal_level = logical, Postgres decodes the physical WAL into logical row-level changes (INSERT, UPDATE, DELETE). This enables:

Logical replication is a large topic with its own guide — the key point here is that it's built on the same WAL infrastructure. The WAL is the single source of truth for all change propagation in Postgres.

For a deeper dive into streaming and logical replication setup, see the Replication Guide.

WAL is the foundation of everything reliable about Postgres. Durability, crash recovery, point-in-time restore, streaming replication, logical decoding — all of it flows from the same write-ahead log. Understanding WAL segments, LSNs, checkpoints, and archiving gives you the mental model to reason about backup strategies, replication lag, and recovery objectives. When something goes wrong at 3am, that mental model is what separates a confident recovery from a panicked one.

PostgreSQL Documentation — WAL Configuration

Official docs on WAL settings and tuning.

Crunchy Data Blog — Postgres WAL Files and Sequence Numbers

Understanding WAL file naming, LSNs, and segment management.

Crunchy Data Blog — The Rest is History: WAL History Files

Timeline IDs and history files explained.

Snowflake Postgres — Replication Guide

How WAL enables both streaming and logical replication.