# 数据库迁移指南

本项目使用 Alembic 进行数据库版本控制和迁移管理。

## 使用 db_migrate.py 脚本

本项目提供了 `db_migrate.py` 辅助脚本，简化了数据库迁移操作。推荐使用此脚本而不是直接使用 alembic 命令。

### 创建新迁移

自动生成迁移脚本（根据模型变更）：

```bash
python db_migrate.py create "描述迁移内容"
```

手动创建空白迁移脚本：

```bash
python db_migrate.py create "描述迁移内容" --manual
```

### 执行迁移

升级到最新版本：

```bash
python db_migrate.py upgrade
```

升级指定版本：

```bash
python db_migrate.py upgrade <版本号>
```

### 降级迁移

降级到上一版本：

```bash
python db_migrate.py downgrade
```

降级到指定版本：

```bash
python db_migrate.py downgrade <版本号>
```

### 标记数据库版本

将数据库标记为指定版本（不执行实际迁移）：

```bash
python db_migrate.py stamp head
```

这在从SQL备份恢复数据库后特别有用，可以避免重复执行迁移。

### 查看迁移信息

查看当前版本：

```bash
python db_migrate.py current
```

查看迁移历史：

```bash
python db_migrate.py history
```

### 执行SQL语句

直接执行SQL语句：

```bash
python db_migrate.py sql "SQL语句"
```

## 原始 Alembic 命令参考

以下是直接使用 Alembic 的命令，仅供参考。建议优先使用上述 `db_migrate.py` 脚本。

### 创建新迁移

自动生成迁移脚本（根据模型变更）：

```bash
alembic revision --autogenerate -m "描述迁移内容"
```

手动创建空白迁移脚本：

```bash
alembic revision -m "描述迁移内容"
```

### 执行迁移

升级到最新版本：

```bash
alembic upgrade head
```

升级指定版本：

```bash
alembic upgrade <版本号>
```

升级指定步数：

```bash
alembic upgrade +<步数>
```

### 降级迁移

降级到上一版本：

```bash
alembic downgrade -1
```

降级到指定版本：

```bash
alembic downgrade <版本号>
```

降级指定步数：

```bash
alembic downgrade -<步数>
```

### 查看迁移信息

查看当前版本：

```bash
alembic current
```

查看迁移历史：

```bash
alembic history
```

查看特定迁移的SQL：

```bash
alembic upgrade <版本号>:head --sql
```

## 迁移工作流

1. 修改 SQLAlchemy 模型
2. 生成迁移脚本 `python db_migrate.py create "描述变更"`
3. 检查生成的脚本是否正确
4. 应用迁移 `python db_migrate.py upgrade`
5. 提交迁移脚本到版本控制系统