A SQLite Commit Can Live Outside the Main Database File

Compare the requested metadata state with the offered file

If an AI platform keeps its metadata in WAL-mode SQLite, a request for the database after an identified commit concerns a logical state. A file offered as metadata.db is a particular storage artifact. The comparison is whether that artifact includes the requested committed content.

SQLite's WAL documentation explains why these descriptions can diverge. Changes can be committed in the WAL while the main database remains unchanged. The WAL is part of the database's persistent state, rather than merely a record of activity that has already reached the main file.

This article compares committed page visibility and artifact contents. Power-failure durability and the completeness of application state outside this database require separate evidence.

References: [SW]

A commit makes page versions eligible within a reader's boundary

SQLite's file-format description defines a WAL frame as a revised database page with a frame header. A transaction ends in a frame carrying a commit marker. The frame's commit information identifies the database size in pages after that commit; ordinary frames have zero in that field. Frames also have validity requirements, including matching salts and checksums.

A read transaction selects a committed WAL end mark. For a requested page, the applicable version is its latest valid WAL frame at or before that boundary. If no such version exists, the reader uses the main database page. Later physical content is outside this selected view.

SQLite's isolation documentation explains the resulting stable snapshot: commits made by another connection while the read transaction remains active do not advance that transaction's view. The relevant comparison names the selected state, rather than assuming every reader sees the newest physical contents.

References: [SF][SW][SI]

WAL-P2: one committed page and two later frames

WAL-P2 is a fictional page-selection example. Stipulate a valid matching main database and WAL, with the required headers and frame validity. A1, A2, B2, C1 and C2 label whole-page content identities. They are not row values or actual binary database images, and the example is not an executed database test.

For the two pages being compared, the main file contains page 1=A1 and page 2=A2. WAL frame 1 contains page 2=B2 and ends a committed transaction. A separate reader selects end mark 1. No checkpoint has transferred B2 into the main file.

A later writer has appended frame 2 containing page 2=C2 and frame 3 containing page 1=C1. These later frames are stipulated valid, but neither carries a commit marker and no later commit follows them. The reader's boundary remains frame 1.

These premises distinguish three things that can otherwise be called the latest database: the reader's committed state, the main file's contents and the last physically present version of each page.

The logical read is A1/B2

For page 1, the only WAL version in the example is C1 at frame 3. It is beyond end mark 1, so it is ineligible. The reader obtains page 1 from the main file: A1.

For page 2, frame 1 supplies B2 and is itself a commit frame. Frame 2's C2 is beyond the selected boundary. The applicable page 2 is therefore B2. The reader's pair is A1/B2: one page from the main file and one from the WAL, together representing the stipulated committed state.

The standalone main artifact contains A1/A2. It represents the earlier state in this example and omits the committed B2 revision. The commit can be successful while this artifact still fails a request for the state including B2.

Selecting the last physical frame for each page would instead produce C1/C2. Both selected frames would lie outside the reader's committed boundary. Their valid frame contents do not establish a later committed transaction. This third result explains why including more physical material is not the same as identifying the required logical state.

References: [SF]

Checkpointing changes placement; the wal-index helps locate pages

Checkpointing transfers committed WAL content into the main database. It is a distinct operation from committing. SQLite's checkpoint interface documentation explicitly allows a checkpoint to leave work unfinished when concurrent readers or writers prevent further progress. A statement that checkpointing occurred therefore needs its extent connected to the state being offered.

In a counterfactual version of WAL-P2 where B2 has been coherently incorporated into the main file and the compared committed state remains fixed, the main pages would be A1/B2. The required page contents would then be present there. The first example's difference came from where B2 resided.

The wal-index has another role. SQLite's Unix and Windows WAL implementation documentation describes shared-memory coordination and a cache for locating WAL frames, usually associated with a -shm file. It contains no database page content. The file-format specification calls the wal-index transient and describes its reconstruction from the WAL. It cannot supply the missing B2 page in a main-file-only offer.

References: [SC][SM][SF]

A standalone file can be sufficient when its state is established

WAL-P2 does not establish that every SQLite handoff needs a WAL file. A coherent standalone export that contains the required committed state can satisfy a one-file requirement. SQLite's Online Backup API documentation provides a concrete basis for this distinction: database contents can be copied into another database, producing a destination snapshot. That is a database-content operation with defined semantics, beyond simply naming a source file.

The evidence needed for a proposed standalone artifact concerns its actual state. Does it include the commit the recipient requires? Is that state coherently represented in the offered file? The source database's use of WAL does not by itself answer either question about a separately produced artifact.

A package containing both a main file and a WAL also needs their relationship and coherent captured state established. Two filenames alone do not demonstrate that the supplied material represents the requested commit. File count cannot replace the state comparison.

References: [SB][SW]

Ask the software owner to identify the state being returned

A useful explanation from the appointed application or database provider connects three facts: the committed metadata state wanted, the form of the offered artifact and the basis for saying that artifact represents the state. If the offer supplies only the main file, its standalone completeness needs to be established. If it supplies WAL-mode material, the matching database state and applicable committed boundary need to be explained.

WAL-P2 makes the decision concrete. A request for the state including B2 is answered by A1/B2. The stipulated main-only A1/A2 offer does not meet it. The physically later C1/C2 selection does not meet it either. An independently established standalone A1/B2 artifact could meet it. These conclusions follow from the contents and boundary, without treating one packaging format as universally necessary.

The related PostgreSQL article addresses the different question of whether separate statements share a database view. The training-checkpoint article addresses which application state a storage copy contains. Neither property establishes the SQLite page composition examined here.

The source basis includes the SQLite 3 file-format page last updated December 25, 2025. The release history checked October 21, 2026 lists SQLite 3.54.1 dated October 16, 2026. This is dated documentation context, not an identification or recommendation of the recipient's installed version.

References: [SF][SV]

Keep any separate physical cabling project in scope

If the wider infrastructure project independently requires physical connections for storage or network equipment, Leviathan's Structured Cabling & Fiber Installation service and its project inquiry provide a route to discuss agreed fiber and copper installation, labels and connection records.

Share a nonconfidential equipment summary, approved endpoints and routes, material-supply responsibilities and the required physical handoff. SQLite state capture and software validation remain with the appointed application and database providers.

References: [L1]