iTi-Flask/docs/MIGRATIONS.md

数据库迁移

规则

每个业务项目只保留一条 Alembic migration 流。

migrations/versions 必须提交到 Git。 运行时数据库文件不提交。

生产只从 main 升级：

flask db upgrade

分支模型

推荐分支模型：

• main：生产发布分支。
• dev：集成分支。
• user/<name>：个人开发分支。

dev 合并到 main 前必须只有一个 migration head。

文件名

migration 文件名使用日期、时间、revision 和 message slug。

migrations/alembic.ini：

file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s

migration message 第一个词是作者名。 后面自由描述。

uv run python -m flask --app app.py db migrate -m "alice add workorder priority"

生成示例：

20260508_1430_9f8a7c6d2e1a_alice_add_workorder_priority.py

合并多个 Head

个人分支合入 dev 前执行：

git fetch
git merge origin/dev
uv run python -m flask --app app.py db heads
uv run python -m flask --app app.py db current
uv run python -m flask --app app.py db upgrade

如果出现多个 head：

uv run python -m flask --app app.py db merge heads -m "alice merge heads before release"
uv run python -m flask --app app.py db upgrade

dev 应保持一个 head。

手工数据库变更

直接修改生产库结构不是正常流程。

如果发生紧急手工变更，必须当天补 migration，并把目标库恢复到一致的 Alembic 版本。

已经合并并部署过的 migration 不允许回头修改。

框架迁移

框架系统迁移会复制或同步到业务项目 migration 流。

业务项目生产仍然只执行一个命令：

flask db upgrade

同步命令：

flask iti migrations sync

默认同步到：

migrations/versions

也可以指定目录：

flask iti migrations sync --target migrations/versions

该命令只复制业务项目缺失的框架 migration。 已有同名文件不会覆盖。