---
url: /docs/database/migrations.md
---
# 数据库迁移

## 本地工作流

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

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

## 迁移与结构推送

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

## 选择目标环境

```sh
bun db:migrate:staging
bun db:migrate:production
```

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

## 发布兼容性

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

## 失败排查

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