aiagent/backend/README_ALEMBIC.md

Alembic 数据库迁移使用说明

概述

本项目使用 Alembic 进行数据库版本管理和迁移。Alembic 是 SQLAlchemy 的数据库迁移工具，可以自动生成迁移脚本并管理数据库结构变更。

目录结构

backend/
├── alembic/
│   ├── versions/          # 迁移脚本目录
│   │   └── 001_initial_migration.py
│   ├── env.py             # Alembic 环境配置
│   └── script.py.mako     # 迁移脚本模板
├── alembic.ini            # Alembic 配置文件
└── migrations/            # 手动SQL脚本（备用）

基本命令

1. 创建新的迁移脚本

# 自动生成迁移脚本（推荐）
alembic revision --autogenerate -m "描述信息"

# 手动创建空迁移脚本
alembic revision -m "描述信息"

2. 执行迁移

# 升级到最新版本
alembic upgrade head

# 升级到指定版本
alembic upgrade <revision>

# 降级到指定版本
alembic downgrade <revision>

# 降级一个版本
alembic downgrade -1

3. 查看迁移历史

# 查看所有迁移版本
alembic history

# 查看当前数据库版本
alembic current

# 查看待执行的迁移
alembic heads

使用流程

首次使用（初始化数据库）

1. 确保数据库已创建：

   CREATE DATABASE IF NOT EXISTS agent_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   

2. 执行初始迁移：

   alembic upgrade head
   

修改模型后创建迁移

1. 修改 backend/app/models/ 中的模型文件

2. 自动生成迁移脚本：

   alembic revision --autogenerate -m "添加新字段"
   

3. 检查生成的迁移脚本（alembic/versions/ 目录）

4. 执行迁移：

   alembic upgrade head
   

注意事项

1. 模型导入：确保 alembic/env.py 中导入了所有模型，这样 Alembic 才能检测到模型变更。

2. 迁移脚本检查：自动生成的迁移脚本可能不完美，需要手动检查和调整：

   • 检查索引创建/删除
   • 检查外键约束
   • 检查默认值设置
   • 检查字符集和排序规则

3. 生产环境：

   • 在生产环境执行迁移前，务必先备份数据库
   • 在测试环境充分测试迁移脚本
   • 考虑数据迁移的兼容性

4. 回滚：如果迁移出现问题，可以使用 alembic downgrade 回滚到之前的版本。

常见问题

1. 迁移脚本检测不到模型变更

原因：模型没有被正确导入

解决：检查 alembic/env.py 中的模型导入，确保所有模型都被导入。

2. 迁移执行失败

原因：可能是数据库连接问题、权限问题或迁移脚本错误

解决：

• 检查数据库连接配置
• 检查数据库用户权限
• 查看错误日志，修复迁移脚本

3. 迁移冲突

原因：多人同时创建迁移脚本导致版本冲突

解决：

• 使用 alembic merge 合并分支
• 或者手动解决冲突，调整 down_revision

与手动SQL脚本的关系

项目中的 backend/migrations/ 目录包含手动SQL脚本，这些脚本用于：

• 快速初始化数据库（不依赖Alembic）
• 特定场景的数据库操作
• 数据迁移脚本

建议：优先使用 Alembic 进行数据库结构管理，手动SQL脚本作为补充。

示例

添加新表

1. 在 app/models/ 中创建新模型
2. 运行 alembic revision --autogenerate -m "添加新表"
3. 检查生成的迁移脚本
4. 运行 alembic upgrade head

修改现有表

1. 修改模型定义
2. 运行 alembic revision --autogenerate -m "修改表结构"
3. 检查生成的迁移脚本（可能需要手动调整）
4. 运行 alembic upgrade head