# 数据库迁移

iTi-Flask 使用 Alembic 管理数据库 schema。

## 规则

- 每个业务项目只有一条 Alembic migration 流。
- `migrations/versions` 必须提交。
- 已发布 migration 不回改。
- 生产只执行 `python -m alembic upgrade head`。
- `iti-system` 的 migration 通过 CLI 同步进业务项目 migration 流。

## 命令

```bash
uv run python -m alembic revision --autogenerate -m "alice add workorder priority"
uv run python -m alembic upgrade head
uv run python -m alembic current
uv run python -m alembic heads
```

多个 head：

```bash
uv run python -m alembic merge heads -m "alice merge heads before release"
uv run python -m alembic upgrade head
```

## 模型发现

Alembic `env.py` 使用 `iti.db.Base.metadata`。
业务模型只要继承 `iti.db.Base`，并在 `env.py` 或应用导入链中被 import，即可参与 autogenerate。

```python
from iti.db import Base

class Example(Base):
    __tablename__ = "example"
```

## 同步 iTi-System

```bash
uv run iti-system migrations sync --target migrations/versions
uv run python -m alembic upgrade head
```

业务项目可在同步后继续新增自己的 migration。