136 lines
4.6 KiB
Markdown
136 lines
4.6 KiB
Markdown
# 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 进行数据库迁移管理的开发人员，应严格遵守。如有特殊情况需要偏离本规范，应提前与团队沟通并获得批准。
|