SuperAPI AI 工具集

alembic-migration

通用与其它

查看项目

更新于 10-16 06:15

技能介绍

用途:用于在异步 SQLAlchemy 2.0 + PostgreSQL 项目中管理数据库结构变更。迁移文件位于 backend/alembic/versions/,按 0001_、0002_ 编号。

主要能力与用法:先在 backend/app/db/models/ 修改模型(Mapped[...]、mapped_column()、repr、带 ondelete="CASCADE" 的关系),并确保在 backend/app/db/models/init.py 中导入,以便自动生成识别。随后执行自动生成迁移:cd backend && uv run alembic revision --autogenerate -m "add <thing>",或 make db-migrate。

生成的文件必须人工审查:确认 upgrade() 符合意图、downgrade() 可真正回滚;用 uv run alembic heads 检查 down_revision 链;留意意外删除的列/表、server defaults、枚举变更、JSON/数组类型;按既有约定为修订文件加下一顺序前缀。应用并验证:cd backend && uv run alembic upgrade head(或 make db-upgrade),用 uv run alembic current 确认已到 head,再做一次来回验证:alembic downgrade -1 && alembic upgrade head。

数据迁移/回填:在 upgrade() 中加入显式 op.execute(...) 或小型数据循环,可参考已有的 backfill.py 迁移;尽量将结构与数据变更拆分为独立且命名清晰的修订。

限制与规则:已应用于共享环境的迁移不得修改,只能新增;make dev / make bootstrap 会自动执行 alembic upgrade head,开发时无需单独步骤;模型与迁移须保持同步,仅有模型变更而无迁移,测试会因会话被 mock 而通过,但在真实 PostgreSQL 上会失败。