写点什么

Django 模型迁移指南:从命令用法到最佳实践

  • 2025-08-01
    福建
  • 本文字数:1988 字

    阅读完需:约 7 分钟

一、迁移的工作原理


Django 迁移系统本质上是一套数据库版本控制系统,它通过以下三个核心环节实现模型与数据库的同步

  • 生成迁移文件:当模型发生变更时,makemigrations 命令会生成记录变更的 Python 脚本,存储在应用的 migrations/ 目录下

your_app/└── migrations/    ├── 0001_initial.py  # 初始迁移文件    └── 0002_auto_20250606_1006.py  # 自动生成的迁移文件
复制代码


  • 应用迁移文件:运行migrate 命令会按顺序执行迁移文件,并通过数据库中的 django_migrations 表记录执行状态,确保每个迁移只被执行一次



  • 回滚迁移操作:支持将数据库状态回滚到指定的历史版本,可通过指定迁移编号或 zero 实现完全回滚


二、生成迁移文件:makemigrations


基本用法

修改模型后(比如添加字段、删除模型、修改字段类型等),使用以下命令生成迁移文件

# 为指定应用生成迁移python manage.py makemigrations your_app_name
# 为所有应用生成迁移python manage.py makemigrations
复制代码


实用选项

预览迁移内容:不实际创建文件,仅查看变更内容

python manage.py makemigrations --dry-run
复制代码


解决迁移冲突:多开发者协作时合并迁移历史

python manage.py makemigrations --merge
复制代码


迁移文件解释

迁移文件是自动生成的 Python 脚本,通常位于每个 app 的 migrations/ 文件夹下

your_app/└── migrations/    ├── 0001_initial.py    └── 0002_auto_20250606_1006.py
复制代码


文件主要内容包括

  • 迁移依赖关系(dependencies

  • 操作列表(operations):记录字段添加、删除、类型修改等具体变更

# 迁移文件示例# Generated by Django 4.2.20 on 2025-07-15 08:22
from django.conf import settingsfrom django.db import migrations, modelsimport django.db.models.deletion

class Migration(migrations.Migration):
dependencies = [ ('myapp_system', '0001_initial'), ]
operations = [ migrations.AlterField( model_name='systemnotifymessage', name='user_id', field=models.ForeignKey(db_column='user_id', db_comment='接收用户ID', db_constraint=False, help_text='接收用户ID', on_delete=django.db.models.deletion.DO_NOTHING, related_name='notify_messages', to=settings.AUTH_USER_MODEL), ), ]
复制代码


三、应用迁移:migrate


基础用法

使用场景

  • 第一次运行 Django 项目之前

  • 修改了 models.py 中的模型定义

  • 添加了第三方 Django 应用

# 应用所有未执行的迁移python manage.py migrate
# 仅应用指定应用的迁移python manage.py migrate myapp
# 应用到指定版本的迁移python manage.py migrate myapp 0001
复制代码


特殊场景处理

初始化已有数据库:当数据库表结构已存在时,使用假造 - fake-initial` 选项跳过初始迁移

python manage.py migrate --fake-initial
复制代码


查看迁移状态:检查哪些迁移已应用,哪些未应用

python manage.py showmigrations
复制代码


四、遗留数据库集成:inspectdb


当需要将 Django 与遗留数据库集成时,inspectdb工具能帮我们自动生成模型代码,省去手动编写的麻烦。

基本用法

# 查看生成的模型代码python manage.py inspectdb
# 将模型代码保存到文件python manage.py inspectdb > my_models.py
# 为特定表生成模型python manage.py inspectdb auth_user
复制代码


注意事项

使用重定向生成文件时,默认编码可能为 UTF-16 LE,导致 Django 无法识别,解决方法有两种:

  • 手动创建 Python 文件并复制内容

  • 使用 VSCode 打开文件,通过 "选择编码" 功能重新保存为 UTF-8


五、迁移回滚


回滚前的准备工作

查看当前迁移状态

python manage.py showmigrations [app_name]
# 带 [X] 标记的表示已应用的迁移,例如:myapp [X] 0001_initial [X] 0002_add_email_field [X] 0003_add_age_field
复制代码


回滚前务必备份数据库,以防意外发生

# MySQL 数据库备份示例mysqldump -u username -p dbname > backup_before_rollback.sql
复制代码


回滚操作方法

回滚到指定迁移版本

# 语法:python manage.py migrate [app_name] [迁移编号]
# 示例:将 myapp 应用回滚到 0001 版本python manage.py migrate myapp 0001
复制代码


完全回滚(清空所有迁移)

# 完全回滚 myapp 应用的所有迁移python manage.py migrate myapp zero
复制代码

回滚操作过程

  • 检查目标迁移版本与当前版本的差异

  • 自动生成反向 SQL 语句(基于迁移文件中的 operations)

  • 执行反向操作并更新 django_migrations 表记录

  • 不会删除迁移文件,只是标记其为未执行状态


六、最佳实践


  • 每次模型变更后生成并测试迁移

  • 迁移文件应纳入版本控制

  • 生产环境执行迁移前先在测试环境验证

  • 复杂变更建议分步骤进行,避免一次性大规模迁移

  • 谨慎使用回滚操作,先在测试环境验证回滚流程,再操作生产环境


文章转载自:小王子1024

原文链接:https://www.cnblogs.com/xwz1024/p/19014745

体验地址:http://www.jnpfsoft.com/?from=001YH

用户头像

还未添加个人签名 2025-04-01 加入

还未添加个人简介

评论

发布
暂无评论
Django模型迁移指南:从命令用法到最佳实践_电子尖叫食人鱼_InfoQ写作社区