---
title: "Writing database migrations"
version: 2.1
locale: zh-hans
source: https://docs.djangoproject.com/zh-hans/2.1/howto/writing-migrations/
canonical: https://djangodocs.dev/zh-hans/2.1/howto/writing-migrations/
---
# Writing database migrations

This document explains how to structure and write database migrations for
different scenarios you might encounter. For introductory material on
migrations, see [the topic guide](/zh-hans/2.1/topics/migrations/).

## Data migrations and multiple databases

When using multiple databases, you may need to figure out whether or not to
run a migration against a particular database. For example, you may want to
**only** run a migration on a particular database.

In order to do that you can check the database connection's alias inside a
`RunPython` operation by looking at the `schema_editor.connection.alias`
attribute:

```
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),
    ]
```

You can also provide hints that will be passed to the [`allow_migrate()`](/zh-hans/2.1/topics/db/multi-db/#allow_migrate)
method of database routers as `**hints`:

*myapp/dbrouters.py*

```python
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
```

Then, to leverage this in your migrations, do the following:

```
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. This is especially important for reusable and third-party apps.

## Migrations that add unique fields

Applying a "plain" migration that adds a unique non-nullable field to a table
with existing rows will raise an error because the value used to populate
existing rows is generated only once, thus breaking the unique constraint.

Therefore, the following steps should be taken. In this example, we'll add a
non-nullable [`UUIDField`](/zh-hans/2.1/ref/models/fields/#django.db.models.UUIDField) with a default value. Modify
the respective field according to your needs.

- Add the field on your model with `default=uuid.uuid4` and `unique=True`
  arguments (choose an appropriate default for the type of the field you're
  adding).
- Run the [`makemigrations`](/zh-hans/2.1/ref/django-admin/#django-admin-makemigrations) command. This should generate a migration
  with an `AddField` operation.
- Generate two empty migration files for the same app by running
  `makemigrations myapp --empty` twice. We've renamed the migration files to
  give them meaningful names in the examples below.
- Copy the `AddField` operation from the auto-generated migration (the first
  of the three new files) to the last migration, change `AddField` to
  `AlterField`, and add imports of `uuid` and `models`. For example:

  *0006\_remove\_uuid\_null.py*

  ```python
  # 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),
          ),
      ]
  ```
- Edit the first migration file. The generated migration class should look
  similar to this:

  *0004\_add\_uuid\_field.py*

  ```python
  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),
          ),
      ]
  ```

  Change `unique=True` to `null=True` -- this will create the intermediary
  null field and defer creating the unique constraint until we've populated
  unique values on all the rows.
- In the first empty migration file, add a
  [`RunPython`](/zh-hans/2.1/ref/migration-operations/#django.db.migrations.operations.RunPython) or
  [`RunSQL`](/zh-hans/2.1/ref/migration-operations/#django.db.migrations.operations.RunSQL) operation to generate a
  unique value (UUID in the example) for each existing row. Also add an import
  of `uuid`. For example:

  *0005\_populate\_uuid\_values.py*

  ```python
  # 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),
      ]
  ```
- Now you can apply the migrations as usual with the [`migrate`](/zh-hans/2.1/ref/django-admin/#django-admin-migrate) command.

  Note there is a race condition if you allow objects to be created while this
  migration is running. Objects created after the `AddField` and before
  `RunPython` will have their original `uuid`’s overwritten.

### Non-atomic migrations

On databases that support DDL transactions (SQLite and PostgreSQL), migrations
will run inside a transaction by default. For use cases such as performing data
migrations on large tables, you may want to prevent a migration from running in
a transaction by setting the `atomic` attribute to `False`:

```
from django.db import migrations

class Migration(migrations.Migration):
    atomic = False
```

Within such a migration, all operations are run without a transaction. It's
possible to execute parts of the migration inside a transaction using
[`atomic()`](/zh-hans/2.1/topics/db/transactions/#django.db.transaction.atomic) or by passing `atomic=True` to
`RunPython`.

Here's an example of a non-atomic data migration that updates a large table in
smaller batches:

```
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),
    ]
```

The `atomic` attribute doesn't have an effect on databases that don't support
DDL transactions (e.g. MySQL, Oracle). (MySQL's [atomic DDL statement support](https://dev.mysql.com/doc/refman/en/atomic-ddl.html) refers to individual
statements rather than multiple statements wrapped in a transaction that can be
rolled back.)

## Controlling the order of migrations

Django determines the order in which migrations should be applied not by the
filename of each migration, but by building a graph using two properties on the
`Migration` class: `dependencies` and `run_before`.

If you've used the [`makemigrations`](/zh-hans/2.1/ref/django-admin/#django-admin-makemigrations) command you've probably
already seen `dependencies` in action because auto-created
migrations have this defined as part of their creation process.

The `dependencies` property is declared like this:

```
from django.db import migrations

class Migration(migrations.Migration):

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

Usually this will be enough, but from time to time you may need to
ensure that your migration runs *before* other migrations. This is
useful, for example, to make third-party apps' migrations run *after*
your [`AUTH_USER_MODEL`](/zh-hans/2.1/ref/settings/#std-setting-AUTH_USER_MODEL) replacement.

To achieve this, place all migrations that should depend on yours in
the `run_before` attribute on your `Migration` class:

```
class Migration(migrations.Migration):
    ...

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

Prefer using `dependencies` over `run_before` when possible. You should
only use `run_before` if it is undesirable or impractical to specify
`dependencies` in the migration which you want to run after the one you are
writing.

## 在第三方应用程序中迁移数据

你可以使用数据迁移把数据从一个第三方应用程序中转移到另一个。

如果你计划要移除旧应用程序，则需要根据是否安装旧应用程序来设置 依赖 属性。否则，一旦你卸载旧应用程序，就会缺失依赖项。同样，你需要在 app.get\_model() 捕获 :exec: LookupError 来从旧应用程序中检索模型。这种途径允许你在任何地方部署项目，而无需先安装并且卸载旧应用程序。

这是一个迁移示例：

*myapp/migrations/0124\_move\_old\_app\_to\_new\_app.py*

```python
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`](/zh-hans/2.1/ref/migration-operations/#django.db.migrations.operations.RunPython) 操作的第二个参数。

## 将非托管模型变为托管的

如果你想要将非托管模型 ([`managed=False`](/zh-hans/2.1/ref/models/options/#django.db.models.Options.managed)) 变为托管的，你必须移除 `managed=False` 并且在对此模型做其他模式相关的改变前生成一次迁移，因为如果迁移中出现模式改变，对 `Meta.managed` 的修改操作不会被执行。