Storage Format

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

作者 tursodatabaseff97ec42cdef无许可证24K 个星标收录于 2026年10月9日更新于 2026年10月8日仓库今天更新

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

仅含说明Software Development

AI 生成的概览

介绍 Turso 所用 SQLite 磁盘文件格式的参考指南，涵盖 B 树、页、单元格、溢出页与空闲列表。

功能: 该技能是一份参考文档，说明 SQLite 数据库文件格式：100 字节数据库头、页类型、表与索引 B 树结构、单元格与记录编码、溢出页链以及空闲列表。它还将这些结构对应到 Turso 的实现文件，并列出用于检查数据库的 PRAGMA 命令。它产出的是解释说明，而不是文件或代码。
适用场景: 当你需要理解或解释 SQLite 或 Turso 如何在磁盘上存储数据时使用，例如读取原始页、调试存储层行为，或解读头部字段与页类型。
运行要求: 不需要脚本或工具，仅为说明与参考资料。调试示例假定已安装 Rust 工具链和 tursodb 可执行文件，参考资料链接指向外部文档。

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

来源与署名

来源：tursodatabase/turso位于.claude/skills/storage-format提交ff97ec4

许可证：无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

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

来源与署名

更多来自 tursodatabase/turso 的技能

Transaction Correctness

Testing

Debugging

Index Knowledge

Mvcc

Differential Fuzzer

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Web Design Guidelines

Vercel React Native Skills

Vercel React Best Practices