storage-format

Installation
Summary

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/
SKILL.md

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)

Offset Size Field
Related skills
Installs
607
GitHub Stars
18.7K
First Seen
Jan 28, 2026