iTi-Flask/docs/MIGRATIONS.md

数据库迁移

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

规则

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

命令

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

多个 head：

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

模型发现

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

from iti.db import Base

class Example(Base):
    __tablename__ = "example"

同步 iTi-System

uv run iti-system migrations sync --target migrations/versions
uv run alembic upgrade head

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