What the SQLite -shm file is
SQLite’s WAL-index is a transient shared-memory cache for finding pages in a write-ahead log and coordinating clients. Its multi-byte fields use the writer machine’s native byte order, unlike the portable main database and WAL files. The first 136 bytes contain two 48-byte header copies plus checkpoint information and reserved lock bytes. Each 32 KiB unit also contains a page-number array and a hash table. The first unit holds 4,062 page mappings; later units hold 4,096 each.
What this inspector checks
The tool recognizes a supported header copy by its format version, initialized flag, and native-order checksum; reports whether the two copies agree; and checks page size, mxFrame capacity, backfill counters, read marks, active page mappings, and hash pointers. A selected WAL adds checksum, salt, page-size, frame-count, committed-boundary, and mapped-page comparisons. Filters and paginated tables keep large indexes navigable.
Use stable copies, not live sidecars
SQLite can rewrite the wal-index while it is mapped by running processes, and the file is not fsync’d for crash recovery. A copied -shm and -wal may represent different instants even when both are internally readable. Header-copy or cross-file differences are evidence to investigate, not automatic proof of corruption. Use SQLite’s backup API for a dependable backup; do not delete or patch sidecars based on this report.
Validation boundary
This is a bounded structural inspection, not database recovery or integrity validation. It does not interpret lock bytes as active locks, decode B-trees or records, reconstruct SQLite views, verify every hash-chain lookup, prove a consistent snapshot, diagnose SQL semantics, repair files, or replace SQLite’s own recovery and integrity checks. The -shm file itself is not required for WAL recovery.
Frequently asked questions
Does an absent or stale -shm mean the database is lost?
No. SQLite rebuilds its WAL-index from the WAL when needed. The WAL, not the -shm cache, matters for recovery.
Why might the two header copies differ?
SQLite writes one copy and then the other while coordinating clients. A live or non-atomic file copy may capture them at different moments; inspect a stable snapshot.
Can this tell which process holds a WAL lock?
No. The reserved lock bytes are not a portable record of lock ownership. The tool deliberately does not read them as lock state.
Authoritative reference
SQLite’s WAL-mode file format documents the wal-index headers, mappings, hash arrays, locks, lifecycle, and recovery behavior.