このドキュメントでは、遭遇する可能性のあるいくつかのシナリオに対する、データベースのマイグレーションの構成方法と書き方について説明します。マイグレーションに関する入門的な資料を探しているなら、トピック別ガイド を読んでください。
\n複数のデータベースを使用している場合、特定のデータベースに対してマイグレーションを実行するかどうかを判断する必要があるかもしれません。例えば、特定のデータベースに対してのみマイグレーションを実行したい場合です。
\nこれを行うには、 RunPython 操作の中で、 schema_editor.connection.alias 属性を見て、データベース接続のエイリアスを確認します:
from django.db import migrations\n\n\ndef forwards(apps, schema_editor):\n if schema_editor.connection.alias != "default":\n return\n # Your migration code goes here\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n # Dependencies to other migrations\n ]\n\n operations = [\n migrations.RunPython(forwards),\n ]\nYou can also provide hints that will be passed to the allow_migrate()\nmethod of database routers as **hints:
myapp/dbrouters.pyclass MyRouter:\n def allow_migrate(self, db, app_label, model_name=None, **hints):\n if "target_db" in hints:\n return db == hints["target_db"]\n return True\nこれをマイグレーションに利用するには、次のようにします:
\nfrom django.db import migrations\n\n\ndef forwards(apps, schema_editor):\n # Your migration code goes here\n ...\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n # Dependencies to other migrations\n ]\n\n operations = [\n migrations.RunPython(forwards, hints={"target_db": "default"}),\n ]\nもし RunPython や RunSQL 操作が 1 つのモデルにしか影響しないのであれば、 model_name をヒントとして渡すことで、ルーターに対して最大限、透過的になります。これは再利用可能なサードパーティアプリにとって特に重要です。
既存の行を持つテーブルにユニークな非 Null フィールドを追加する「プレーン」なマイグレーションを適用するとエラーが発生します。これは、既存の行すべてを埋めるために使用される値がただ一つだけ生成され、これがユニーク制約に違反するためです。
\nそのため、次の手順を踏む必要があります。この例では、デフォルト値を持つ非 Null の UUIDField を追加します。必要に応じて、該当するフィールドを変更してください。
モデルに default=uuid.uuid4 と unique=True 引数を持つフィールドを追加します（追加するフィールドのタイプに適切なデフォルトを選択してください）。
makemigrations コマンドを実行します。これにより、 AddField 操作を含むマイグレーションが生成されます。
同じアプリに対して makemigrations myapp --empty を2回実行して、2つの空のマイグレーションファイルを生成します。以下の例では、マイグレーションファイルにわかりやすい名前を付けるためにファイル名を変更しています。
自動生成されたマイグレーション(3つの新しいファイルのうちの最初のファイル)から AddField オペレーションを最後のマイグレーションにコピーし、 AddField を AlterField に変更し、 uuid と models のインポートを追加します。例:
0006_remove_uuid_null.py# Generated by Django A.B on YYYY-MM-DD HH:MM\nfrom django.db import migrations, models\nimport uuid\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0005_populate_uuid_values"),\n ]\n\n operations = [\n migrations.AlterField(\n model_name="mymodel",\n name="uuid",\n field=models.UUIDField(default=uuid.uuid4, unique=True),\n ),\n ]\n最初の移行ファイルを編集します。 生成された移行クラスは次のようになります:
\n0004_add_uuid_field.pyclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0003_auto_20150129_1705"),\n ]\n\n operations = [\n migrations.AddField(\n model_name="mymodel",\n name="uuid",\n field=models.UUIDField(default=uuid.uuid4, unique=True),\n ),\n ]\nunique=True を null=True に変更してください。これは、一時的にNULLフィールドを作成し、すべての行に一意な値を設定するまで、一意制約の作成を延期します。
最初の空のマイグレーションファイルに、 RunPython または RunSQL オペレーションを追加して、既存の各行に対して一意な値 (この例では UUID) を生成します。 uuid のインポートも追加します。例:
0005_populate_uuid_values.py# Generated by Django A.B on YYYY-MM-DD HH:MM\nfrom django.db import migrations\nimport uuid\n\n\ndef gen_uuid(apps, schema_editor):\n MyModel = apps.get_model("myapp", "MyModel")\n for row in MyModel.objects.all():\n row.uuid = uuid.uuid4()\n row.save(update_fields=["uuid"])\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0004_add_uuid_field"),\n ]\n\n operations = [\n # omit reverse_code=... if you don't want the migration to be reversible.\n migrations.RunPython(gen_uuid, reverse_code=migrations.RunPython.noop),\n ]\nこれで migrate コマンドを使って通常通りマイグレーションを適用することができます。
このマイグレーションの実行中にオブジェクトの作成を許可すると、競合状態が発生することに注意してください。 AddField の後でかつ RunPython の前に作成されたオブジェクトは、元の uuid が上書きされます。
DDL トランザクションをサポートしているデータベース (SQLite と PostgreSQL) では、マイグレーションはデフォルトでトランザクション内で実行されます。大きなテーブルに対してデータ移行を行う場合などには、 atomic 属性を False に設定することで、トランザクション内で移行が実行されないようにすることができます:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n atomic = False\nWithin such a migration, all operations are run without a transaction. It's\npossible to execute parts of the migration inside a transaction using\natomic() or by passing atomic=True to\nRunPython.
以下は、大きなテーブルを小さなバッチで更新する、非アトミックなデータマイグレーションの例です:
\nimport uuid\n\nfrom django.db import migrations, transaction\n\n\ndef gen_uuid(apps, schema_editor):\n MyModel = apps.get_model("myapp", "MyModel")\n while MyModel.objects.filter(uuid__isnull=True).exists():\n with transaction.atomic():\n for row in MyModel.objects.filter(uuid__isnull=True)[:1000]:\n row.uuid = uuid.uuid4()\n row.save()\n\n\nclass Migration(migrations.Migration):\n atomic = False\n\n operations = [\n migrations.RunPython(gen_uuid),\n ]\natomic 属性は DDL トランザクションをサポートしていないデータベース (MySQL や Oracle など) には影響しません。(MySQLの atomic DDL statement support は、ロールバック可能なトランザクションに包まれた複数のステートメントではなく、個々のステートメントを指します)。
Django はマイグレーションを適用する順番を、マイグレーションのファイル名ではなく、 Migration クラスの 2 つのプロパティである dependencies と run_before を使ってグラフを作成することで決定します:
makemigrations コマンドを使ったことがあるなら、おそらく dependencies の動作をすでに見ているでしょう。自動生成されたマイグレーションは作成プロセスの一部としてそれを定義するためです。
dependencies プロパティは次のように宣言されます:
from django.db import migrations\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ]\n通常はこれで十分ですが、時にはあなたのマイグレーションが他のマイグレーションよりも 先に 実行されるようにする必要があるかもしれません。これは例えば、サードパーティアプリのマイグレーションを AUTH_USER_MODEL の置換の 後に 実行させるのに便利です。
これを行うには、 Migration クラスの run_before 属性に、依存するすべてのマイグレーションを配置します:
class Migration(migrations.Migration):\n ...\n\n run_before = [\n ("third_party_app", "0001_do_awesome"),\n ]\n可能な限り、 run_before よりも dependencies を使うことを推奨します。 run_before を使うのは、書いているマイグレーションの後に実行したいマイグレーションで dependencies を指定するのが望ましくないか、現実的でない場合のみです。
データマイグレーションを使って、あるサードパーティアプリケーションから別のアプリケーションにデータを移動できます。
\n後で古いアプリを削除する予定がある場合は、古いアプリがインストールされているかどうかに基づいて dependencies プロパティを設定する必要があります。そうしないと、古いアプリをアンインストールしたときに依存関係がなくなってしまいます。同様に、古いアプリからモデルを取得する apps.get_model() の呼び出しで LookupError をキャッチする必要があります。この方法によって、古いアプリをインストールしてからアンインストールすることなく、プロジェクトをどこにでもデプロイできるようになります。
簡単なマイグレーションの例を見てみましょう:
\nmyapp/migrations/0124_move_old_app_to_new_app.pyfrom django.apps import apps as global_apps\nfrom django.db import migrations\n\n\ndef forwards(apps, schema_editor):\n try:\n OldModel = apps.get_model("old_app", "OldModel")\n except LookupError:\n # The old app isn't installed.\n return\n\n NewModel = apps.get_model("new_app", "NewModel")\n NewModel.objects.bulk_create(\n NewModel(new_attribute=old_object.old_attribute)\n for old_object in OldModel.objects.all()\n )\n\n\nclass Migration(migrations.Migration):\n operations = [\n migrations.RunPython(forwards, migrations.RunPython.noop),\n ]\n dependencies = [\n ("myapp", "0123_the_previous_migration"),\n ("new_app", "0001_initial"),\n ]\n\n if global_apps.is_installed("old_app"):\n dependencies.append(("old_app", "0001_initial"))\nまた、マイグレーションが適用されないときにどうしたいかも検討します。（上記の例のように）何もしないか、新しいアプリケーションからデータの一部または全部を削除できます。 それに応じて RunPython 操作の2番目の引数を調整します。
ManyToManyField を中間 (through) モデルを使うように変更するLink to this heading#ManyToManyField を through モデルに変更すると、デフォルトのマイグレーションは既存のテーブルを削除して新しいテーブルを作成し、既存のリレーションを失います。これを避けるには、SeparateDatabaseAndState を使用して、マイグレーションの自動検出器に新しいモデルが作成されたことを伝えながら、既存のテーブル名を新しいテーブル名に変更します。既存のテーブル名と制約名は sqlmigrate または dbshell で確認できます。新しいテーブル名は中間モデルの _meta.db_table プロパティで確認できます。新しい through モデルは ForeignKey に Django と同じ名前を使うべきです。また、追加のフィールドが必要な場合は、 SeparateDatabaseAndState の後の操作で追加してください。
例えば、 Author にリンクする ManyToManyField を持つ Book モデルがあった場合、次のように新しいフィールド is_primary を持つ中間モデル AuthorBook を追加できます:
from django.db import migrations, models\nimport django.db.models.deletion\n\n\nclass Migration(migrations.Migration):\n dependencies = [\n ("core", "0001_initial"),\n ]\n\n operations = [\n migrations.SeparateDatabaseAndState(\n database_operations=[\n # Old table name from checking with sqlmigrate, new table\n # name from AuthorBook._meta.db_table.\n migrations.RunSQL(\n sql="ALTER TABLE core_book_authors RENAME TO core_authorbook",\n reverse_sql="ALTER TABLE core_authorbook RENAME TO core_book_authors",\n ),\n ],\n state_operations=[\n migrations.CreateModel(\n name="AuthorBook",\n fields=[\n (\n "id",\n models.AutoField(\n auto_created=True,\n primary_key=True,\n serialize=False,\n verbose_name="ID",\n ),\n ),\n (\n "author",\n models.ForeignKey(\n on_delete=django.db.models.deletion.DO_NOTHING,\n to="core.Author",\n ),\n ),\n (\n "book",\n models.ForeignKey(\n on_delete=django.db.models.deletion.DO_NOTHING,\n to="core.Book",\n ),\n ),\n ],\n options={\n "constraints": [\n models.UniqueConstraint(\n fields=["author", "book"],\n name="unique_author_book",\n )\n ],\n },\n ),\n migrations.AlterField(\n model_name="book",\n name="authors",\n field=models.ManyToManyField(\n to="core.Author",\n through="core.AuthorBook",\n ),\n ),\n ],\n ),\n migrations.AddField(\n model_name="authorbook",\n name="is_primary",\n field=models.BooleanField(default=False),\n ),\n ]\n未管理状態のモデル（managed=False) を管理状態に変更する場合、 managed=False を削除し、マイグレーションを生成してから、モデルにスキーマ関連の変更を加える必要があります。これは、 Meta.managed を変更する操作を含むマイグレーションに含まれるスキーマ変更が適用されない可能性があるためです。