156 lines
4.2 KiB
Markdown
156 lines
4.2 KiB
Markdown
# 数据库迁移
|
||
|
||
## 概述
|
||
|
||
使用 Django 内置的迁移系统管理数据库结构变更。Django 的迁移系统基于 `django.db.migrations` 模块，能够自动检测模型变更并生成迁移脚本。
|
||
|
||
:::tip 迁移工具链
|
||
- **结构迁移**：Django 内置迁移系统（`makemigrations` + `migrate`）
|
||
- **字段注释**：Django 4.1+ 通过 `db_comment` 参数自动添加数据库字段注释
|
||
:::
|
||
|
||
## 全新安装初始化
|
||
|
||
首次部署时，使用 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`，在执行 `migrate` 时会自动同步到数据库：
|
||
|
||
```python
|
||
class Example(BaseModel):
|
||
name = models.CharField(
|
||
max_length=100,
|
||
verbose_name="案例名称",
|
||
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 makemigrations --merge` 合并迁移 |
|
||
| 迁移文件丢失 | 删除了 migrations 目录 | 重新 `makemigrations` 生成 |
|
||
| 表已存在 | 手动建表后执行迁移 | `python manage.py migrate --fake <app>` |
|
||
| 字段不存在 | 模型与数据库不一致 | 检查迁移文件，手动修复数据库 |
|
||
| 迁移执行缓慢 | 大表结构变更 | 考虑分批迁移或在低峰期执行 |
|
||
|
||
## 总结
|
||
|
||
Django 迁移系统通过 `makemigrations` 和 `migrate` 命令管理数据库结构变更。模型修改后自动生成迁移文件，审查无误后执行迁移。生产环境务必做好备份，迁移前先在测试环境验证。
|