SQLite UUIDv7 零停机迁移：索引重建成本量化与双写回滚策略

将现有 SQLite 数据库的整数主键迁移至 UUIDv7 是一项涉及存储格式、索引结构与应用程序三方的复杂工程。与诊断视角的 B-tree 重平衡分析不同，本文聚焦工程实施层面：如何在不停机的前提下完成迁移，如何量化索引重建成本，以及如何设计可回滚的双写策略。

UUIDv7 的局部性优势与存储选型

UUIDv7 将 48 位 Unix 时间戳置于高位，剩余位填充随机数。这种结构使新生成的 UUID 在字典序上近似递增，与 B-tree 的页填充策略高度契合。相比完全随机的 UUIDv4，UUIDv7 可将随机页写入转换为顺序追加，显著降低页分裂频率。

存储格式选择直接影响索引大小与查询性能。以 BLOB (16) 存储 UUIDv7 最为紧凑，单条记录索引项仅占用 16 字节；若使用 TEXT 存储带连字符的 36 字符格式，索引膨胀超过 100%。在时序数据场景下，BLOB 存储的 UUIDv7 配合毫秒级 INTEGER 时间戳，已被验证可支撑高吞吐写入。

Expand-Migrate-Contract 三阶段迁移框架

SQLite 的零停机迁移依赖 Expand-Migrate-Contract（扩展 - 迁移 - 收缩）模式，通过触发器在双模式并存期保持数据一致性。

扩展阶段（Expand）：为现有表添加 UUID 列（可为 NULL），创建新旧字段间的双向同步触发器。INSERT 触发器在写入旧字段时自动填充新字段，UPDATE 触发器保持两者同步。此阶段应用程序仍使用旧主键，但新写入已同步至 UUID 列。

迁移阶段（Migrate）：分批次回填历史数据的 UUID。每批次控制在 1000-5000 行，通过 WHERE id BETWEEN ? AND ? 限定范围，避免长时间事务锁定。回填期间监控 PRAGMA wal_checkpoint 状态，确保 WAL 文件不会无限增长。

收缩阶段（Contract）：当所有数据完成回填且应用程序已切换至 UUID 查询路径后，移除旧字段与触发器。SQLite 不支持 ALTER TABLE DROP COLUMN，需通过创建新表、数据迁移、重命名表的方式完成收缩。此步骤需安排在低峰期执行，虽非瞬时完成，但可通过事务包装保证原子性。

索引重建成本量化

索引重建成本与表大小、B-tree 碎片化程度及存储介质 I/O 能力正相关。以 5000 万行数据为例，UUIDv7 BLOB 主键索引重建的 I/O 开销约为原始数据量的 1.2-1.5 倍（含索引页与溢出页）。

双写阶段的性能损耗主要来自触发器执行。实测表明，单表双触发器（INSERT + UPDATE）会使写入延迟增加 15-25%。若业务对延迟敏感，可将触发器逻辑下沉至应用层，通过事务内双写替代触发器，延迟可降低至 5-8%。

双写一致性保障与回滚策略

双写期间的一致性保障采用 "新字段优先写入，旧字段兜底" 策略。应用程序写入时同时生成 UUIDv7 与旧整数 ID，优先使用 UUID 进行外键关联。若 UUID 查询失败（回填未完成），则回退至旧 ID 查询。

回滚机制设计为三级：

• L1 应用层回滚：切换配置项 USE_UUID_PRIMARY=false，应用程序立即回退至旧主键路径，无需数据库变更。
• L2 数据层回滚：若发现 UUID 生成逻辑缺陷，可暂停回填任务，保持双写模式运行，修复后重新启动。
• L3 全量回滚：收缩阶段前保留完整备份，必要时可重建旧 schema。此操作需停机窗口，应在业务低峰期预留 2-4 小时。

可落地参数清单

实施 checklist

• 验证 UUIDv7 生成库的时间单调性（防止时钟回拨导致重复）
• 测试触发器在并发写入下的性能基线
• 预演收缩阶段的表重建耗时（使用生产数据副本）
• 配置监控：双写延迟、WAL 大小、索引页碎片化率
• 准备 L1/L2 回滚开关与运维 runbook

UUIDv7 迁移不仅是主键格式的变更，更是写入模式从随机到顺序的结构性调整。通过 Expand-Migrate-Contract 框架与量化成本评估，可在保障业务连续性的前提下完成这一迁移。

参考来源

• GitHub Gist: tl;dr zero-downtime database migrations in SQLite using triggers
• dev.to: Building High-Performance Time Series on SQLite with Go: UUIDv7, sqlc, and libSQL

systems