What this SQLite WAL inspector checks
A WAL begins with one 32-byte header followed by fixed-size frames. This inspector checks the two allowed magic numbers, format version, power-of-two page size, header checksum, frame boundaries, page numbers, copied salts, and every cumulative frame checksum. The magic number controls the byte order used for checksum words; stored checksum fields and structural integers remain big-endian.
Commits and the recovery boundary
A non-zero second field in a frame header is a commit marker and gives the database size in pages after that transaction. SQLite recovery scans forward until the first invalid frame and uses the final valid commit, so later valid-looking bytes are not silently treated as recoverable. The transaction and page-history tables make that distinction explicit. A page number above a commit’s resulting database size is flagged for review, not declared corrupt: a transaction can shrink its database.
Why select the main database?
The optional database adds a narrow cross-check: signature, page size, WAL read/write version bytes, page count, schema cookie, user version, application ID, and SQLite version number. The header’s declared page count is trusted only when it is nonzero and its change counter matches the version-valid-for number; otherwise its physical size is reported without a false mismatch warning. This does not merge WAL pages into the database. Copying a live database without its matching WAL can omit recent committed transactions; use SQLite’s backup facilities for operational backups.
Validation boundary
This is a structural preflight, not PRAGMA integrity_check, a forensic recovery suite, or a database browser. It does not decode B-trees, schemas, records, freelists, overflow pages, rollback journals, or -shm wal-index files; reconstruct a database; distinguish deleted content; prove that the files belong together beyond their visible header facts; or establish logical consistency, authenticity, safety, or legal provenance. Inspect a stable copy, not files being changed by a running application.
Frequently asked questions
Why can a valid-looking frame be outside the recovery prefix?
SQLite stops its recovery scan at the first frame whose salt or cumulative checksum is invalid. Later bytes can be leftovers from an earlier WAL cycle or damaged data, so they are not re-admitted just because an isolated field looks plausible.
Does an uncommitted tail mean corruption?
No. Complete frames after the final commit marker can result from an interrupted or active write transaction. They remain intentionally separate from recoverable committed frames.
Can I safely delete a WAL after checking it?
No. A WAL may contain committed changes that have not been checkpointed into the main database. Let SQLite manage checkpointing and file lifecycle through a proper database connection.
Authoritative references
Use SQLite’s official WAL file-format and checksum specification, WAL-mode file and recovery notes, and write-ahead logging documentation for authoritative behavior and operational guidance.
Inspect an OLE/CFB container · Inspect a binary property list · Browse legacy-data tools