iTi-Flask/docs/MIGRATIONS.md

# 数据库迁移

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

## 基本规则

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

升级数据库：

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

生成 migration：

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

## 文件命名

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

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

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

生成示例：

```text
20260508_1430_9f8a7c6d2e1a_alice_add_workorder_priority.py
```

## 多个 head

合并分支后检查：

```bash
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 时合并：

```bash
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 看到模型：

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

app = create_app(model_imports=[import_models])
```

## 手工变更

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