SQLBot/docs/agents/migrations.md

数据库迁移 Agent 说明

基本规则

• 数据库是 PostgreSQL；SQLModel 变更必须配套 Alembic 迁移。
• 迁移位于 backend/alembic/versions/。
• 文件名沿用三位编号加语义描述（存在 009_0、009_1 子编号形态）；编号从现有迁移文件推导下一个可用值，不要假设固定值。
• 每个迁移必须：
  • 设置唯一 revision；
  • 把 down_revision 指向当前 head；
  • 提供 upgrade() 和可执行的 downgrade()；
  • 保持单线迁移链，不创建并行 head。

生成方式：

cd backend
uv run alembic revision --autogenerate -m "073 describe change"

autogenerate 只是草稿。必须人工检查：

• 是否漏掉 xpack 或延迟导入模型的表；
• 索引、约束、默认值、nullable、comment 是否完整；
• 是否包含无关表或历史差异；
• PostgreSQL 方言是否正确，尤其是 JSONB、VECTOR 和 USING 转换。

结构迁移

• 新增非空列优先采用两步：先加 nullable 列并回填，再视需要收紧约束。
• 有默认值语义时明确 server_default，不要只依赖 Python 模型默认值。
• 修改类型时提供 PostgreSQL USING 表达式；参考 071_modify_permission_jsonb.py。
• 删除或重命名列先确认代码、导出、报表和 xpack 调用没有旧名残留。
• 不要在迁移里顺手重命名历史表或整理无关 schema。

数据迁移

• 数据回填必须分批，避免长事务锁表。
• 先明确空值、重复值和非法历史值的默认策略。
• 不要在迁移中调用业务 CRUD；使用面向迁移的 SQL 或轻量对象。
• 涉及加密、embedding 或外部系统时，说明为什么迁移期可以安全执行。
• downgrade 若无法完整恢复数据，必须显式说明局限，不要伪装成无损回滚。

xpack schema

• xpack 表结构变更属于跨仓库接口变更。
• 先确认主仓库将锁定的 xpack wheel 版本，并检查该版本中的模型。
• 不要把仅闭源功能需要的表混进开源功能迁移。
• 发布顺序遵循 docs/agents/packaging.md。

验证

在有可用的一次性开发数据库前，不要默认执行迁移。至少执行：

cd backend
uv run alembic heads
uv run alembic history

确认只有一个 head 且新迁移的父节点正确。对一次性数据库执行 upgrade head，必要时再执行一级 downgrade 验证回滚。数据库结构变更要同步检查模型、CRUD、API schema、导出/导入和 xpack 调用。