djangoadmin/djangoadmin-wiki

Fork 0

Files

T

gitadmin d7a081e8b7 优化更新

2026-09-13 18:12:07 +08:00

4.2 KiB

Raw Blame History

数据库迁移

概述

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

:::tip 迁移工具链

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

全新安装初始化

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

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

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

:::tip 初始化流程

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

Django 迁移命令

生成迁移脚本

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

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

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

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

:::tip 注意事项

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

4.2 KiB Raw Blame History Unescape Escape