# Alembic 数据库迁移使用说明

## 概述

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

## 目录结构

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

## 基本命令

### 1. 创建新的迁移脚本

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

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

### 2. 执行迁移

```bash
# 升级到最新版本
alembic upgrade head

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

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

# 降级一个版本
alembic downgrade -1
```

### 3. 查看迁移历史

```bash
# 查看所有迁移版本
alembic history

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

# 查看待执行的迁移
alembic heads
```

## 使用流程

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

1. 确保数据库已创建：
   ```sql
   CREATE DATABASE IF NOT EXISTS agent_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

2. 执行初始迁移：
   ```bash
   alembic upgrade head
   ```

### 修改模型后创建迁移

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

2. 自动生成迁移脚本：
   ```bash
   alembic revision --autogenerate -m "添加新字段"
   ```

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

4. 执行迁移：
   ```bash
   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`