本文档抓取自官方文档中心（2026-10-10 快照），具体功能以实际产品为准。

数据库迁移指南

本项目使用 Alembic 进行数据库迁移管理。

目录结构

alembic/
├── env.py               # 环境配置（读取 config_{env}.yml）
├── script.py.mako       # 迁移脚本模板
└── versions/            # 迁移脚本目录
alembic.ini              # Alembic 主配置
model/
├── migration.py         # 迁移执行模块
└── sql/
    └── baseline.sql     # 基准 SQL（用于初始化新数据库）

配置

在 config_{env}.yml 中配置：

alembic:
  auto_migrate: true      # 应用启动时是否自动执行迁移
  script_location: "alembic"  # 迁移脚本目录

常用命令

# 查看迁移历史
alembic history

# 查看当前版本
alembic current

# 升级到最新版本
alembic upgrade head

# 回滚一个版本
alembic downgrade -1

# 创建新迁移
alembic revision -m "描述信息"

# 标记数据库为最新版本（不执行迁移）
alembic stamp head

创建新迁移

1. 创建迁移脚本：

   alembic revision -m "add_new_column"

1. 编辑生成的脚本文件，在 upgrade() 和 downgrade() 中添加 SQL：

   def upgrade() -> None:
       op.execute("ALTER TABLE xxx ADD COLUMN yyy VARCHAR(255)")
   
   def downgrade() -> None:
       op.execute("ALTER TABLE xxx DROP COLUMN yyy")

1. 执行迁移：

   alembic upgrade head

初始化新数据库

1. 使用 model/sql/baseline.sql 创建所有表
2. 执行 alembic stamp head 将数据库标记为最新版本

自动迁移

当 config.alembic.auto_migrate = true 时，应用启动会自动执行 alembic upgrade head。

数据库权限要求

Alembic 需要以下权限：

• CREATE TABLE - 创建 alembic_version 版本追踪表
• ALTER TABLE - 执行表结构变更
• DROP TABLE - 执行回滚操作（可选）
• INSERT/UPDATE/DELETE - 更新版本信息

注意事项

1. 生产环境建议：关闭 auto_migrate，手动执行迁移
2. 多实例部署：确保只有一个实例执行迁移，避免并发冲突
3. 备份：执行迁移前务必备份数据库
4. 迁移失败处理：如果数据库迁移失败，系统将立即退出，不会继续启动。这是为了避免在数据库结构不一致的情况下运行，防止出现各种异常问题