第1章：SQLite核心原理与本地文件布局

1.1 数据库文件结构与页组织

SQLite 将整个数据库存储为单一磁盘文件，内部以固定大小的页（Page）为基本单位进行读写。文件布局遵循严格的分区结构，包含文件头、页内容以及可选的回滚日志或 WAL 文件。

下图展示了标准 SQLite 数据库文件的物理页布局

1.2 页缓存机制（Page Cache）

SQLite 在内存中维护一个页缓存（Page Cache），用于缓冲最近访问的磁盘页，减少同步 I/O 次数。缓存大小通过 PRAGMA cache_size 控制，默认值为 2000 页（约 8 MiB，当页大小为 4096 时）。

配置示例

-- 设置缓存大小为 10000 页
PRAGMA cache_size = 10000;

-- 查看当前缓存页数
PRAGMA cache_size;

-- 设置页大小 8192（必须在创建数据库前设置）
PRAGMA page_size = 8192;

1.3 WAL 与日志模式选择

SQLite 支持两种事务日志模式：回滚日志（Rollback Journal） 和 预写日志（Write-Ahead Log, WAL）。模式选择直接影响并发性、写入性能与崩溃恢复。

核心差异对比

切换命令与诊断

-- 设置 WAL 模式
PRAGMA journal_mode = WAL;

-- 设置回滚日志模式（DELETE 模式为最兼容）
PRAGMA journal_mode = DELETE;

-- 查看当前日志模式
PRAGMA journal_mode;

-- 检查 WAL 检查点状态
PRAGMA wal_checkpoint(PASSIVE);

1.4 实现流程示例（C 代码 API）

以下代码演示了如何打开数据库、设置页大小、WAL 模式并执行一条 DDL 语句。

#include <sqlite3.h>
#include <stdio.h>

int main() {
    sqlite3 *db;
    char *err_msg = 0;

    // 打开数据库（如果不存在则创建）
    int rc = sqlite3_open("example.db", &db);
    if (rc != SQLITE_OK) {
        fprintf(stderr, "无法打开数据库: %s\n", sqlite3_errmsg(db));
        sqlite3_close(db);
        return 1;
    }

    // 设置页大小为 8192（必须在创建表之前设置）
    sqlite3_exec(db, "PRAGMA page_size = 8192;", 0, 0, &err_msg);
    // 启用 WAL 模式
    sqlite3_exec(db, "PRAGMA journal_mode = WAL;", 0, 0, &err_msg);
    // 创建表
    sqlite3_exec(db, "CREATE TABLE IF NOT EXISTS users(id INT, name TEXT);", 0, 0, &err_msg);

    if (err_msg) {
        fprintf(stderr, "SQL 错误: %s\n", err_msg);
        sqlite3_free(err_msg);
    }

    sqlite3_close(db);
    return 0;
}

1.5 调试与验证技巧

1. 使用 sqlite3 命令行工具检查文件结构：
   

   sqlite3 example.db
   .header on
   PRAGMA page_size;
   PRAGMA cache_size;
   PRAGMA journal_mode;

2. 使用 file 命令查看文件头魔数：
   

   xxd -l 16 example.db | head -n 1
   # 输出示例: 00000000: 5351 4c69 7465 2066 6f72 6d61 7420 3300  SQLite format 3.

3. 使用 PRAGMA database_list 确认当前数据库文件路径。
4. 写入大规模数据后，查看 WAL 文件大小：ls -lh example.db example.db-wal。

1.6 常见错误与稳定性优化