はじめに

モデルの管理画面での表示名を変更した際に、マイグレーションファイルを作成し忘れてしまいました(;_;)

Django のマイグレーションの仕組みについて正しく理解できていなかったので、調べた内容をまとめます🥕

この記事でわかること

Django のマイグレーションの基本的な仕組み

追記

GitHub Actions で Django のマイグレーション漏れを自動検出する方法についての記事を書きました_φ(･_･

マイグレーションとは

Django のマイグレーションは、モデルへの変更をデータベーススキーマに反映するための仕組みです。

基本的な流れは以下のようになります。

モデルを変更する：models.py を編集する
マイグレーションファイルを生成する：python manage.py makemigrations
データベースに適用する：python manage.py migrate

マイグレーションはデータベーススキーマのバージョン管理システムのようなもので、マイグレーションファイルは git のコミットのような役割です。

マイグレーションファイルに記録される内容

マイグレーションファイルには、モデルに対して行った変更が「オペレーション（操作）」として記録されます。

オペレーションの種類はいくつかあり、代表的なものは以下です。

オペレーション	対応する変更
`CreateModel`	モデルの新規作成
`DeleteModel`	モデルの削除
`AddField`	フィールドの追加
`RemoveField`	フィールドの削除
`AlterField`	フィールドの変更
`AlterModelOptions`	`Meta` オプション（表示名など）の変更

DB に影響する変更（フィールドの追加など）では、python manage.py migrate を実行すると SQL が実行され、テーブル構造が変更されます。
一方、表示名の変更はテーブル構造に影響しないため、SQL は実行されません。Django は django_migrations テーブルで適用済みのマイグレーションを管理しています。表示名の変更では、このテーブルに適用記録が残るだけです。

Django はモデルの変更履歴を完全に保持するために、DB に影響しない変更もマイグレーションとして記録する必要があります。

✍️ 補足

マイグレーションファイルを生成した後、migrate で適用する前にどのような SQL が実行されるかを sqlmigrate コマンドで確認することができます。

python manage.py sqlmigrate アプリ名 マイグレーション番号

AlterModelOptions（モデルの表示名の変更）と AlterField（フィールドの表示名の変更）を含むマイグレーションで実行すると、以下のように出力されます。

--
-- Change Meta options on mymodel
--
-- (no-op)
--
-- Alter field my_field on related_model
--
-- (no-op)

(no-op) は「何もしない」を意味します。どちらの変更も表示名のみの変更であるため、SQL は実行されません。

まとめ

マイグレーションは、モデルの変更をデータベーススキーマに反映するための仕組み
モデルを変更したら makemigrations → migrate の順に実行する
表示名の変更は AlterModelOptions として記録されるが、SQL は実行されない
DB に影響しない変更も、変更履歴を完全に保持するためにマイグレーションファイルの作成が必要

参考