编写数据库迁移

本文档介绍了如何为可能遇到的不同场景构建和编写数据库迁移。 有关迁移的介绍材料,请参阅the topic guide

数据迁移和多个数据库

在使用多个数据库时,可能需要确定是否针对特定数据库运行迁移。 For example, you may want to only run a migration on a particular database.

为了做到这一点,您可以通过查看schema_editor.connection.alias属性来检查RunPython操作中的数据库连接的别名:

from django.db import migrations

def forwards(apps, schema_editor):
    if schema_editor.connection.alias != 'default':
        return
    # Your migration code goes here

class Migration(migrations.Migration):

    dependencies = [
        # Dependencies to other migrations
    ]

    operations = [
        migrations.RunPython(forwards),
    ]

您还可以提供将作为**hints传递给数据库路由器的allow_migrate()方法的提示:

MYAPP / dbrouters.py
class MyRouter:

    def allow_migrate(self, db, app_label, model_name=None, **hints):
        if 'target_db' in hints:
            return db == hints['target_db']
        return True

然后,要在您的迁移中利用这一点,请执行以下操作:

from django.db import migrations

def forwards(apps, schema_editor):
    # Your migration code goes here
    ...

class Migration(migrations.Migration):

    dependencies = [
        # Dependencies to other migrations
    ]

    operations = [
        migrations.RunPython(forwards, hints={'target_db': 'default'}),
    ]

If your RunPython or RunSQL operation only affects one model, it’s good practice to pass model_name as a hint to make it as transparent as possible to the router. 这对于可重复使用和第三方应用程序尤其重要。

添加唯一字段的迁移

应用“普通”迁移将唯一的不可空字段添加到具有现有行的表中将引发错误,因为用于填充现有行的值只生成一次,从而打破了唯一约束。

因此,应采取以下步骤。 在这个例子中,我们将添加一个具有默认值的不可为空的UUIDField 根据您的需要修改相应的字段。

  • 使用default=uuid.uuid4unique=True参数在模型中添加字段(为正在添加的字段的类型选择一个适当的默认值)。

  • 运行makemigrations命令。 这应该通过AddField操作生成迁移。

  • 通过两次运行makemigrations myapp - 空,为同一应用生成两个空迁移文件。 我们已经将迁移文件重命名为在下面的示例中给出有意义的名称。

  • 将自动生成的迁移(三个新文件中的第一个)的AddField操作复制到上次迁移,将AddField更改为AlterField并添加uuidmodels的导入。 例如:

    0006_remove_uuid_null.py
    # Generated by Django A.B on YYYY-MM-DD HH:MM
    from django.db import migrations, models
    import uuid
    
    class Migration(migrations.Migration):
    
        dependencies = [
            ('myapp', '0005_populate_uuid_values'),
        ]
    
        operations = [
            migrations.AlterField(
                model_name='mymodel',
                name='uuid',
                field=models.UUIDField(default=uuid.uuid4, unique=True),
            ),
        ]
    
  • 编辑第一个迁移文件。 生成的迁移类应如下所示:

    0004_add_uuid_field.py
    class Migration(migrations.Migration):
    
        dependencies = [
            ('myapp', '0003_auto_20150129_1705'),
        ]
    
        operations = [
            migrations.AddField(
                model_name='mymodel',
                name='uuid',
                field=models.UUIDField(default=uuid.uuid4, unique=True),
            ),
        ]
    

    unique=True更改为null=True - 这将创建中间空字段,并推迟创建唯一约束,直到我们在所有行上填充了唯一值。

  • 在第一个空的迁移文件中,添加一个RunPythonRunSQL操作来为每个现有行生成一个唯一的值(在本例中为UUID)。 还要添加uuid的导入。 例如:

    0005_populate_uuid_values.py
    # Generated by Django A.B on YYYY-MM-DD HH:MM
    from django.db import migrations
    import uuid
    
    def gen_uuid(apps, schema_editor):
        MyModel = apps.get_model('myapp', 'MyModel')
        for row in MyModel.objects.all():
            row.uuid = uuid.uuid4()
            row.save(update_fields=['uuid'])
    
    class Migration(migrations.Migration):
    
        dependencies = [
            ('myapp', '0004_add_uuid_field'),
        ]
    
        operations = [
            # omit reverse_code=... if you don't want the migration to be reversible.
            migrations.RunPython(gen_uuid, reverse_code=migrations.RunPython.noop),
        ]
    
  • 现在,您可以像平常一样使用migrate命令应用迁移。

    请注意,如果允许在迁移运行时创建对象,则会出现争用情况。 AddField之后和RunPython之前创建的对象将会覆盖原来的uuid

非原子迁移

在支持DDL事务的数据库上(SQLite和PostgreSQL),默认情况下,迁移将在事务内运行。 对于在大型表上执行数据迁移等用例,您可能希望通过将atomic属性设置为False来防止迁移在事务中运行:

from django.db import migrations

class Migration(migrations.Migration):
    atomic = False

在这种迁移中,所有操作都是在没有交易的情况下运行的。 可以使用atomic()或将atomic=True传递给RunPython执行事务内部的部分迁移。

下面是一个非原子数据迁移的例子,它以较小的批次更新大表:

import uuid

from django.db import migrations, transaction

def gen_uuid(apps, schema_editor):
    MyModel = apps.get_model('myapp', 'MyModel')
    while MyModel.objects.filter(uuid__isnull=True).exists():
        with transaction.atomic():
            for row in MyModel.objects.filter(uuid__isnull=True)[:1000]:
                row.uuid = uuid.uuid4()
                row.save()

class Migration(migrations.Migration):
    atomic = False

    operations = [
        migrations.RunPython(gen_uuid),
    ]

atomic属性对不支持DDL事务的数据库(例如MySQL,Oracle)没有影响。

控制迁移的顺序

Django决定迁移的顺序,而不是每个迁移的文件名,而是通过在Migration类中使用两个属性来构建一个图:dependenciesrun_before

如果您已经使用了makemigrations命令,那么您可能已经看到了dependencies,因为自动创建的迁移将其定义为其创建过程的一部分。

dependencies属性声明如下:

from django.db import migrations

class Migration(migrations.Migration):

    dependencies = [
        ('myapp', '0123_the_previous_migration'),
    ]

通常这样就足够了,但有时您可能需要确保您的迁移在其他迁移之前运行 例如,在您的AUTH_USER_MODEL替换之后,第三方应用程序的迁移运行非常有用。

要实现这一点,请将所有依赖于您的迁移放置在Migration类的run_before属性中:

class Migration(migrations.Migration):
    ...

    run_before = [
        ('third_party_app', '0001_do_awesome'),
    ]

在可能的情况下,优先在run_before之前使用dependencies 如果在您要写入的迁移之后要迁移的迁移中指定dependencies,则只应使用run_before

在第三方应用程序之间迁移数据

您可以使用数据迁移将数据从一个第三方应用程序移动到另一个。

如果您打算稍后移除旧应用程序,则需要根据是否安装旧应用程序来设置dependencies属性。 否则,一旦你卸载旧的应用程序,你将失去依赖关系。 同样,您需要在apps.get_model()调用中捕获LookupError,以从旧应用程序中检索模型。 这种方法允许你在任何地方部署你的项目,而无需先安装,然后卸载旧的应用程序。

这是一个示例迁移:

的myapp /迁移/ 0124_move_old_app_to_new_app.py
from django.apps import apps as global_apps
from django.db import migrations

def forwards(apps, schema_editor):
    try:
        OldModel = apps.get_model('old_app', 'OldModel')
    except LookupError:
        # The old app isn't installed.
        return

    NewModel = apps.get_model('new_app', 'NewModel')
    NewModel.objects.bulk_create(
        NewModel(new_attribute=old_object.old_attribute)
        for old_object in OldModel.objects.all()
    )

class Migration(migrations.Migration):
    operations = [
        migrations.RunPython(forwards, migrations.RunPython.noop),
    ]
    dependencies = [
        ('myapp', '0123_the_previous_migration'),
        ('new_app', '0001_initial'),
    ]

    if global_apps.is_installed('old_app'):
        dependencies.append(('old_app', '0001_initial'))

还要考虑在迁移不适用时你想要发生什么。 你可以不做任何事情(如上面的例子),或从新的应用程序中删除部分或全部数据。 相应地调整RunPython操作的第二个参数。

将非托管模型更改为托管

如果要将非托管模型(managed=False)更改为托管模型,则必须先删除managed=False并在对模型进行其他与模式相关的更改之前生成迁移,因为在迁移中出现的包含要更改Meta.managed的操作的模式更改可能不适用。