数据库迁移

本地工作流

# 修改模型后生成 SQL
bun db:generate
# 审查新增 SQL 和迁移元数据
bun db:check
# 仅在确认目标为隔离开发库后执行
bun db:migrate

生成结果位于 db/migrations/。SQL、快照和迁移顺序元数据一起提交，不修改已经在线上应用的旧迁移。

迁移与结构推送

db:migrate 按已记录迁移执行，适合可追踪的发布；db:push 根据当前模型直接修改数据库，只用于可丢弃本地库。项目有结构推送保护，不应绕过后向生产执行。

选择目标环境

bun db:migrate:staging
bun db:migrate:production

以上是有写入影响的命令示例，执行前确认对应 .env.staging.local 或 .env.production.local 的连接目标、备份和 SQL。文件缺失或没有显式 DATABASE_URL 时命令应失败，不回退到其他库。

发布兼容性

数据库迁移和三个 Worker 部署不是原子操作。先增加兼容列或表，使旧代码仍能运行；部署新代码并验证后，再在后续版本删除旧结构。不要在一次发布中先删列再更新依赖该列的代码。

失败排查

保留失败 SQL、迁移记录和请求标识，确认是哪一步失败。不要盲目再次推送结构或删除迁移记录；修正未应用的迁移或新增补救迁移，并在隔离数据库复现。恢复数据库与回滚代码是不同操作。