# 数据库迁移

## 概述

使用 Django 内置的迁移系统管理数据库结构变更。Django 的迁移系统基于 `django.db.migrations` 模块，能够自动检测模型变更并生成迁移脚本。

:::tip 迁移工具链
- **结构迁移**：Django 内置迁移系统（`makemigrations` + `migrate`）
- **字段注释**：Django 4.1+ 通过 `db_comment` 参数自动添加数据库字段注释
- **自定义命令**：`python manage.py add_full_comments` 回填数据库字段注释
:::

## 全新安装初始化

首次部署时，使用 Django 迁移命令完成建表：

```bash
# 方式一：执行所有迁移
python manage.py migrate

# 方式二：先生成迁移文件，再执行
python manage.py makemigrations
python manage.py migrate
```

:::tip 初始化流程
1. 确保数据库已创建：`CREATE DATABASE djangoadmin.django.elevue DEFAULT CHARACTER SET utf8mb4;`
2. 确保 `.env` 中的数据库配置正确
3. 执行 `python manage.py migrate` 自动创建所有表
:::

## Django 迁移命令

### 生成迁移脚本

修改模型后，执行以下命令自动生成迁移脚本：

```bash
# 为所有应用生成迁移
python manage.py makemigrations

# 为指定应用生成迁移
python manage.py makemigrations example

# 查看迁移状态
python manage.py showmigrations
```

:::tip 注意事项
- 执行前确保数据库连接正常（`.env` 中的数据库配置正确）
- 自动生成的迁移文件需人工审查，确认无误后再执行
- 迁移文件位于各应用的 `migrations/` 目录
:::

### 应用迁移

```bash
# 应用所有待执行的迁移
python manage.py migrate

# 应用指定应用的迁移
python manage.py migrate example

# 应用到指定迁移版本
python manage.py migrate example 0001
```

### 回滚迁移

```bash
# 回滚指定应用到初始状态
python manage.py migrate example zero

# 回滚到指定版本
python manage.py migrate example 0001
```

### 查看迁移状态

```bash
# 查看所有应用的迁移状态
python manage.py showmigrations

# 查看指定应用的迁移状态
python manage.py showmigrations example

# 查看迁移的 SQL 语句（不执行）
python manage.py sqlmigrate example 0001
```

### 手动标记迁移

对于已有数据库，手动标记为已迁移状态：

```bash
# 标记指定应用为已迁移
python manage.py migrate --fake example
```

## 字段注释管理

Django 4.1+ 支持通过 `db_comment` 参数为数据库字段添加注释。项目中的模型已自动生成 `db_comment`：

```python
class Example(BaseModel):
    name = models.CharField(
        max_length=100,
        verbose_name="案例名称",
        db_comment='案例名称'  # 数据库字段注释
    )
```

### 回填字段注释

对于已有数据库，可使用自定义命令回填字段注释：

```bash
python manage.py add_full_comments
```

该命令会遍历所有模型，为缺少注释的字段补充 `db_comment`。

## 迁移文件结构

每个应用的迁移文件位于 `application/{app_name}/migrations/` 目录：

```
application/example/
├── __init__.py
├── models.py
├── forms.py
├── services.py
├── views.py
├── urls.py
├── apps.py
├── admin.py
└── migrations/
    ├── __init__.py
    ├── 0001_initial.py    # 初始迁移
    └── 0002_xxx.py        # 后续迁移
```

## 常见操作速查

| 场景 | 命令 |
|------|------|
| 全新安装 | `python manage.py migrate` |
| 模型变更后生成迁移 | `python manage.py makemigrations` |
| 应用迁移 | `python manage.py migrate` |
| 回滚指定应用 | `python manage.py migrate <app> zero` |
| 查看迁移状态 | `python manage.py showmigrations` |
| 查看迁移 SQL | `python manage.py sqlmigrate <app> <migration>` |
| 回填字段注释 | `python manage.py add_full_comments` |

## 常见问题与排错

| 问题 | 原因 | 解决方案 |
|:----|:----|:----|
| 迁移冲突 | 多人同时修改同一模型 | `python manage.py makemigrations --merge` 合并迁移 |
| 迁移文件丢失 | 删除了 migrations 目录 | 重新 `makemigrations` 生成 |
| 表已存在 | 手动建表后执行迁移 | `python manage.py migrate --fake <app>` |
| 字段不存在 | 模型与数据库不一致 | 检查迁移文件，手动修复数据库 |
| 迁移执行缓慢 | 大表结构变更 | 考虑分批迁移或在低峰期执行 |

## 总结

Django 迁移系统通过 `makemigrations` 和 `migrate` 命令管理数据库结构变更。模型修改后自动生成迁移文件，审查无误后执行迁移。生产环境务必做好备份，迁移前先在测试环境验证。