Explain how SQLite's write-ahead logging (WAL) checkpoint process works?

In WAL mode, committed transactions accumulate as appended entries in the WAL file rather than being written into the main database file immediately. A checkpoint is the process that periodically copies those accumulated WAL entries into the main database file, after which the WAL file can be reset (or truncated) since its contents are now reflected in the main file.

flowchart LR
    A[WAL file accumulates committed pages] --> B{Checkpoint triggered}
    B --> C[Copy WAL pages into main DB file, in order]
    C --> D[WAL file reset/truncated]
    D --> A

Checkpoints happen automatically by default once the WAL file grows past a threshold (roughly 1000 pages), but can also be triggered manually via PRAGMA wal_checkpoint. A checkpoint has to wait for any readers still using older WAL content to finish before it can safely truncate the WAL file, which is why a long-running read transaction can cause the WAL file to grow larger than usual — checkpointing is effectively paused (or partial) until that reader completes.