迁移

迁移文件

迁移以磁盘格式存储，这里称为“迁移文件”。这些文件实际上是普通的 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 模块）时寻找的是 django.db.migrations.Migration 的子类，称为 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()

撤销迁移

可以通过 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 中的迁移文件是由 Operations 组成的，你用于数据迁移的主要操作是 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 需要一个可调用对象作为它的参数，这个可调用对象需要两个参数——第一个是 应用注册表 ，其中加载了所有模型的历史版本，以匹配迁移所在的位置，第二个是 SchemaEditor，你可以用它来手动实现数据库架构的变更（但要注意，这样做会混淆迁移自动检测器！）

让我们编写一个迁移，使用 first_name 和 last_name 的组合值填充新的 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 = '%s %s' % (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 问题，请将循环依赖中的外键分离到单独的迁移中，并将依赖项移到另一个应用上。如果你不确定，请参见 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 实例
• uuid.UUID 实例
• functools.partial() 和具有可序列化 func、args 和 keywords 值的 functools.partialmethod 实例。
• Pure and concrete path objects from pathlib. Concrete paths are converted to their pure path equivalent, e.g. pathlib.PosixPath to pathlib.PurePosixPath.
• os.PathLike instances, e.g. os.DirEntry, which are converted to str or bytes using os.fspath().
• 包含可序列化值的 LazyObject 实例。
• 枚举类型（例如 TextChoices 或 IntegerChoices）实例。
• 任何 Django 字段
• 任何函数或方法引用（如 datetime.datetime.today）（必须在模块的顶层范围内）
• 在类主体内部使用的未绑定方法
• 任何类引用（必须在模块的顶层范围内）
• 具有自定义 deconstruct() 方法的任何东西（见下文）

Django 不能序列化：

• 嵌套类
• 任何类实例（例如 MyClass(4.3, 5.7)）
• 匿名函数

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