Clawith/backend/ALEMBIC_GUIDELINES.md

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 常用命令

• 生成迁移：

  alembic revision --autogenerate -m "描述变更内容"
  

• 应用迁移：

  alembic upgrade head
  

• 回滚迁移：

  alembic downgrade -1  # 回滚一个版本
  alembic downgrade base  # 回滚到初始状态
  

• 查看迁移历史：

  alembic history
  

• 查看当前版本：

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