iTi-Flask/docs/MIGRATIONS.md

数据库迁移

iTi-Flask 只初始化 Flask-Migrate。 业务表由业务项目自己维护 migration。

基本规则

• 每个业务项目只保留一条 Alembic migration 流。
• migrations/versions 必须提交到 Git。
• 运行时数据库文件不提交。
• 已发布的 migration 不回头修改。
• 生产只执行 db upgrade。

升级数据库：

uv run python -m flask --app app.py db upgrade

生成 migration：

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

文件命名

模板已配置 migration 文件名格式：

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

message 第一个词写作者名，后面写变更说明。

生成示例：

20260508_1430_9f8a7c6d2e1a_alice_add_workorder_priority.py

多个 head

合并分支后检查：

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

发布前应保持一个 head。

模型导入

业务项目通过 model_imports 让 Alembic 看到模型：

from iti.applications import create_app
from my_app.models import import_models

app = create_app(model_imports=[import_models])

手工变更

不要直接修改生产库结构。 发生紧急手工变更后，应补 migration，并让目标库回到一致的 Alembic 版本。