命令¶

有几个命令可用于与迁移和 Django 对数据库模式的处理进行交互

• migrate，负责应用和取消应用迁移。
• makemigrations，负责根据您对模型所做的更改创建新的迁移。
• sqlmigrate，显示迁移的 SQL 语句。
• showmigrations，列出项目的迁移及其状态。

您应该将迁移视为数据库模式的版本控制系统。 makemigrations 负责将您的模型更改打包到单独的迁移文件中 - 类比于提交 - 并且 migrate 负责将它们应用到您的数据库。

每个应用程序的迁移文件都位于该应用程序内部的“migrations”目录中，旨在提交并作为其代码库的一部分进行分发。您应该在开发机器上进行一次迁移，然后在同事的机器、暂存机器以及最终的生产机器上运行相同的迁移。

迁移将在相同的数据集上以相同的方式运行并产生一致的结果，这意味着您在开发和暂存中看到的内容在相同情况下与生产中发生的情况完全相同。

Django 将为模型或字段的任何更改（即使是不影响数据库的选项）进行迁移，因为重建字段的唯一方法是拥有历史记录中的所有更改，并且您可能需要在以后的一些数据迁移中使用这些选项（例如，如果您设置了自定义验证器）。

后端支持¶

迁移在 Django 附带的所有后端以及任何第三方后端（如果它们已编程支持模式更改（通过 SchemaEditor 类完成））上受支持。

但是，在模式迁移方面，一些数据库比其他数据库更强大；下面介绍了一些注意事项。

工作流程¶

Django 可以为您创建迁移。对您的模型进行更改 - 例如，添加一个字段并删除一个模型 - 然后运行 makemigrations

$ python manage.py makemigrations
Migrations for 'books':
  books/migrations/0003_auto.py:
    - Alter field author on book

您的模型将被扫描并与当前包含在迁移文件中的版本进行比较，然后将写入一组新的迁移。请务必阅读输出以查看 makemigrations 认为您进行了哪些更改 - 它并不完美，对于复杂的更改，它可能无法检测到您期望的内容。

获得新的迁移文件后，您应该将它们应用到数据库，以确保它们按预期工作

$ python manage.py migrate
Operations to perform:
  Apply all migrations: books
Running migrations:
  Rendering model states... DONE
  Applying books.0003_auto... OK

应用迁移后，将迁移和模型更改作为单个提交提交到您的版本控制系统 - 这样，当其他开发人员（或您的生产服务器）检出代码时，他们将同时获得模型更改和相应的迁移。

如果您想为迁移指定一个有意义的名称而不是生成的名称，可以使用 makemigrations --name 选项

$ python manage.py makemigrations --name changed_my_model your_app_label

事务¶

在支持 DDL 事务的数据库（SQLite 和 PostgreSQL）上，默认情况下所有迁移操作都将在单个事务中运行。相反，如果数据库不支持 DDL 事务（例如 MySQL、Oracle），则所有操作都将在没有事务的情况下运行。

您可以通过将 atomic 属性设置为 False 来阻止迁移在事务中运行。例如

from django.db import migrations


class Migration(migrations.Migration):
    atomic = False

也可以使用 atomic() 或将 atomic=True 传递给 RunPython 在事务中执行迁移的一部分。有关更多详细信息，请参阅 非原子迁移。

依赖项¶

虽然迁移是针对每个应用程序的，但模型中隐含的表和关系过于复杂，无法一次为一个应用程序创建。当您进行需要其他内容运行的迁移时 - 例如，您在 books 应用程序中添加了指向 authors 应用程序的 ForeignKey - 生成的迁移将包含对 authors 中迁移的依赖项。

这意味着当您运行迁移时，authors 迁移会首先运行并创建 ForeignKey 引用的表，然后创建 ForeignKey 列的迁移会在之后运行并创建约束。如果没有这样做，迁移将尝试在没有引用的表存在的情况下创建 ForeignKey 列，您的数据库将抛出错误。

这种依赖行为会影响大多数迁移操作，在这些操作中，您将迁移限制为单个应用程序。将迁移限制为单个应用程序（无论是在 makemigrations 还是 migrate 中）都是尽力而为的承诺，并非保证；任何其他需要用于正确获取依赖关系的应用程序都将被使用。

没有迁移的应用程序不能与具有迁移的应用程序建立关系（ForeignKey、ManyToManyField 等）。有时它可能有效，但不受支持。

迁移文件¶

迁移以磁盘格式存储，这里称为“迁移文件”。这些文件实际上是具有约定对象布局的普通 Python 文件，以声明式风格编写。

一个基本的迁移文件如下所示

from django.db import migrations, models


class Migration(migrations.Migration):
    dependencies = [("migrations", "0001_initial")]

    operations = [
        migrations.DeleteModel("Tribble"),
        migrations.AddField("Author", "rating", models.IntegerField(default=0)),
    ]

Django 在加载迁移文件（作为 Python 模块）时，会查找名为 Migration 的 django.db.migrations.Migration 子类。然后它检查此对象是否有四个属性，其中只有两个属性在大多数情况下使用

• dependencies，此迁移依赖的迁移列表。
• operations，定义此迁移执行操作的 Operation 类列表。

操作是关键；它们是一组声明式指令，告诉 Django 需要进行哪些模式更改。Django 会扫描它们并构建所有应用程序模式更改的内存表示，并使用它来生成执行模式更改的 SQL。

该内存结构还用于找出模型与迁移当前状态之间的差异；Django 按顺序运行所有更改，在一个内存模型集上，以得出上次运行 makemigrations 时模型的状态。然后它使用这些模型与 models.py 文件中的模型进行比较，以找出您所做的更改。

您很少需要手动编辑迁移文件，但如果您需要，完全可以手动编写它们。一些更复杂的操作无法自动检测，只能通过手动编写的迁移来实现，因此如果您需要编辑它们，不要害怕。

class MyManager(models.Manager):
    use_in_migrations = True


class MyModel(models.Model):
    objects = MyManager()

class MyManager(MyBaseManager.from_queryset(CustomQuerySet)):
    use_in_migrations = True


class MyModel(models.Model):
    objects = MyManager()

向应用程序添加迁移¶

新应用程序预先配置为接受迁移，因此您可以在进行一些更改后运行 makemigrations 来添加迁移。

如果您的应用程序已经拥有模型和数据库表，但还没有迁移（例如，您是在之前的 Django 版本中创建的），则需要通过运行以下命令将其转换为使用迁移：

$ python manage.py makemigrations your_app_label

这将为您的应用程序创建一个新的初始迁移。现在，运行 python manage.py migrate --fake-initial，Django 将检测到您有一个初始迁移，并且它想要创建的表已经存在，并将标记该迁移为已应用。（如果没有 migrate --fake-initial 标志，该命令将出错，因为要创建的表已经存在。）

请注意，这只有在以下两种情况下才有效：

• 您在创建表后没有更改模型。为了使迁移正常工作，您必须首先进行初始迁移，然后进行更改，因为 Django 会将更改与迁移文件进行比较，而不是与数据库进行比较。
• 您没有手动编辑数据库 - Django 将无法检测到您的数据库与您的模型不匹配，您只会遇到迁移尝试修改这些表时的错误。

反转迁移¶

可以通过传递上一个迁移的编号，使用 migrate 来反转迁移。例如，要反转迁移 books.0003

$ python manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto... OK

...\> py manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto... OK

如果要反转为应用程序应用的所有迁移，请使用名称 zero

$ python manage.py migrate books zero
Operations to perform:
  Unapply all migrations: books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0002_auto... OK
  Unapplying books.0001_initial... OK

...\> py manage.py migrate books zero
Operations to perform:
  Unapply all migrations: books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0002_auto... OK
  Unapplying books.0001_initial... OK

如果迁移包含任何不可逆操作，则该迁移将不可逆。尝试反转此类迁移将引发 IrreversibleError

$ python manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto...Traceback (most recent call last):
django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL  sql='DROP TABLE demo_books'> in books.0003_auto is not reversible

...\> py manage.py migrate books 0002
Operations to perform:
  Target specific migration: 0002_auto, from books
Running migrations:
  Rendering model states... DONE
  Unapplying books.0003_auto...Traceback (most recent call last):
django.db.migrations.exceptions.IrreversibleError: Operation <RunSQL  sql='DROP TABLE demo_books'> in books.0003_auto is not reversible

历史模型¶

当您运行迁移时，Django 会从迁移文件中存储的模型的历史版本开始工作。如果您使用 RunPython 操作编写 Python 代码，或者您的数据库路由器上有 allow_migrate 方法，则您**需要使用**这些历史模型版本，而不是直接导入它们。

由于无法序列化任意 Python 代码，因此这些历史模型将不会包含您定义的任何自定义方法。但是，它们将具有相同的字段、关系、管理器（仅限于具有 use_in_migrations = True 的管理器）和 Meta 选项（也已版本化，因此它们可能与您当前的选项不同）。

对字段选项中函数的引用，例如 upload_to 和 limit_choices_to，以及具有 use_in_migrations = True 的管理器的模型管理器声明，将在迁移中序列化，因此只要有迁移引用这些函数和类，就需要保留它们。任何 自定义模型字段 也需要保留，因为迁移会直接导入这些字段。

此外，模型的具体基类将作为指针存储，因此只要有迁移包含对它们的引用，就必须始终保留基类。从好的方面来说，这些基类的方法和管理器会正常继承，因此如果您绝对需要访问这些方法和管理器，可以选择将它们移到超类中。

要删除旧引用，您可以 压缩迁移，或者，如果引用不多，可以将它们复制到迁移文件中。

删除模型字段时的注意事项¶

与上一节中描述的“对历史函数的引用”注意事项类似，如果旧迁移中引用了自定义模型字段，从您的项目或第三方应用程序中删除它们会导致问题。

为了帮助解决这种情况，Django 提供了一些模型字段属性，以便使用 系统检查框架 协助模型字段弃用。

将 system_check_deprecated_details 属性添加到您的模型字段，类似于以下示例

class IPAddressField(Field):
    system_check_deprecated_details = {
        "msg": (
            "IPAddressField has been deprecated. Support for it (except "
            "in historical migrations) will be removed in Django 1.9."
        ),
        "hint": "Use GenericIPAddressField instead.",  # optional
        "id": "fields.W900",  # pick a unique ID for your field.
    }

在您选择的弃用期（对于 Django 本身中的字段，两个或三个功能版本）之后，将 system_check_deprecated_details 属性更改为 system_check_removed_details 并更新字典，类似于

class IPAddressField(Field):
    system_check_removed_details = {
        "msg": (
            "IPAddressField has been removed except for support in "
            "historical migrations."
        ),
        "hint": "Use GenericIPAddressField instead.",
        "id": "fields.E900",  # pick a unique ID for your field.
    }

您应该保留字段在数据库迁移中运行所需的方法，例如 __init__()、deconstruct() 和 get_internal_type()。只要存在引用该字段的任何迁移，就保留此存根字段。例如，在压缩迁移并删除旧迁移后，您应该能够完全删除该字段。

数据迁移¶

除了更改数据库模式之外，您还可以使用迁移来更改数据库本身的数据，如果您需要的话，可以与模式一起更改。

更改数据的迁移通常称为“数据迁移”；最好将它们编写为单独的迁移，与您的模式迁移并排放置。

Django 无法像处理模式迁移那样自动为您生成数据迁移，但编写它们并不难。Django 中的迁移文件由 操作 组成，您用于数据迁移的主要操作是 RunPython。

首先，创建一个可以从中工作的空迁移文件（Django 会将文件放在正确的位置，建议一个名称，并为您添加依赖项）

python manage.py makemigrations --empty yourappname

然后，打开文件；它应该看起来像这样

# Generated by Django A.B on YYYY-MM-DD HH:MM
from django.db import migrations


class Migration(migrations.Migration):
    dependencies = [
        ("yourappname", "0001_initial"),
    ]

    operations = []

现在，您需要做的就是创建一个新函数，并让 RunPython 使用它。 RunPython 期望一个可调用对象作为其参数，该对象接受两个参数 - 第一个是 应用程序注册表，其中加载了所有模型的历史版本以匹配迁移在历史记录中的位置，第二个是 模式编辑器，您可以使用它手动执行数据库模式更改（但请注意，这样做可能会混淆迁移自动检测器！）

让我们编写一个迁移，将新的 name 字段填充为 first_name 和 last_name 的组合值（我们已经回过神来，意识到并非每个人都有姓和名）。我们只需要使用历史模型并遍历行即可。

from django.db import migrations


def combine_names(apps, schema_editor):
    # We can't import the Person model directly as it may be a newer
    # version than this migration expects. We use the historical version.
    Person = apps.get_model("yourappname", "Person")
    for person in Person.objects.all():
        person.name = f"{person.first_name} {person.last_name}"
        person.save()


class Migration(migrations.Migration):
    dependencies = [
        ("yourappname", "0001_initial"),
    ]

    operations = [
        migrations.RunPython(combine_names),
    ]

完成后，我们可以像往常一样运行 python manage.py migrate，数据迁移将在其他迁移旁边运行。

您可以向 RunPython 传递第二个可调用对象，以在向后迁移时运行您想要执行的任何逻辑。如果省略此可调用对象，则向后迁移将引发异常。

class Migration(migrations.Migration):
    dependencies = [
        ("app1", "0001_initial"),
        # added dependency to enable using models from app2 in move_m1
        ("app2", "0004_foobar"),
    ]

    operations = [
        migrations.RunPython(move_m1),
    ]

压缩迁移¶

鼓励您自由地进行迁移，不必担心迁移的次数；迁移代码经过优化，可以一次处理数百次迁移而不会造成明显的减速。但是，最终您会希望将数百次迁移减少到几次，这就是压缩的作用。

压缩是指将一组现有的多个迁移压缩成一个（有时是几个）迁移，这些迁移仍然代表相同的更改。

Django 通过获取所有现有的迁移，提取它们的 Operation 并按顺序排列，然后运行优化器来尝试缩短列表长度 - 例如，它知道 CreateModel 和 DeleteModel 相互抵消，并且它知道 AddField 可以合并到 CreateModel 中。

一旦操作序列尽可能地缩短 - 可缩短的程度取决于模型之间的紧密程度以及是否存在任何 RunSQL 或 RunPython 操作（除非标记为 elidable，否则无法优化） - Django 然后会将其写回一组新的迁移文件。

这些文件被标记为表明它们替换了先前压缩的迁移，因此它们可以与旧的迁移文件共存，并且 Django 会根据您在历史记录中的位置智能地在它们之间切换。如果您仍然处于压缩的迁移集的中间，它将继续使用它们，直到到达末尾，然后切换到压缩的历史记录，而新安装将使用新的压缩迁移并跳过所有旧的迁移。

这使您能够压缩而不会弄乱当前正在生产中但尚未完全更新的系统。推荐的流程是压缩，保留旧文件，提交并发布，等待所有系统升级到新版本（或者如果您是第三方项目，请确保您的用户按顺序升级版本，不要跳过任何版本），然后删除旧文件，提交并进行第二次发布。

支持所有这些操作的命令是 squashmigrations - 将要压缩到的应用程序标签和迁移名称传递给它，它将开始工作。

$ ./manage.py squashmigrations myapp 0004
Will squash the following migrations:
 - 0001_initial
 - 0002_some_change
 - 0003_another_change
 - 0004_undo_something
Do you wish to proceed? [yN] y
Optimizing...
  Optimized from 12 operations to 7 operations.
Created new squashed migration /home/andrew/Programs/DjangoTest/test/migrations/0001_squashed_0004_undo_something.py
  You should commit this migration but leave the old ones in place;
  the new migration will be used for new installs. Once you are sure
  all instances of the codebase have applied the migrations you squashed,
  you can delete them.

如果您想设置压缩迁移的名称，而不是使用自动生成的名称，请使用 squashmigrations --squashed-name 选项。

请注意，Django 中的模型相互依赖关系可能非常复杂，压缩可能会导致迁移无法运行；要么是优化不当（在这种情况下，您可以尝试使用 --no-optimize 再次尝试，但您也应该报告问题），要么是出现 CircularDependencyError，在这种情况下，您可以手动解决它。

要手动解决 CircularDependencyError，请将循环依赖关系链中的一个 ForeignKey 分解到单独的迁移中，并将对另一个应用程序的依赖关系与其一起移动。如果您不确定，请查看 makemigrations 在被要求从您的模型创建全新的迁移时如何处理这个问题。在 Django 的未来版本中，squashmigrations 将更新为尝试自行解决这些错误。

压缩迁移后，您应该将它与它替换的迁移一起提交，并将此更改分发到应用程序的所有运行实例，确保它们运行 migrate 以将更改存储到其数据库中。

然后，您必须将压缩的迁移转换为正常的迁移，方法是：

• 删除它替换的所有迁移文件。
• 更新所有依赖于已删除迁移的迁移，使其改为依赖于压缩的迁移。
• 从压缩迁移的 Migration 类中删除 replaces 属性（这是 Django 如何判断它是一个压缩迁移的方式）。

序列化值¶

迁移是包含模型旧定义的 Python 文件 - 因此，为了编写它们，Django 必须获取模型的当前状态并将它们序列化到文件中。

虽然 Django 可以序列化大多数内容，但有些内容无法序列化为有效的 Python 表示形式 - Python 标准中没有规定如何将值转换回代码（repr() 仅适用于基本值，并且没有指定导入路径）。

Django 可以序列化以下内容：

• int、float、bool、str、bytes、None、NoneType
• list、set、tuple、dict、range。
• datetime.date、datetime.time 和 datetime.datetime 实例（包括时区感知的实例）
• decimal.Decimal 实例
• enum.Enum 和 enum.Flag 实例
• uuid.UUID 实例
• functools.partial() 和 functools.partialmethod 实例，这些实例具有可序列化的 func、args 和 keywords 值。
• 来自 pathlib 的纯路径和具体路径对象。具体路径将转换为其纯路径等效项，例如 pathlib.PosixPath 转换为 pathlib.PurePosixPath。
• os.PathLike 实例，例如 os.DirEntry，它们使用 os.fspath() 转换为 str 或 bytes。
• LazyObject 实例，它们包装可序列化值。
• 枚举类型（例如 TextChoices 或 IntegerChoices）实例。
• 任何 Django 字段
• 任何函数或方法引用（例如 datetime.datetime.today）（必须位于模块的顶层范围）
  • 如果正确包装，函数可以进行装饰，即使用 functools.wraps()
  • functools.cache() 和 functools.lru_cache() 装饰器被明确支持
• 从类体内部使用的未绑定方法
• 任何类引用（必须位于模块的顶层范围）
• 任何具有自定义 deconstruct() 方法的项（参见下文）

Django 无法序列化

• 嵌套类
• 任意类实例（例如 MyClass(4.3, 5.7)）
• Lambda 表达式

from decimal import Decimal

from django.db.migrations.serializer import BaseSerializer
from django.db.migrations.writer import MigrationWriter


class DecimalSerializer(BaseSerializer):
    def serialize(self):
        return repr(self.value), {"from decimal import Decimal"}


MigrationWriter.register_serializer(Decimal, DecimalSerializer)

from django.utils.deconstruct import deconstructible


@deconstructible
class MyCustomClass:
    def __init__(self, foo=1):
        self.foo = foo
        ...

    def __eq__(self, other):
        return self.foo == other.foo

支持多个 Django 版本¶

如果你维护一个带有模型的第三方应用程序，你可能需要发布支持多个 Django 版本的迁移。在这种情况下，你应该始终运行 makemigrations **使用你想要支持的最低 Django 版本**。

迁移系统将根据与 Django 其他部分相同的策略维护向后兼容性，因此在 Django X.Y 上生成的迁移文件应该在 Django X.Y+1 上不变地运行。但是，迁移系统不承诺向前兼容性。可能会添加新功能，并且使用较新版本的 Django 生成的迁移文件可能无法在较旧版本上运行。