数据库迁移

概述

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

迁移工具链

• 结构迁移：Django 内置迁移系统（makemigrations + migrate）
• 字段注释：Django 4.1+ 通过 db_comment 参数自动添加数据库字段注释

全新安装初始化

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

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

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

初始化流程

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

Django 迁移命令

生成迁移脚本

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

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

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

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

注意事项

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

应用迁移

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

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

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

回滚迁移

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

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

查看迁移状态

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

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

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

手动标记迁移

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

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

字段注释管理

Django 4.1+ 支持通过 db_comment 参数为数据库字段添加注释。项目中的模型已自动生成 db_comment，在执行 migrate 时会自动同步到数据库：

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 命令管理数据库结构变更。模型修改后自动生成迁移文件，审查无误后执行迁移。生产环境务必做好备份，迁移前先在测试环境验证。