How a Checkpoint Works in PostgreSQL

How a Checkpoint Works Internally in PostgreSQL

The Checkpointer performs the following steps

The Checkpointer performs the following steps

  1. Marks a Safe Point (Redo LSN): PostgreSQL identifies a position in the WAL called the Redo LSN and writes a CKPT_START record. If a crash happens later, the database knows it only needs to recover data starting from this exact point forward.

  2. Writes “Dirty Pages” Slowly: It identifies all data changed in memory (dirty pages) and writes them to the operating system cache. It does this slowly (Spreading) to prevent the hard drive from freezing up for users.

  3. Forces Data to Be Permanent (fsync): The checkpointer issues an fsync() call to ensure that all modified database pages written from the shared buffer cache to the operating system’s page cache are safely flushed to the database files on persistent storage.

  4. Writes a Success Receipt: A CKPT_END record is written to the WAL to seal the process. Only after this succeeds is the pg_control file updated with the Redo LSN (from Step 1) to officially confirm to the entire system that the checkpoint finished safely.

  5. Triggers WAL Cleanup (Recycling/Removal Decision)

Now that data is safely on disk, old WAL files are no longer needed for crash recovery. However, Postgres only deletes or reuses them after checking these rules:

PostgreSQL checks:

  • min_wal_size
    • Keep at least this much WAL available.
    • WAL files below this threshold are usually recycled instead of removed.
  • max_wal_size
    • If total WAL exceeds this value, PostgreSQL tries to recycle or remove old WAL files after the checkpoint.
  • archive_mode / archive_command
    • If WAL archiving is enabled, a WAL file cannot be removed or recycled until it has been successfully archived.
    • The corresponding .ready file changes to .done only after successful archiving.
  • wal_keep_size
    • Prevents removal of WAL files that may still be needed by streaming replication standbys.
  • slot_wal_keep_size / Replication Slots
    • WAL required by any replication slot must be retained.
    • If a standby has fallen behind, PostgreSQL keeps the required WAL files until the slot no longer needs them (subject to slot_wal_keep_size if configured).

Crash Recovery During Instance Startup

If the database crashes during Step 2 or Step 3, the pg_control file still points to the previous successful checkpoint. Because pg_control is not updated until the very end of Step 4, Postgres knows on reboot that the current checkpoint failed, ignores it completely, and safely recovers using the older, valid checkpoint instead.

Checkpoint TriggerDescription
Time-basedAutomatically triggered every checkpoint_timeout (default: 5 minutes).
WAL Size LimitTriggered when the total WAL generated exceeds max_wal_size, allowing PostgreSQL to control WAL growth.
Manual CheckpointA DBA manually initiates a checkpoint using: CHECKPOINT;
Smart / Fast ShutdownDuring a normal server shutdown, PostgreSQL performs a checkpoint to ensure that all dirty buffers are written to disk, reducing recovery time during the next startup.
Immediate ShutdownNo checkpoint is performed. The server terminates immediately, requiring crash recovery during the next startup.
pg_basebackupBy default, pg_basebackup requests the primary server to perform a checkpoint before copying data files, ensuring a consistent physical backup.
Checkpoint behavior can be controlled using:
--checkpoint=fast - Completes as quickly as possible
or
--checkpoint=spread (Default) - Spreads writes over checkpoint_completion_target
Crash RecoveryAfter replaying all required WAL records following an unexpected shutdown, PostgreSQL automatically writes a new checkpoint before accepting client connections.
Point-in-Time Recovery (PITR)After recovery reaches the requested recovery target, PostgreSQL performs a checkpoint before opening the database for normal operation.
Standby PromotionWhen a standby server is promoted to become the new primary, PostgreSQL performs a checkpoint to establish a new recovery starting point.
Caution: Your use of any information or materials on this website is entirely at your own risk. It is provided for educational purposes only. It has been tested internally, however, we do not guarantee that it will work for you. Ensure that you run it in your test environment before using.
Thank you
Rajasekhar Amudala
Email: br8dba@gmail.com
LinkedIn: linkedin.com/in/rajasekhar-amudala