Storage Format
- 946 installs
- 23.5k repo stars
- Updated July 28, 2026
- tursodatabase/turso
storage-format is a skill that explains how Turso and SQLite physically store data on disk—including B-trees, pages, cells, and freelists—for developers who debug performance, design schemas, or build custom database ext
About
storage-format is a Turso database skill documenting the SQLite 3 on-disk file layout used by tursodb. It maps the 100-byte database header, B-tree page structure, cell and overflow pages, and freelist mechanics, with default page size 4096 bytes and supported sizes from 512 to 65536 bytes as powers of two. Developers use storage-format when diagnosing slow queries, reasoning about index layout, estimating storage overhead, or extending Turso with format-aware tooling. The skill is reference depth for physical storage, not a migration or ORM tutorial.
- Explains the complete SQLite database file structure including header, B-tree pages, overflow, and freelist
- Details the first 100-byte database header with all field offsets, sizes, and meanings
- Covers all five page types (interior/leaf index/table B-trees, overflow, freelist) and their binary flags
- Describes B-tree variants: 64-bit rowid Table B-trees versus Index B-trees
- Documents page size rules, big-endian encoding, and power-of-two constraints from 512 to 65536 bytes
Storage Format by the numbers
- 946 all-time installs (skills.sh)
- +47 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #90 of 923 Databases skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/tursodatabase/turso --skill storage-formatAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 946 |
|---|---|
| repo stars | ★ 23.5k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 28, 2026 |
| Repository | tursodatabase/turso ↗ |
How does SQLite store data on disk?
Understand exactly how Turso and SQLite physically store data on disk when debugging performance, designing schemas, or building custom extensions.
Who is it for?
Backend developers debugging Turso or SQLite performance, schema design, or building format-aware database tooling.
Skip if: Developers who only need SQL query help or ORM setup without caring about physical page or B-tree internals.
When should I use this skill?
User asks about SQLite file format, B-trees, page size, Turso storage internals, or on-disk performance debugging.
What you get
Accurate mental model and reference for SQLite page layout, B-tree structure, header fields, and freelist behavior in Turso files.
- storage layout reference
- debugging guidance
By the numbers
- SQLite database header is 100 bytes on page 1
- Supported page sizes range 512–65536 bytes with 4096-byte default
Files
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 |
|---|---|---|
| 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 ...Page 1 always root of sqlite_schema table.
Cell Format
Table Leaf Cell
[payload_size: varint] [rowid: varint] [payload] [overflow_ptr: u32?]Table Interior Cell
[left_child_page: u32] [rowid: varint]Index Cells
Similar but key is arbitrary (columns + rowid), not just rowid.
Record Format (Payload)
[header_size: varint] [type1: varint] [type2: varint] ... [data1] [data2] ...Serial types:
| 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 |
Overflow Pages
When payload exceeds threshold, excess stored in overflow chain:
[next_page: u32] [data...]Last page has next_page=0.
Freelist
Linked list of trunk pages, each containing leaf page numbers:
Trunk: [next_trunk: u32] [leaf_count: u32] [leaf_pages: u32...]Turso Implementation
Key files:
core/storage/sqlite3_ondisk.rs- On-disk format,PageTypeenumcore/storage/btree.rs- B-tree operations (large file)core/storage/pager.rs- Page managementcore/storage/buffer_pool.rs- Page caching
Debugging Storage
# Integrity check
cargo run --bin tursodb test.db "PRAGMA integrity_check;"
# Page count
cargo run --bin tursodb test.db "PRAGMA page_count;"
# Freelist info
cargo run --bin tursodb test.db "PRAGMA freelist_count;"References
Related skills
Azure KustoRun fast KQL queries against Azure Data Explorer for log analytics, telemetry, and time-series data.467k1.3k
Lark BaseLet their coding agents read from, write to, and query structured data stored in Lark Base (Feishu) spreadsheets and databases.452k
Lark SheetsCreate, read, update, and export spreadsheets inside Lark (Feishu) directly from their AI coding agent.378k15.7k
Supabase Postgres Best PracticesAutomatically apply Supabase Postgres performance rules during query writing, schema design, and database optimization.300k2.4k
Firebase Data ConnectGenerate complete, production-ready Firebase Data Connect GraphQL schemas and queries for complex relational data models.107k386Firebase FirestoreAdd Cloud Firestore read/write capabilities to an Android Kotlin app using the official Firebase SDK.72.1k386How it compares
Use storage-format for on-disk internals; use SQL or ORM skills for application-level queries without physical layout needs.
FAQ
What page sizes does storage-format document for SQLite?
storage-format states SQLite page sizes are powers of two from 512 to 65536 bytes, with 4096 bytes as the common default. Page 1 holds the 100-byte database header plus schema root B-tree data.
Is storage-format specific to Turso?
storage-format covers the SQLite file format used by tursodb, including B-trees, cells, overflow pages, and freelists. The same on-disk layout applies when debugging Turso-hosted SQLite databases.
Is Storage Format safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.