struct {
  u32 magic;           /* 0: 0x377f0682 (小端) 或 0x377f0683 (大端) */
  u32 version;         /* 4: 文件格式版本，当前 3007000 */
  u32 pageSize;        /* 8: 数据库页面大小，如 1024、4096 等 */
  u32 ckptSeq;         /* 12: Checkpoint 序列号 */
  u32 salt1;           /* 16: Salt-1，随机整数，每次 checkpoint 递增 */
  u32 salt2;           /* 20: Salt-2，随机整数，每次 checkpoint 随机化 */
  u32 checksum1;       /* 24: 头部校验和 - 第一部分 */
  u32 checksum2;       /* 28: 头部校验和 - 第二部分 */
} WalIndexHdr;

struct {
  u32 pageNum;         /* 0: 页面号 */
  u32 dbSize;          /* 4: Commit Marker 时显示数据库大小 (页面数) */
  u32 salt1;           /* 8: 从 WAL Header 拷贝 */
  u32 salt2;           /* 12: 从 WAL Header 拷贝 */
  u32 checksum1;       /* 16: 帧校验和 - 第一部分 */
  u32 checksum2;       /* 20: 帧校验和 - 第二部分 */
  u8 pageData[];       /* 24: 实际页面数据，大小为 pageSize */
} WalFrame;

struct Wal {
  sqlite3_vfs *pVfs;           /* VFS 模块 */
  sqlite3_file *pWalFd;        /* WAL 文件句柄 */
  sqlite3_file *pDbFd;         /* 数据库文件句柄 */
  int readLock;                /* Reader 锁 ID */
  int writeLock;               /* Writer 锁标志 */
  int ckptLock;                /* Checkpoint 锁标志 */
  int exclusiveMode;           /* 锁定模式 */
  WalIndexHdr hdr;             /* 本地 WAL Header 缓存 */
  u32 aWiData[WAL_NREADER];    /* 共享内存数据 */
  int syncHeader;              /* 是否同步 header */
  int padToSectorBoundary;     /* 是否对齐扇区边界 */
  i64 mxWalSize;               /* WAL 最大大小限制 */
  u32 iCallback;               /* 事务回调帧数 */
  u32 iReCksum;                /* 重计算的位置 */
};

struct WalCkptInfo {
  u32 nBackfill;                  /* 已刷入数据库的帧数 */
  u32 aReadMark[WAL_NREADER];     /* 读器标记 */
  u8 aLock[SQLITE_SHM_NLOCK];     /* 锁字节 */
  u32 nBackfillAttempted;           /* 尝试刷入的帧数 */
  u32 notUsed0;                     /* 预留字段 */
};

int sqlite3WalBeginWriteTransaction(Wal *pWal) {
  /* 单 writer 锁，其他 writer 等待或返回 BUSY */
  rc = walLockExclusive(pWal, WAL_WRITE_LOCK, 1);
  
  /* 防止 WAL Header 被其他进程修改 */
  if (memcmp(&pWal->hdr, (void *)walIndexHdr(pWal), sizeof(WalIndexHdr)) != 0) {
    return SQLITE_BUSY_SNAPSHOT;
  }
  return SQLITE_OK;
}

PRAGMA wal_checkpoint;           -- PASSIVE 模式
PRAGMA wal_checkpoint(TRUNCATE); -- RESTART 模式
PRAGMA wal_checkpoint(FULL);     -- FULL 模式

int sqlite3WalCheckpoint(Wal *pWal, int eMode) {
  // 1. 获取 checkpoint 锁
  walLockExclusive(pWal, WAL_CKPT_LOCK, 1);
  
  // 2. FULL/RESTART/TRUNCATE 模式获取 writer 锁
  walBusyLock(pWal, ..., WAL_WRITE_LOCK, 1);
  
  // 3. 读取 wal-index 头部信息
  walIndexReadHdr(pWal, &isChanged);
  
  // 4. 将 WAL 帧刷入数据库文件
  walCheckpoint(pWal, db, eMode2, ...);
  
  // 5. 释放所有锁
  walUnlockExclusive(pWal, WAL_CKPT_LOCK, 1);
}

/* 第一部分：Header (136 字节) */
- WalIndexHdr (x2)  : 重复两个，增强可靠性
- WalCkptInfo       : Checkpoint 信息

/* 第二部分：Index Blocks (4096 条目/块) */
- Page Mapping: 帧号到页面号的映射
- Hash Table: 快速定位帧的哈希表

int sqlite3WalFindFrame(Wal *pWal, Pgno pgNo, int *piFrame) {
  // 1. 哈希表查找
  hashLoc = walHashLocation(pgNo);
  
  // 2. 从 wal-index 中定位帧
  for (每个 index block) {
    if (pgNo == pageMapping[i]) {
      *piFrame = i;
      return SQLITE_OK;
    }
  }
  return SQLITE_NOTFOUND;
}

WAL_INDEX_LOCK_OFFSET = 120 字节

120: WAL_WRITE_LOCK      -- 写入锁 (单 writer)
121: WAL_CKPT_LOCK        -- Checkpoint 锁
122: WAL_RECOVER_LOCK     -- 崩溃恢复锁
123-127: WAL_READ_LOCK[0-4] -- Reader 锁 (最多 5 个并发 reader)

1. 获取 WAL_READ_LOCK(k) (共享锁，非阻塞尝试)
2. 记录 mxFrame 到 aReadMark[k]
3. 读取数据 (忽略 aReadMark 之后的新帧)
4. 释放 WAL_READ_LOCK(k)

1. 获取 WAL_WRITE_LOCK (独占锁)
2. 等待所有 active reader 完成 (阻塞或 BUSY)
3. 写入帧到 WAL (追加写)
4. Commit: FSync + 释放 WAL_WRITE_LOCK

1. 获取 WAL_CKPT_LOCK (独占锁)
2. FULL/RESTART/TRUNCATE: 额外获取 WAL_WRITE_LOCK
3. 等待所有 active reader 释放
4. 刷 WAL 帧到数据库
5. 更新 salt1/salt2, 释放所有锁

#define WAL_NREADER  5  /* 最大 5 个 reader 锁槽 */

/* 槽分配算法 */
1. 新 reader 尝试：找到 aReadMark 中的最大空闲槽
2. 若所有槽被占用：等待最老 reader 完成
3. aReadMark[0]: 特殊槽，值为 0，表示不使用 WAL，直接读数据库
4. aReadMark[1-4]: 普通 reader 槽，存储 mxFrame 快照

void walChecksum(u8 *p, int nB, int bigEnd, u32 aCksum[2]) {
  u32 s0 = 0, s1 = 0;
  u32 *pU32 = (u32*)p;
  int n = nB >> 2;  /* 32 位整数数量 */
  
  for (int i = 0; i < n; i++) {
    u32 x = bigEnd ? sqlite3_getint32(pU32) : sqlite3_getlendo32(pU32);
    s0 += x + s1;
    s1 += s0;
  }
  
  aCksum[0] = s0;
  aCksum[1] = s1;
}

// 帧有效验证
if (frame.salt1 != header.salt1 || frame.salt2 != header.salt2) {
  return INVALID_FRAME;  /* 盐值不匹配，废弃 */
}

if (calculatedChecksum != frame.checksum) {
  return CORRUPT_FRAME;  /* 校验和失败，数据损坏 */
}

return VALID_FRAME;

// Reader 获取快照
WalIndexHdr hdr;
memcpy(&hdr, walIndexHdr(pWal), sizeof(WalIndexHdr));
mxFrame = hdr.mxFrame;  /* 记录当前最大帧 */

// Reader 读取页面时
int frameNum;
if (walFindFrame(pWal, pgNo, &frameNum, mxFrame)) {
  /* 从 WAL 读取帧 (不超过 mxFrame) */
} else {
  /* 从数据库文件读取 */
}

// 保证一致性
/* 只要 reader 坚持使用原始 mxFrame，就不会看到新提交的数据 */

salt1++   /* 递增，防止旧帧被复用 */
salt2 = random()  /* 随机化，防止旧帧被误认 */

if (frame.salt1 != hdr.salt1) return INVALID;
if (frame.salt2 != hdr.salt2) return INVALID;

/* WAL 生命周期 */
1. 写入帧到 WAL (增长)
2. Checkpoint 刷入数据库 (复用 WAL 空间)
3. 重置 mxFrame = 0，从新位置继续写入

/* 触发条件 */
- 自动：wal_autocheckpoint 帧数 (默认 1000)
- 手动：PRAGMA wal_checkpoint
- 清理：最后一个读者断开

/* WalIndexHashLoc (哈希位置) */
struct WalHashLoc {
  u32 iBucket;            /* 哈希桶 */
  u32 iPage;              /* 页面号 */
  u32 iFrame;             /* 帧位置 */
};

/* 查找算法 */
int sqlite3WalFindFrame(Wal *pWal, Pgno pgNo, int *piFrame) {
  /* 1. 计算哈希桶 */
  hash = walHash(pgNo, iChange);
  
  /* 2. 查找 frame 位置 */
  for (i = 0; i < HASH_NPAGE; i++) {
    if (pWal->aPageMapping[hash + i] == pgNo) {
      *piFrame = hash + i;
      return SQLITE_OK;
    }
  }
  return SQLITE_NOTFOUND;
}

-- 1. 调整自动 checkpoint 阈值
PRAGMA wal_autocheckpoint = 10000;  -- 默认 1000，可根据场景调整

-- 2. 设置 WAL 文件大小限制 (MB)
PRAGMA wal_size_limit = 1024;  -- 最大 1GB

-- 3. 调整 checkpoint 模式
PRAGMA wal_checkpoint(TRUNCATE);  -- 最积极，立即截断

-- 1. 查看当前 WAL 模式
PRAGMA journal_mode;           -- 返回 "wal"

-- 2. 查看 WAL 文件状态
PRAGMA wal_checkpoint;         -- PASSIVE 模式，输出 checkpoint 结果

-- 3. 强制 Checkpoint 并截断 WAL
PRAGMA wal_checkpoint(TRUNCATE);

-- 4. 查看 WAL 配置
PRAGMA wal_autocheckpoint;     -- 显示当前 autocheckpoint 阈值
PRAGMA wal_size_limit;         -- 显示当前 WAL 大小限制

-- 5. 生成 WAL 文件信息
PRAGMA integrity_check;        -- 检查数据库完整性
PRAGMA wal_checkpoint;         -- 检查 WAL 状态

# 1. 编译 SQLite 源码
./configure --enable-wal
make -j$(nproc)

# 2. 运行测试
make test

# 3. 查看 WAL 源码结构
find src/wal*.c -type f | head -10

# 4. 生成 WAL 状态报告
./sqlite3 test.db "PRAGMA journal_mode=wal; PRAGMA wal_checkpoint; PRAGMA integrity_check;"

# 5. 分析 WAL 文件二进制格式
hexdump -C test.db-wal | head -50

# 6. 查看共享内存结构
ls -lh test.db-wal test.db-shm