マイグレーションファイルは一つ以上の オペレーション、データベースに対してマイグレーションが行うべき操作を宣言的に保持するオブジェクト、から構成されます。
加えて Django はモデルが過去からどのように変遷したかを解明するため、またマイグレーションを自動的に記述できるように最後のマイグレーション以降モデルに対して行われた変更を導出するために、これらの オペレーション オブジェクトを利用します;マイグレーションの定義が宣言的であるのはそのためで、これは Django がプロジェクトの全容がどういった物であるかを解析する際、データベースを直接操作することなく、容易にマイグレーション定義を全てメモリ上にロードして処理できる事を意味します。
データのマイグレーション や高度なデータベースへの手動操作のような特別な オペレーション も存在します。もし頻繁に行われる独自の変更をカプセル化したければ独自に オペレーション を記述する事もできます。
もし独自の Operation オブジェクトを定義する空のマイグレーションファイルが必要であれば、python manage.py makemigrations --empty yourappname を実行するだけですが、手動でのスキーマ変更操作の追加はマイグレーションの自動検出機構の誤動作を招き、makemigrations を実行した出力結果が正常な物でなくなる可能性が有る事に十分注意してください。
Django が提供するコア機能は全て django.db.migrations.operations モジュールから利用できます。
より入門的な内容に関しては、 トピックスのマイグレーション を参照ください。
\nCreateModelLink to this heading#プロジェクトの履歴に新たなモデル、そしてデータベース上に対応するテーブルを作成します。
\nname は models.py ファイルに定義されているであろうモデルの名称です。
fields は (フィールド名, フィールドのインスタンス) という 2 値のタプルのリストです。フィールドのインスタンスは束縛されないフィールド(他のモデルから取得した物でなく、単に models.CharField(...) 等と記述する物)でなければいけません。
options は定義されるモデルの Meta クラスの値からなるオプションの辞書オブジェクトです。
bases は定義するモデルが継承する他のクラスのリストです;このリストは定義するモデルが他のモデルに依存する(履歴上のバージョンを継承する)場合、クラスオブジェクトを文字列として "appname.ModelName" という形式で含むことができます。このパラメータが空である場合、定義するモデルは標準の models.Model からの継承だけというデフォルト設定を利用します。
managers は (マネージャ名, マネージャのインスタンス) という 2 値のタプルのリストを受け取ります。マイグレーションの間はリスト内で最初に定義されたマネージャがこのモデルの標準マネージャとして利用されます。
DeleteModelLink to this heading#プロジェクトの履歴からモデルを、加えてデータベースから該当モデルを扱うテーブルを削除します。
\nRenameModelLink to this heading#モデルの名称を今までの名称から新しい名称に変更します。
\n一度に定義しているモデルの名前とかなり多くのフィールドの名前を変更した場合は手動でこの処理を追加する必要があるかもしれません;マイグレーションの自動検知機構が古い名称を持ったモデルを削除して異なった名称のモデルを追加したと認識してしまうため、そのマイグレーション処理は古いテーブルの全てのデータを消去してしまいます。
\nAlterModelTableLink to this heading#定義しているモデルのテーブル名を変更します(Meta サブクラスの db_table オプションを参照します)。
AlterUniqueTogetherLink to this heading#Changes the model's set of unique constraints (the\nunique_together option on the Meta\nsubclass).
AlterIndexTogetherLink to this heading#Changes the model's set of custom indexes (the\nindex_together option on the Meta\nsubclass).
AlterOrderWithRespectToLink to this heading#Makes or deletes the _order column needed for the\norder_with_respect_to option on the Meta\nsubclass.
AlterModelOptionsLink to this heading#Stores changes to miscellaneous model options (settings on a model's Meta)\nlike permissions and verbose_name. Does not affect the database, but\npersists these changes for RunPython instances to use. options\nshould be a dictionary mapping option names to values.
AlterModelManagersLink to this heading#Alters the managers that are available during migrations.
\nAddFieldLink to this heading#Adds a field to a model. model_name is the model's name, name is\nthe field's name, and field is an unbound Field instance (the thing\nyou would put in the field declaration in models.py - for example,\nmodels.IntegerField(null=True).
The preserve_default argument indicates whether the field's default\nvalue is permanent and should be baked into the project state (True),\nor if it is temporary and just for this migration (False) - usually\nbecause the migration is adding a non-nullable field to a table and needs\na default value to put into existing rows. It does not affect the behavior\nof setting defaults in the database directly - Django never sets database\ndefaults and always applies them in the Django ORM code.
RemoveFieldLink to this heading#Removes a field from a model.
\nBear in mind that when reversed, this is actually adding a field to a model.\nThe operation is reversible (apart from any data loss, which of course is\nirreversible) if the field is nullable or if it has a default value that can be\nused to populate the recreated column. If the field is not nullable and does\nnot have a default value, the operation is irreversible.
\nAlterFieldLink to this heading#Alters a field's definition, including changes to its type,\nnull, unique,\ndb_column and other field attributes.
The preserve_default argument indicates whether the field's default\nvalue is permanent and should be baked into the project state (True),\nor if it is temporary and just for this migration (False) - usually\nbecause the migration is altering a nullable field to a non-nullable one and\nneeds a default value to put into existing rows. It does not affect the\nbehavior of setting defaults in the database directly - Django never sets\ndatabase defaults and always applies them in the Django ORM code.
Note that not all changes are possible on all databases - for example, you\ncannot change a text-type field like models.TextField() into a number-type\nfield like models.IntegerField() on most databases.
RenameFieldLink to this heading#Changes a field's name (and, unless db_column\nis set, its column name).
AddIndexLink to this heading#Creates an index in the database table for the model with model_name.\nindex is an instance of the Index class.
RemoveIndexLink to this heading#Removes the index named name from the model with model_name.
RunSQLLink to this heading#データベース上で任意の SQL を実行させる事ができます - データベースバックエンドで Django が直接サポートしていない先進機能、例えば部分インデックス等、を利用する上で有用です。
\nsql および、与えられれば reverse_sql もデータベース上で実行するための SQL 文字列である必要が有ります。多くの(PostgreSQL を除いた)データベースバックエンドにおいて、Django は与えられた SQL を実行前に独立した句で分割します。この処理は Python の sqlparse ライブラリを必要とします。
文字列もしくは 2 値のタプルのリストを渡すことができます。その内後者はクエリとパラメータを cursor.execute() において行うのと同じ形式で渡すために用いられます。以下の 3 つの処理は互いに等価です:
\nmigrations.RunSQL("INSERT INTO musician (name) VALUES ('Reinhardt');")\nmigrations.RunSQL([("INSERT INTO musician (name) VALUES ('Reinhardt');", None)])\nmigrations.RunSQL([("INSERT INTO musician (name) VALUES (%s);", ['Reinhardt'])])\nクエリにパーセント文字リテラルを含ませたい場合、パラメータを渡していればパーセント文字を二重に記述する必要が有ります。
\nreverse_sql クエリはマイグレーションが非適用となった場合に実行され、前のクエリで行われた変更を取り消す事ができます:
migrations.RunSQL(\n [("INSERT INTO musician (name) VALUES (%s);", ['Reinhardt'])],\n [("DELETE FROM musician where name=%s;", ['Reinhardt'])],\n)\n引数 state_operations にはプロジェクトのステートから見た SQL と等価となる処理を渡すことができます;例えば、手動でカラムを作成した場合、マイグレーションの自動検知機構が最新のモデルのステートを保持できるように AddField のリストを渡す必要が有ります(そうしなければ、次に makemigrations を実行した際、フィールドを追加した処理を一切検知せずに同じ追加処理を再度適用してしまうでしょう)。例として:
migrations.RunSQL(\n "ALTER TABLE musician ADD COLUMN name varchar(255) NOT NULL;",\n state_operations=[\n migrations.AddField(\n 'musician',\n 'name',\n models.CharField(max_length=255),\n ),\n ],\n)\nオプションの hints 引数はデータベースルータオブジェクトの allow_migrate() メソッドに **hints として渡されてルーティングの決定を補助します。データベースのヒントに関しての詳細は Hints を参照ください。
オプションの elidable 引数はこの処理を マイグレーションの統合 を行った際に消去する(省略する)か否かを決定します。
指定された順序での処理を行わない場合、sql もしくは reverse_sql に対して RunSQL.noop 要素を渡します。これは特に処理を逆の順序で行いたい場合に有用です。
RunPythonLink to this heading#マイグレーション履歴を反映して独自の Python コードを実行します。code (与えられれば加えて reverse_code )は二つの引数を受け取る呼び出し可能オブジェクトでなければなりません;第一引数はプロジェクトの履歴において処理の場所が一致している履歴を反映したモデルを含んだ django.apps.registry.Apps のインスタンスであり、第二引数は SchemaEditor のインスタンスです。
reverse_code 引数はマイグレーションが非適用となった際に呼び出されます。この呼び出し可能オブジェクトはマイグレーションが逆順処理可能となるよう、先の呼び出し可能オブジェクト code で行われた処理を無効化しなければなりません。
オプションの hints 引数はルーティングの決定を補助するためにデータベースルータの allow_migrate() メソッドに **hints として渡されます。データベースのヒントに関しての詳細は Hints を参照してください。
オプションの elidable 引数はこの処理を マイグレーションの統合 を行った際に消去する(省略する)か否かを決定します。
上記マイグレーションファイル内の Migration クラスにおいてコードが分割された関数として記述され、単に RunPython に渡すだけで良い状態にすることが推奨されます。以下に RunPython を用いて Country モデル上の初期オブジェクトを追加する例を示します:
from django.db import migrations\n\ndef forwards_func(apps, schema_editor):\n # We get the model from the versioned app registry;\n # if we directly import it, it'll be the wrong version\n Country = apps.get_model("myapp", "Country")\n db_alias = schema_editor.connection.alias\n Country.objects.using(db_alias).bulk_create([\n Country(name="USA", code="us"),\n Country(name="France", code="fr"),\n ])\n\ndef reverse_func(apps, schema_editor):\n # forwards_func() creates two Country instances,\n # so reverse_func() should delete them.\n Country = apps.get_model("myapp", "Country")\n db_alias = schema_editor.connection.alias\n Country.objects.using(db_alias).filter(name="USA", code="us").delete()\n Country.objects.using(db_alias).filter(name="France", code="fr").delete()\n\nclass Migration(migrations.Migration):\n\n dependencies = []\n\n operations = [\n migrations.RunPython(forwards_func, reverse_func),\n ]\nこれは データのマイグレーション の作成、独自のデータ更新と構成変更、そして ORM や Python のコードにアクセスを必要とするあらゆる操作のために行われる一般的な操作です。
\nもし South マイグレーションツールから移行した場合、これは基本的に処理として South の方式を用いています - 即ち順序通りおよび逆順のマイグレーションに対して 1 つもしくは 2 つのメソッドを用い、ORM とスキーマの操作が可能になるという方式です。多くの場合、South による orm.Model もしくは orm["appname", "Model"] に対する参照は、本マイグレーションツールによる apps.get_model("appname", "Model") に対する参照に直接置き換えて考える事ができ、残りのコードの大半はデータのマイグレーションに際して変更が不要です。しかしながら、他のアプリケーション内のマイグレーションが本アプリケーションの依存関係に組み込まれない限り apps は本アプリケーション内のモデルへの参照のみを持ちます。
RunSQL と同様、もし内部のスキーマを変更する場合は Django のモデル機構のスコープ範囲外(例えば triggers 等)で行うか、もしくはモデルの状態に変更を反映する処理に SeparateDatabaseAndState を追加する事を心がけてください - そうでなければ、バージョン管理された ORM およびマイグレーションの自動検出機構が正常に動作しなくなります。
標準では RunPython は DDL トランザクションをサポートしないデータベース(例えば MySQL と Oracle 等)上では通常のトランザクション内で記述された内容の処理を行います。この仕組みは安全ではありますが、これらのデータベースバックエンドを利用中に schema_editor を利用しようとするとクラッシュを引き起こす場合が有ります;このような場合は、RunPython に対して atomic=False を渡してください。
トランザクション中の DDL 使用をサポートしているデータベース(SQLite や PostgreSQL)においては、RunPython は各マイグレーションに対して作成されたトランザクション以外に自動的にトランザクションを保持しません。そのため、例えば PostgreSQL では、スキーマ変更と RunPython を同一のマイグレーション内で結合させて用いるのは避けるべきであり、そうしなければ OperationalError: cannot ALTER TABLE "mytable" because it has pending trigger events のようなエラーに遭遇する可能性が有ります。
もしここまでに挙げられた物と異なるデータベースを利用しておりトランザクション中の DDL 事項をサポートしているか不明な場合、 django.db.connection.features.can_rollback_ddl 属性を確認してください。
もし RunPython 操作が 非アトミックなマイグレーション の一部である場合、その操作は RunPython 操作に対して atomic=True が渡されて生成されたトランザクション中においてのみ実行されます。
指定された順序で処理を行いたくない場合は code もしくは reverse_code に RunPython.noop メソッドを渡してください。この指定は処理を逆順で行いたい場合に特に有用です。
SeparateDatabaseAndStateLink to this heading#作業の観点からデータベース(スキーマ変更)と状態(自動検知機構による)を組み合わせて併用する、高度に特殊化された処理です。
\n2 つの行う処理のリストを受け取り、状態を適用する必要が有る場合は状態に関するリストを利用し、データベースの変更を行う必要が有る場合はデータベースのリストを利用します。あなたがこの操作によって何が起きるかを明確に認識していない場合はこの操作を行わないでください。
\nオペレーションは比較的シンプルな API を持っており、Django に内蔵された機能を独自に補助する処理を簡単に記述できるよう設計されています。Operation の基本構造は以下のようなものです:
from django.db.migrations.operations.base import Operation\n\nclass MyCustomOperation(Operation):\n\n # If this is False, it means that this operation will be ignored by\n # sqlmigrate; if true, it will be run and the SQL collected for its output.\n reduces_to_sql = False\n\n # If this is False, Django will refuse to reverse past this operation.\n reversible = False\n\n def __init__(self, arg1, arg2):\n # Operations are usually instantiated with arguments in migration\n # files. Store the values of them on self for later use.\n pass\n\n def state_forwards(self, app_label, state):\n # The Operation should take the 'state' parameter (an instance of\n # django.db.migrations.state.ProjectState) and mutate it to match\n # any schema changes that have occurred.\n pass\n\n def database_forwards(self, app_label, schema_editor, from_state, to_state):\n # The Operation should use schema_editor to apply any changes it\n # wants to make to the database.\n pass\n\n def database_backwards(self, app_label, schema_editor, from_state, to_state):\n # If reversible is True, this is called when the operation is reversed.\n pass\n\n def describe(self):\n # This is used to describe what the operation does in console output.\n return "Custom Operation"\n上の例をテンプレートとして利用する事ができますが、django.db.migrations.operations 内の Django 内蔵のオペレーションを参考にする事もできます - これらは ProjectState のような半内部的側面を持つマイグレーションフレームワークとその履歴上のモデルを取得する方法、同様に ModelState が state_forwards() によってその履歴上のモデルを模倣する方法等の可読性が高く広範にわたる例を持っています。
いくつかの注意すべき点
\n単純なマイグレーションについて記述するだけであれば ProjectState について多くを学ぶ必要は有りません; ただそれがアプリケーションの(それに対して get_model を呼ぶことができる)登録情報へのアクセスを提供するプロパティ app を持っている事だけ知っていて下さい。
database_forwards および database_backwards は共にパラメータとして 2 つの状態を受け取ります; これらは単に適用される事になる state_forwards メソッドの差異を表しているだけですが、利便性と実行速度のために渡されます。
If you want to work with model classes or model instances from the\nfrom_state argument in database_forwards() or\ndatabase_backwards(), you must render model states using the\nclear_delayed_apps_cache() method to make related models available:
def database_forwards(self, app_label, schema_editor, from_state, to_state):\n # This operation should have access to all models. Ensure that all models are\n # reloaded in case any are delayed.\n from_state.clear_delayed_apps_cache()\n ...\ndatabase_backwards メソッドにおける to_state は 古い 状態を示します;そのため、その値はマイグレーションが状態を戻した場合は現在の状態となります。
内蔵されたオペレーションにおいて references_model が実装されているのを見つけるかもしれません;これは独自のオペレーションのためでなく自動検知機構のコードの一部として存在しています。
簡単な例として、(PostgreSQL のより興味深い機能を含んだ) PostgreSQL 拡張をロードするオペレーションを作成してみましょう。これはかなり単純な物となります;モデルの状態を変えず、1 つのコマンドを実行するだけです:
\nfrom django.db.migrations.operations.base import Operation\n\nclass LoadExtension(Operation):\n\n reversible = True\n\n def __init__(self, name):\n self.name = name\n\n def state_forwards(self, app_label, state):\n pass\n\n def database_forwards(self, app_label, schema_editor, from_state, to_state):\n schema_editor.execute("CREATE EXTENSION IF NOT EXISTS %s" % self.name)\n\n def database_backwards(self, app_label, schema_editor, from_state, to_state):\n schema_editor.execute("DROP EXTENSION %s" % self.name)\n\n def describe(self):\n return "Creates extension %s" % self.name\n