157 lines
3.7 KiB
Markdown
157 lines
3.7 KiB
Markdown
|
# 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`
|