| name | db-migrate |
| description | Alembic 迁移生成与执行 |
Database Migrate
规则摘要:.cursor/rules/db-migrate.mdc。命令一律用仓库根 .venv(见 .cursor/rules/agent-env.mdc)。
当前 head:s2f9c1a08e47(以 alembic heads / _alembic_head() 为准)。
1. 空库 / 升级
cd backend
../.venv/bin/alembic upgrade head
开发空库 API 启动时 init_db() 会:PostgreSQL 先 alembic upgrade head,再 create_all + 补缺失列/索引/注释并 stamp head。已有库也依赖启动时 upgrade,但生产仍应显式 upgrade head。
DATABASE_URL 只来自 backend/.env(alembic/env.py 注入),勿写进 alembic.ini。
2. 模型变更 → 新 revision
cd backend
../.venv/bin/alembic revision --autogenerate -m "add xxx"
提交前清单(缺一项即不完整)
3. 链结构(勿改 baseline)
c18a0e9b4d21 (baseline)
→ b7e4c2a19f08
→ e8c3a1b047d2 ─┬→ f3a9c2d18e04 (merge)
→ a1b8c3d049e4 ─┘
→ d4b7e1c08a92 → e7d2b4a10c95 → f8c2a1b03d14
→ g7b3e9a02c15 → h1c4d8e05f26 → i2d5f6a07b31 → j3e6a7b18c42
→ k4f7b8c29d53 → l5f8d2c31a70 → m6e0b3c42d81 → n7a1c4e53f92
→ o8b2d5c64a03 → p9c3e6d75b14 → q0d4f7e86c25 → r1e8a0b97d36
→ s2f9c1a08e47 (head)
4. 回滚
../.venv/bin/alembic downgrade -1
生产 downgrade / drop 需用户确认。
5. 允许 / 禁止
- 允许:DDL 增量;独立 revision 做小数据回填(如
openai_compat → custom)或列注释同步
- 禁止:改 baseline;migration 内调 Service;不可回滚的 destructive 变更未经确认