An SQLite 2 file is nothing but pages, one after another, all of the same size. No page says what kind it is: a reader learns that from what points to it, starting from the header on page 1 and the schema table on page 2.
Page size and numbering
Pages are 1,024 bytes. The size is a constant fixed when SQLite is compiled
(SQLITE_PAGE_SIZE, 1,024 in standard builds) and is not written in the
file. The 2.8.17 source warns that “changing the page size results in a completely
imcompatible file format”, so a file from a build with another page size is a
different format; none is described here.
Pages are numbered from 1. Page N starts at byte (N − 1) × 1,024, so a file of L bytes holds L ÷ 1,024 pages, and a length that is not a multiple of 1,024 means the file is cut short or damaged. Page number 0 means “no page” wherever a page number is stored. The largest page number is 1,073,741,823.
A build may also keep SQLITE_PAGE_RESERVE bytes unused at the end of
every page; in standard builds that is 0, and this reference assumes it.
Kinds of page
| Page | Kind | Found from |
|---|---|---|
| 1 | Database header | always page 1 |
| 2 | Root of sqlite_master | always page 2 |
| any other | B-tree page, interior or leaf | a root page in sqlite_master, or a child pointer in a b-tree page or cell |
| any other | Overflow page | a cell whose payload spills, or the previous overflow page |
| any other | Freelist trunk page | the header’s first free page, or the previous trunk |
| any other | Free page | a trunk page’s list |
Leaf and interior b-tree pages share a layout. A page is interior when its right child or any cell’s left child is not 0.
Finding every page
To learn the kind of every page, a reader can walk the file in one pass:
- Mark page 1 as the header.
- Walk the
sqlite_masterb-tree from page 2, following each cell’s overflow chain, and read every row: each table and index gives its root page. - Walk each of those b-trees in the same way.
- Follow the freelist from the header’s first free page: each trunk page, then the free pages it lists.
A page reached twice is a sign of damage. The explorer walks the file this way and reports such pages.
Unused pages
A page that no b-tree, overflow chain or freelist reaches is unused. “Unused” is the explorer’s own term: in a healthy file there are none, since SQLite puts every page it frees on the freelist. Unused pages point to a damaged file, or one whose writer stopped part way.