关于 storage-format
这份指南介绍 Turso 的 SQLite 数据库文件布局和存储结构，面向检查或调试磁盘数据的开发者。内容涵盖文件头、页面与单元格类型、记录、B-tree、溢出页和空闲列表。
主要功能
- 01数据库文件头字段与编码
- 02页面和单元格布局
- 03表与索引的 B-tree 结构
- 04记录与序列类型格式
- 05溢出页和空闲列表
适用场景
- 01检查 SQLite 数据库文件
- 02调试页面与 B-tree 行为
- 03检查数据库完整性和页面计数
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/storage-format确认已加载。
详细介绍
存储格式指南
数据库文件结构
┌─────────────────────────────┐
│ Page 1: Header + Schema │ ← First 100 bytes = DB header
├─────────────────────────────┤
│ Page 2..N: B-tree pages │ ← Tables and indexes
│ Overflow pages │
│ Freelist pages │
└─────────────────────────────┘
页大小：2 的幂，范围为 512–65536 字节。默认值为 4096。
数据库头部（前 100 字节）
| 偏移量 | 大小 | 字段 |
|---|---|---|
| 0 | 16 | 魔数："SQLite format 3\0" |
| 16 | 2 | 页大小（大端序） |
| 18 | 1 | 写入格式版本（1=回滚，2=WAL） |
| 19 | 1 | 读取格式版本 |
| 24 | 4 | 更改计数器 |
| 28 | 4 | 数据库页数 |
| 32 | 4 | 第一个空闲列表主干页 |
| 36 | 4 | 空闲列表页总数 |
| 40 | 4 | 架构 cookie |
| 56 | 4 | 文本编码（1=UTF8，2=UTF16LE，3=UTF16BE） |
所有多字节整数均采用大端序。
页类型
| 标志 | 类型 | 用途 |
|---|---|---|
| 0x02 | 内部索引页 | 索引 B 树内部节点 |
| 0x05 | 内部表页 | 表 B 树内部节点 |
| 0x0a | 叶索引页 | 索引 B 树叶节点 |
| 0x0d | 叶表页 | 表 B 树叶节点 |
| - | 溢出页 | 超出单元容量的有效载荷 |
| - | 空闲列表页 | 未使用的页（主干页或叶页） |
B 树结构
两种 B 树类型：
- 表 B 树：使用 64 位 rowid 作为键，存储行数据
- 索引 B 树：使用任意键（索引列 + rowid）
Interior page: [ptr0] key1 [ptr1] key2 [ptr2] ...
│ │ │
▼ ▼ ▼
child child child
pages pages pages
Leaf page: key1:data key2:data key3:data ...
第 1 页始终是 sqlite_schema 表的根页。
单元格式
表叶单元
[payload_size: varint] [rowid: varint] [payload] [overflow_ptr: u32?]
表内部单元
[left_child_page: u32] [rowid: varint]
索引单元
格式类似，但键是任意值（列 + rowid），而不只是 rowid。
记录格式（有效载荷）
[header_size: varint] [type1: varint] [type2: varint] ... [data1] [data2] ...
序列类型：
| 类型 | 含义 |
|---|---|
| 0 | NULL |
| 1-4 | 1/2/3/4 字节有符号整数 |
| 5 | 6 字节有符号整数 |
| 6 | 8 字节有符号整数 |
| 7 | IEEE 754 浮点数 |
| 8 | 整数 0 |
| 9 | 整数 1 |
| ≥12 偶数 | BLOB，长度=(N-12)/2 |
| ≥13 奇数 | 文本，长度=(N-13)/2 |
溢出页
当有效载荷超过阈值时，超出部分会存储在溢出链中：
[next_page: u32] [data...]
最后一页的 next_page=0。
空闲列表
由主干页组成的链表，每个主干页都包含叶页编号：
Trunk: [next_trunk: u32] [leaf_count: u32] [leaf_pages: u32...]
Turso 实现
关键文件：
core/storage/sqlite3_ondisk.rs- 磁盘格式，PageType枚举core/storage/btree.rs- B 树操作（大型文件）core/storage/pager.rs- 页管理core/storage/buffer_pool.rs- 页缓存
存储调试
# 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;"
参考资料
评论
支持 Markdown