storage-format

SKILL.md

SQLite file format internals: pages, B-trees, cells, overflow chains, and freelist structure used in Turso.

Database organized as fixed-size pages (default 4096 bytes) containing B-tree nodes, overflow pages, and freelist pages; header stores magic bytes, page size, encoding, and freelist pointers

Two B-tree types: table B-trees use 64-bit rowid keys and store row data; index B-trees use arbitrary keys (index columns + rowid)

Cells encode payloads with varint-prefixed rowid/keys; overflow pages chain together when payload exceeds threshold, with next-page pointers forming linked lists

Freelist implemented as trunk pages containing leaf page numbers, enabling efficient tracking of unused space

Includes debugging commands (integrity check, page count, freelist info) and references Turso implementation files in core/storage/

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 size: power of 2, 512-65536 bytes. Default 4096.

Database Header (First 100 Bytes)