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