マイグレーションファイルは一つ以上の オペレーション、データベースに対してマイグレーションが行うべき操作を宣言的に保持するオブジェクト、から構成されます。
加えて Django はモデルが過去からどのように変遷したかを解明するため、またマイグレーションを自動的に記述できるように最後のマイグレーション以降モデルに対して行われた変更を導出するために、これらの オペレーション オブジェクトを利用します;マイグレーションの定義が宣言的であるのはそのためで、これは Django がプロジェクトの全容がどういった物であるかを解析する際、データベースを直接操作することなく、容易にマイグレーション定義を全てメモリ上にロードして処理できる事を意味します。
データのマイグレーション や高度なデータベースへの手動操作のような特別な オペレーション も存在します。もし頻繁に行われる独自の変更をカプセル化したければ独自に オペレーション を記述する事もできます。
If you need an empty migration file to write your own Operation objects\ninto, use python manage.py makemigrations --empty yourappname, but be aware\nthat manually adding schema-altering operations can confuse the migration\nautodetector and make resulting runs of makemigrations output\nincorrect code.
Django が提供するコア機能は全て django.db.migrations.operations モジュールから利用できます。
より入門的な内容に関しては、 トピックスのマイグレーション を参照ください。
\nCreateModelLink to this heading#プロジェクトの履歴に新たなモデル、そしてデータベース上に対応するテーブルを作成します。
\nname は models.py ファイルに定義されているであろうモデルの名称です。
fields は (フィールド名, フィールドのインスタンス) という 2 値のタプルのリストです。フィールドのインスタンスは束縛されないフィールド(他のモデルから取得した物でなく、単に models.CharField(...) 等と記述する物)でなければいけません。
options は定義されるモデルの Meta クラスの値からなるオプションの辞書オブジェクトです。
bases is an optional list of other classes to have this model inherit from;\nit can contain both class objects as well as strings in the format\n"appname.ModelName" if you want to depend on another model (so you inherit\nfrom the historical version). If it's not supplied, it defaults to inheriting\nfrom the standard models.Model.
managers は (マネージャ名, マネージャのインスタンス) という 2 値のタプルのリストを受け取ります。マイグレーションの間はリスト内で最初に定義されたマネージャがこのモデルの標準マネージャとして利用されます。
DeleteModelLink to this heading#プロジェクトの履歴からモデルを、加えてデータベースから該当モデルを扱うテーブルを削除します。
\nRenameModelLink to this heading#モデルの名称を今までの名称から新しい名称に変更します。
\n一度に定義しているモデルの名前とかなり多くのフィールドの名前を変更した場合は手動でこの処理を追加する必要があるかもしれません;マイグレーションの自動検知機構が古い名称を持ったモデルを削除して異なった名称のモデルを追加したと認識してしまうため、そのマイグレーション処理は古いテーブルの全てのデータを消去してしまいます。
\nAlterModelTableLink to this heading#定義しているモデルのテーブル名を変更します(Meta サブクラスの db_table オプションを参照します)。
AlterModelTableCommentLink to this heading#Changes the model's table comment (the\ndb_table_comment option on the Meta\nsubclass).
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 index_together option on the\nMeta subclass).
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 is irreversible)\nif the field is nullable or if it has a default value that can be used to\npopulate the recreated column. If the field is not nullable and does not have a\ndefault 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.
RenameIndexLink to this heading#Renames an index in the database table for the model with model_name.\nExactly one of old_name and old_fields can be provided. old_fields\nis an iterable of the strings, often corresponding to fields of\nindex_together.
On databases that don't support an index renaming statement (SQLite and MariaDB\n< 10.5.2), the operation will drop and recreate the index, which can be\nexpensive.
\nAddConstraintLink to this heading#Creates a constraint in the database table for\nthe model with model_name.
RemoveConstraintLink to this heading#Removes the constraint named name from the model with model_name.
RunSQLLink to this heading#Allows running of arbitrary SQL on the database - useful for more advanced\nfeatures of database backends that Django doesn't support directly.
\nsql, and reverse_sql if provided, should be strings of SQL to run on\nthe database. On most database backends (all but PostgreSQL), Django will\nsplit the SQL into individual statements prior to executing them.
文字列もしくは 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クエリにパーセント文字リテラルを含ませたい場合、パラメータを渡していればパーセント文字を二重に記述する必要が有ります。
\nThe reverse_sql queries are executed when the migration is unapplied. They\nshould undo what is done by the sql queries. For example, to undo the above\ninsertion with a deletion:
migrations.RunSQL(\n sql=[("INSERT INTO musician (name) VALUES (%s);", ["Reinhardt"])],\n reverse_sql=[("DELETE FROM musician where name=%s;", ["Reinhardt"])],\n)\nIf reverse_sql is None (the default), the RunSQL operation is\nirreversible.
The state_operations argument allows you to supply operations that are\nequivalent to the SQL in terms of project state. For example, if you are\nmanually creating a column, you should pass in a list containing an AddField\noperation here so that the autodetector still has an up-to-date state of the\nmodel. If you don't, when you next run makemigrations, it won't see any\noperation that adds that field and so will try to run it again. For example:
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 として渡されてルーティングの決定を補助します。データベースのヒントに関しての詳細は ヒント を参照ください。
オプションの elidable 引数はこの処理を マイグレーションの統合 を行った際に消去する(省略する)か否かを決定します。
指定された順序での処理を行わない場合、sql もしくは reverse_sql に対して RunSQL.noop 要素を渡します。これは特に処理を逆の順序で行いたい場合に有用です。
RunPythonLink to this heading#マイグレーション履歴を反映して独自の Python コードを実行します。code (与えられれば加えて reverse_code )は二つの引数を受け取る呼び出し可能オブジェクトでなければなりません;第一引数はプロジェクトの履歴において処理の場所が一致している履歴を反映したモデルを含んだ django.apps.registry.Apps のインスタンスであり、第二引数は SchemaEditor のインスタンスです。
The reverse_code argument is called when unapplying migrations. This\ncallable should undo what is done in the code callable so that the\nmigration is reversible. If reverse_code is None (the default), the\nRunPython operation is irreversible.
オプションの hints 引数はルーティングの決定を補助するためにデータベースルータの allow_migrate() メソッドに **hints として渡されます。データベースのヒントに関しての詳細は ヒント を参照してください。
オプションの elidable 引数はこの処理を マイグレーションの統合 を行った際に消去する(省略する)か否かを決定します。
You are advised to write the code as a separate function above the Migration\nclass in the migration file, and pass it to RunPython. Here's an example of\nusing RunPython to create some initial objects on a Country model:
from django.db import migrations\n\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 [\n Country(name="USA", code="us"),\n Country(name="France", code="fr"),\n ]\n )\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\n\nclass Migration(migrations.Migration):\n dependencies = []\n\n operations = [\n migrations.RunPython(forwards_func, reverse_func),\n ]\nこれは データのマイグレーション の作成、独自のデータ更新と構成変更、そして ORM や Python のコードにアクセスを必要とするあらゆる操作のために行われる一般的な操作です。
\nRunSQL と同様、もし内部のスキーマを変更する場合は 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#データベース(スキーマ変更)と状態(自動検出機能)という2つの側面を混在させてマッチさせることができる、高度に専門化された操作です。
\nこれは2つの操作のリストを受け入れます。状態への適用を求められたときは、 state_operations リストを使用します(これは RunSQL の state_operations 引数の一般化されたバージョンです)。データベースへの変更の適用を求められたときは、 database_operations リストを使用します。
データベースの実際の状態と Django の状態のビューが同期しなくなると、マイグレーションフレームワークが壊れてしまい、データが失われることさえあります。じっくりと、データベースと状態の操作を慎重にチェックすべきです。データベースの操作をチェックするために、 sqlmigrate と dbshell を使うことができます。状態の操作をチェックするために makemigrations 、特に --dry-run を使うことができます。
For an example using SeparateDatabaseAndState, see\nChanging a ManyToManyField to use a through model.
オペレーションは比較的シンプルな API を持っており、Django に内蔵された機能を独自に補助する処理を簡単に記述できるよう設計されています。Operation の基本構造は以下のようなものです:
from django.db.migrations.operations.base import Operation\n\n\nclass MyCustomOperation(Operation):\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\n @property\n def migration_name_fragment(self):\n # Optional. A filename part suitable for automatically naming a\n # migration containing this operation, or None if not applicable.\n return "custom_operation_%s_%s" % (self.arg1, self.arg2)\nYou can take this template and work from it, though we suggest looking at the\nbuilt-in Django operations in django.db.migrations.operations - they cover\na lot of the example usage of semi-internal aspects of the migration framework\nlike ProjectState and the patterns used to get historical models, as well\nas ModelState and the patterns used to mutate historical models in\nstate_forwards().
いくつかの注意すべき点
\nYou don't need to learn too much about ProjectState to write migrations;\njust know that it has an apps property that gives access to an app\nregistry (which you can then call get_model on).
database_forwards and database_backwards both get two states passed\nto them; these represent the difference the state_forwards method would\nhave applied, but are given to you for convenience and speed reasons.
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 が実装されているのを見つけるかもしれません;これは独自のオペレーションのためでなく自動検知機構のコードの一部として存在しています。
As an example, let's make an operation that loads PostgreSQL extensions (which\ncontain some of PostgreSQL's more exciting features). Since there's no model\nstate changes, all it does is run one command:
\nfrom django.db.migrations.operations.base import Operation\n\n\nclass LoadExtension(Operation):\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\n @property\n def migration_name_fragment(self):\n return "create_extension_%s" % self.name\n