D1 数据库迁移实战:先扩展、再迁移、最后收缩

应用与数据库不是总能同时更新:旧实例可能还在运行,新版本也可能需要回滚。直接删除或重命名字段,容易让旧版本在部署窗口内报错。更稳妥的是 expand-contract:先增加兼容结构,迁移数据和应用,确认完成后再移除旧结构。

一个字段重命名例子

假设 name 要迁移到 display_name。第一阶段添加可兼容的字段,新代码读取新字段并在缺失时回退旧字段;写入路径在过渡期同时维护两者。第二阶段分批回填历史数据,记录游标、失败条数与校验结果。第三阶段确认所有服务已切换、回滚窗口结束,再移除旧字段或旧写入逻辑。

必须评估并发写入:回填期间用户可能修改同一行,不能让旧数据覆盖新值。使用条件更新、版本字段或其他并发控制,并在测试环境演练中断后重启。大规模迁移分批执行,观察耗时和读写成本;不要把整表重写放进每次请求的热路径。

发布前后

迁移脚本纳入版本控制,记录已执行版本;备份并验证恢复流程。区分可回滚的 schema 变更和不可逆的数据转换,明确何时只能向前修复。上线后检查错误率、行数、空值和关键查询计划;异常时暂停下一阶段。

具体 SQL 能力、迁移命令和限制应以当前 D1 文档为准;即使数据库提供时间点恢复,也应定期验证备份可用性。

参考:Cloudflare D1 migrations;D1 备份与 Time Travel。