storage-format
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)
| Offset | Size | Field |
|---|
More from tursodatabase/turso
code-quality
General Correctness rules, Rust patterns, comments, avoiding over-engineering. When writing code always take these into account
1.0Kindex-knowledge
Generate hierarchical AGENTS.md knowledge base for a codebase. Creates root + complexity-scored subdirectory documentation.
660debugging
How to debug tursodb using Bytecode comparison, logging, ThreadSanitizer, deterministic simulation, and corruption analysis tools
634async-io-model
Explanations of common asynchronous patterns used in tursodb. Involves IOResult, state machines, re-entrancy pitfalls, CompletionGroup. Always use these patterns in `core` when doing anything IO
607testing
How to write tests, when to use each type of test, and how to run them. Contains information about conversion of `.test` to `.sqltest`, and how to write `.sqltest` and rust tests
601pr-workflow
General guidelines for Commits, formatting, CI, dependencies, security
599