Storage Format

tursodatabase/turso/.claude/skills/storage-format

by tursodatabaseff97ec42cdefNo license24K starsListed Oct 9, 2026Updated Oct 8, 2026Repository updated today

SQLite file format, B-trees, pages, cells, overflow, freelist that is used in tursodb

Instructions onlySoftware Development

AI-generated overview

Reference guide to the SQLite on-disk file format, B-trees, pages, cells, overflow and freelist, as used in Turso.

What it does: This skill is a reference document describing the SQLite database file format: the 100-byte database header, page types, table and index B-tree layouts, cell and record encodings, overflow page chains and the freelist. It also maps these structures to Turso implementation files and lists PRAGMA commands for inspecting a database. It produces explanations rather than files or code.
When to use it: Use it when you need to understand or explain how SQLite or Turso stores data on disk, for example when reading raw pages, debugging storage-level behavior, or interpreting header fields and page types.
Requirements: No scripts or tooling are required; it is instructions and reference material only. The debugging examples assume a Rust toolchain and the tursodb binary, and the reference links point to external documentation.

Storage Format Guide

Database File Structure

┌─────────────────────────────┐│ Page 1: Header + Schema     │  ← First 100 bytes = DB header├─────────────────────────────┤│ Page 2..N: B-tree pages     │  ← Tables and indexes│            Overflow pages   ││            Freelist pages   │└─────────────────────────────┘

┌─────────────────────────────┐│ Page 1: Header + Schema     │  ← First 100 bytes = DB header├─────────────────────────────┤│ Page 2..N: B-tree pages     │  ← Tables and indexes│            Overflow pages   ││            Freelist pages   │└─────────────────────────────┘

Page size: power of 2, 512-65536 bytes. Default 4096.

Database Header (First 100 Bytes)

Offset	Size	Field
0	16	Magic: `"SQLite format 3\0"`
16	2	Page size (big-endian)
18	1	Write format version (1=rollback, 2=WAL)
19	1	Read format version
24	4	Change counter
28	4	Database size in pages
32	4	First freelist trunk page
36	4	Total freelist pages
40	4	Schema cookie
56	4	Text encoding (1=UTF8, 2=UTF16LE, 3=UTF16BE)

All multi-byte integers: big-endian.

Page Types

Flag	Type	Purpose
0x02	Interior index	Index B-tree internal node
0x05	Interior table	Table B-tree internal node
0x0a	Leaf index	Index B-tree leaf
0x0d	Leaf table	Table B-tree leaf
-	Overflow	Payload exceeding cell capacity
-	Freelist	Unused pages (trunk or leaf)

B-tree Structure

Two B-tree types:

Table B-tree: 64-bit rowid keys, stores row data
Index B-tree: Arbitrary keys (index columns + rowid)

Interior page:  [ptr0] key1 [ptr1] key2 [ptr2] ...                   │         │         │                   ▼         ▼         ▼               child     child     child               pages     pages     pages
Leaf page:     key1:data  key2:data  key3:data ...

Interior page:  [ptr0] key1 [ptr1] key2 [ptr2] ...                   │         │         │                   ▼         ▼         ▼               child     child     child               pages     pages     pages
Leaf page:     key1:data  key2:data  key3:data ...

Page 1 always root of sqlite_schema table.

Cell Format

Table Leaf Cell

Table Interior Cell

Index Cells

Similar but key is arbitrary (columns + rowid), not just rowid.

Record Format (Payload)

Serial types:

Overflow Pages

When payload exceeds threshold, excess stored in overflow chain:

Last page has next_page=0.

Freelist

Linked list of trunk pages, each containing leaf page numbers:

Turso Implementation

Key files:

core/storage/sqlite3_ondisk.rs - On-disk format, PageType enum
core/storage/btree.rs - B-tree operations (large file)
core/storage/pager.rs - Page management
core/storage/buffer_pool.rs - Page caching

Debugging Storage

bash

# Integrity checkcargo run --bin tursodb test.db "PRAGMA integrity_check;"
# Page countcargo run --bin tursodb test.db "PRAGMA page_count;"
# Freelist infocargo run --bin tursodb test.db "PRAGMA freelist_count;"

# Integrity checkcargo run --bin tursodb test.db "PRAGMA integrity_check;"
# Page countcargo run --bin tursodb test.db "PRAGMA page_count;"
# Freelist infocargo run --bin tursodb test.db "PRAGMA freelist_count;"

References

Source and attribution

Source:tursodatabase/tursoin.claude/skills/storage-formatat commitff97ec4

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

Type	Meaning
0	NULL
1-4	1/2/3/4 byte signed int
5	6 byte signed int
6	8 byte signed int
7	IEEE 754 float
8	Integer 0
9	Integer 1
≥12 even	BLOB, length=(N-12)/2
≥13 odd	Text, length=(N-13)/2

Storage Format

Storage Format Guide

Database File Structure

Database Header (First 100 Bytes)

Page Types

B-tree Structure

Cell Format

Table Leaf Cell

Table Interior Cell

Index Cells

Record Format (Payload)

Overflow Pages

Freelist

Turso Implementation

Debugging Storage

References

Source and attribution

More from tursodatabase/turso

Transaction Correctness

Testing

Debugging

Index Knowledge

Mvcc

Differential Fuzzer

More in Software Development

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices