# Alembic 数据库迁移管理规范

## 1. 概述

本规范旨在确保团队在使用 Alembic 进行数据库迁移管理时的一致性和可靠性，特别是在开发过程中对数据库模型的变更进行版本控制。

## 2. 版本管理规范

### 2.1 迁移文件命名规则

**统一采用以下命名格式**：
```
<timestamp>_<description>.py
```

- **timestamp**：使用 `YYYYMMDDHHMM` 格式的时间戳，确保迁移文件按时间顺序排序
- **description**：使用小写字母、数字和下划线，简洁描述迁移内容

**示例**：
- `202603131430_add_user_email_column.py`
- `202603140915_modify_agent_table.py`

### 2.2 版本历史管理

- **保持版本历史清晰**：每个迁移文件对应一个具体的数据库变更
- **避免合并迁移**：不要将多个不相关的变更合并到一个迁移文件中
- **版本回滚**：确保每个迁移都有对应的回滚逻辑
- **版本标记**：在重要的发布版本处添加标记，便于追踪

## 3. 开发流程规范

### 3.1 模型变更流程

1. **修改模型**：在 `app/models/` 目录中修改或添加模型
2. **生成迁移**：运行 `alembic revision --autogenerate -m "描述变更内容"`
3. **检查迁移**：手动检查生成的迁移文件，确保逻辑正确
4. **应用迁移**：运行 `alembic upgrade head` 应用到本地数据库
5. **测试验证**：确保应用正常运行，数据迁移正确
6. **提交代码**：将模型变更和迁移文件一起提交

### 3.2 协作开发流程

1. **拉取最新代码**：在开始工作前，确保拉取最新的代码和迁移文件
2. **分支管理**：在各自的分支上进行模型变更
3. **解决冲突**：如果遇到迁移文件冲突，手动解决并确保逻辑正确
4. **代码审查**：迁移文件需要经过代码审查，确保质量
5. **部署前验证**：在部署到生产环境前，在测试环境验证迁移

## 4. 最佳实践

### 4.1 迁移文件编写

- **保持简洁**：每个迁移文件只包含一个逻辑变更
- **添加注释**：对复杂的迁移逻辑添加注释说明
- **使用批量操作**：对于大量数据的迁移，使用批量操作提高性能
- **处理默认值**：为新增字段提供合理的默认值
- **考虑数据完整性**：确保迁移过程中数据的完整性

### 4.2 性能优化

- **索引创建**：在迁移中合理创建索引，提高查询性能
- **分批处理**：对于大型表的变更，使用分批处理避免锁表
- **事务管理**：合理使用事务，确保迁移的原子性

### 4.3 安全性

- **避免破坏性操作**：谨慎使用 `drop_table` 等破坏性操作
- **数据备份**：在执行重要迁移前，确保数据已经备份
- **权限控制**：确保迁移操作使用适当的数据库权限

## 5. 命令参考

### 5.1 常用命令

- **生成迁移**：
  ```bash
  alembic revision --autogenerate -m "描述变更内容"
  ```

- **应用迁移**：
  ```bash
  alembic upgrade head
  ```

- **回滚迁移**：
  ```bash
  alembic downgrade -1  # 回滚一个版本
  alembic downgrade base  # 回滚到初始状态
  ```

- **查看迁移历史**：
  ```bash
  alembic history
  ```

- **查看当前版本**：
  ```bash
  alembic current
  ```

### 5.2 环境变量

- 数据库连接字符串通过 `app/config.py` 中的 `DATABASE_URL` 配置
- 开发环境和生产环境应使用不同的数据库连接

## 6. 故障处理

### 6.1 迁移失败

1. **分析错误**：查看错误信息，确定失败原因
2. **回滚操作**：如果迁移失败，使用 `alembic downgrade` 回滚到上一个版本
3. **修复问题**：修复模型或迁移文件中的问题
4. **重新迁移**：再次运行迁移命令

### 6.2 数据丢失

- **立即停止**：发现数据丢失时立即停止操作
- **恢复备份**：使用最近的数据库备份恢复数据
- **重新迁移**：在恢复数据后，重新执行迁移

## 7. 版本控制集成

- **迁移文件**：将所有迁移文件纳入版本控制
- **忽略文件**：不要将 `alembic/versions/` 目录中的 `.pyc` 文件纳入版本控制
- **提交信息**：在提交迁移文件时，使用清晰的提交信息描述变更

## 8. 文档维护

- **更新文档**：当数据库结构发生重大变更时，更新相关文档
- **模型文档**：为复杂的模型添加文档说明
- **迁移记录**：保持迁移历史的清晰记录，便于后续维护

## 9. 附则

本规范适用于所有使用 Alembic 进行数据库迁移管理的开发人员，应严格遵守。如有特殊情况需要偏离本规范，应提前与团队沟通并获得批准。