メインコンテンツへスキップ
見出し画像

DjangoのORMとマイグレーションの仕組み。ForeignKey・ManyToManyがPostgreSQLのテーブルになるまで

    業務システムの多くは、顧客・注文・請求といった情報をデータベースに保存して動いています。データベースを扱うには、ふつうは SQL という専用の言葉を書く必要があります。

    Python の Web フレームワークである Django には、SQL を書かずに Python のコードだけでデータベースを扱える「ORM」という仕組みが入っています。NDシステムズも、業務システムを開発するとき、案件によっては Django の ORM を使うことがあります。

    この記事では、記事用に作った架空の「料理教室」の例を使い、ORM の考え方と、ForeignKey・OneToOneField・ManyToManyField が PostgreSQL の中でどのようなテーブルになるのかを、実際に動かした結果でまとめました。そのうえで、ORM を使うと起こりやすい「N+1 問題」と、いくつもの保存をひとまとまりにする transaction.atomic を、それぞれ1つの節にして説明します。最後に、python manage.py makemigrations と python manage.py migrate を実行したとき、内部で何が起きているかを順に見ていきます。

    まず用語をそろえる

    ORM の話に入る前に、よく出てくる言葉を整理します。

    • データベース:情報を整理して保存し、あとから探したり書き換えたりできるようにする仕組み。この記事では PostgreSQL(ポストグレスキューエル)を使います。

    • テーブル:表計算ソフトのシートのような、行と列でできた表。「講座」「受講者」のように、種類ごとに1つずつ作ります。

    • 行と列:1行が1件のデータ(1つの講座)、1列が項目(講座名・定員)です。

    • 主キー(id):行を見分けるための番号。同じ番号は2つとありません。

    • SQL:データベースに「この表を作って」「この条件で探して」と頼むための言葉です。

    • ORM(Object-Relational Mapping):プログラムの「クラス」とデータベースの「テーブル」を対応づけ、プログラムの書き方のままデータベースを扱えるようにする仕組みです。

    画像
    Python のクラスがテーブルに、クラスの属性が列に、1つ1つのインスタンスが行に対応する

    Django の公式の説明でも、「1つのモデルは、ふつう1つのデータベースのテーブルに対応する」とされています。ここでいう「モデル」は、データの形を Python で書いたクラスのことです。

    ORM の何が画期的なのか

    SQL を書かずに、Python で読み書きできる

    たとえば「田中先生が受け持つ講座」を探すとき、Django では次の1行で済みます。

    Course.objects.filter(instructor__name="田中")

    このとき Django は、この1行を SQL に組み立てて PostgreSQL に送っています。列の名前などを省いて短くすると、次のような形です。

    SELECT 講座の列 FROM school_course
    INNER JOIN school_instructor ON 講座の講師の番号 = 講師の番号
    WHERE 講師の名前 = '田中'
    • SELECT … FROM:どの表から、どの列を取り出すか

    • INNER JOIN … ON:別の表を、どの列でつなぐか

    • WHERE:どの条件に合う行だけにするか

    つまり「講座の表と講師の表をつなぎ、講師の名前が田中の行だけを取り出す」という命令です。実際の SQL では、表と列の名前がすべて正式な名前で書かれ、もっと長くなります。

    instructor__name のように2つの下線でつなぐだけで、表と表をつなぐ命令(JOIN、結合)まで Django が書いてくれます。つながりが3段・4段と深くなるほど、この差は大きくなります。

    画像
    Python の1行が、JOIN を含む SQL に組み立てられて PostgreSQL に届く

    データベースが替わっても、コードはほぼそのまま

    Django が公式に対応しているデータベースは、PostgreSQL・MariaDB・MySQL・Oracle・SQLite の5つです[3]。モデルや検索のコードは、どのデータベースでもほぼ同じように書けます。

    開発中は手元で軽い SQLite を使い、本番では PostgreSQL を使う、といった使い分けもしやすくなります。ただし、データベースごとの細かな違いはあるため、本番と同じデータベースでの確認は欠かせません。

    SQL インジェクションを防ぐ形で、問い合わせが組み立てられる

    SQL インジェクションは、入力欄に SQL の断片を紛れ込ませて、データベースに想定外の命令を実行させる攻撃です。Django の公式文書は、QuerySet(Django の検索の仕組み)は「パラメータ化」で問い合わせを組み立てるため、SQL インジェクションから守られていると説明しています[4]。

    パラメータ化とは、SQL の命令の部分と、利用者が入力した値の部分を分けてデータベースに渡すことです。値は命令として扱われないため、入力に SQL を混ぜても命令にはなりません。ただし、SQL を直接書く機能を使う場合は、自分で同じ注意を払う必要があります[4]。

    モデルが「設計図」になり、変更の履歴まで残る

    ORM の便利さは、検索だけではありません。モデルを書き換えると、Django はその差分を「マイグレーション」というファイルに書き出し、データベースの形を合わせてくれます。

    Django の公式文書は、マイグレーションを「データベースの形のためのバージョン管理」と考えるとよい、と説明しています[1]。いつ・どの項目を足したかがファイルとして残り、開発用・確認用・本番のデータベースに、同じ変更を同じ順番で当てられます。

    画像
    モデルを変えるたびに番号付きのファイルが積み重なり、どのデータベースにも同じ順番で当てられる

    便利な分、気をつけたいこともある

    ORM は SQL を隠してくれる分、何回データベースに問い合わせているかや、どこで保存が確定するかが見えにくくなります。この2つは、あとの「N+1 問題」と「transaction.atomic」の節で、例を使って詳しく説明します。

    例に使う「料理教室」のモデル

    ここからは、記事用に作った架空の料理教室を例にします。登場するのは、講師・講座・分類(タグ)・受講者・申込の5つです。

    画像
    料理教室の5つのモデルと、そのつながり
    from django.conf import settings
    from django.db import models
    
    
    class Instructor(models.Model):
        """講師"""
        name = models.CharField("名前", max_length=50)
        # 1対1:講師1人に、ログイン用のユーザー1つ
        user = models.OneToOneField(
            settings.AUTH_USER_MODEL, on_delete=models.CASCADE, related_name="instructor"
        )
    
    
    class Tag(models.Model):
        """講座の分類(和食・パン・初心者向け など)"""
        name = models.CharField("名前", max_length=30, unique=True)
    
    
    class Student(models.Model):
        """受講者"""
        name = models.CharField("名前", max_length=50)
    
    
    class Course(models.Model):
        """講座"""
        title = models.CharField("講座名", max_length=100)
        # 1対多:講師1人が、いくつもの講座を受け持つ
        instructor = models.ForeignKey(
            Instructor, on_delete=models.PROTECT, related_name="courses"
        )
        # 多対多(中間テーブルはDjangoが自動で作る)
        tags = models.ManyToManyField(Tag, blank=True, related_name="courses")
        # 多対多(中間テーブルを自分で定義する)
        students = models.ManyToManyField(
            Student, through="Enrollment", related_name="courses"
        )
    
    
    class Enrollment(models.Model):
        """申込(受講者と講座をつなぐ中間テーブル)"""
        student = models.ForeignKey(Student, on_delete=models.CASCADE)
        course = models.ForeignKey(Course, on_delete=models.CASCADE)
        applied_on = models.DateField("申込日")
    
        class Meta:
            constraints = [
                models.UniqueConstraint(
                    fields=["student", "course"], name="unique_enrollment"
                )
            ]

    検証には Django 5.2(長期サポート版)と PostgreSQL 16 を使いました。アプリの名前は school です。

    1対多:ForeignKey

    コードの意味

    「講師1人が、いくつもの講座を受け持つ」ような関係を 1対多(One to Many) と呼びます。Django では、「多」の側(講座)に ForeignKey を置きます。

    instructor = models.ForeignKey(Instructor, on_delete=models.PROTECT, related_name="courses")
    • Instructor:つながる相手のモデル

    • on_delete:相手(講師)が消されそうになったときの扱い

    • related_name:逆向きにたどるときの名前。田中先生.courses.all() で、田中先生の講座の一覧を取り出せます

    PostgreSQL の中では

    講座のテーブル school_course には、instructor_id という列ができました。Django の公式文書のとおり、項目名の後ろに「_id」を付けた名前の列が作られ、そこに講師の id が入ります[2]。

    データベースの中では、講座のテーブル(school_course)は次の4つの列になりました。

    • id:講座の番号(主キー)

    • title:講座名

    • capacity:定員

    • instructor_id:受け持つ講師の番号

    ここには、2つの大事なものができています。

    1. 外部キー制約(FOREIGN KEY):instructor_id には、講師のテーブルに実在する id しか入れられない、という決まりです。存在しない講師を指す講座は、データベースが受け付けません。

    2. インデックス(index):本の索引のように、特定の列から行をすばやく探すための仕組みです。「この講師の講座」を探すときに使われます。

    PostgreSQL は、外部キー制約を作っても、参照する側の列にインデックスを自動では作りません[5]。Django は ForeignKey にインデックスを自動で作るため[2]、この点を意識しなくても済みます。

    画像
    講座の instructor_id が講師の id を指す。外部キー制約とインデックスが一緒に作られる

    決まりの確認は、まとまりの最後に行われる

    Django が作る外部キー制約には、「確認をトランザクションの最後まで待つ」という指定(DEFERRABLE INITIALLY DEFERRED)も付いていました[6]。トランザクションは、いくつかの書き込みを「全部成功するか、全部なかったことにするか」のひとまとまりとして扱う仕組みです。

    ふつうの制約は、1つの命令を実行するたびに確認されます。この指定があると、まとまりの途中では一時的に食い違っていても、最後にそろっていれば受け付けられます。トランザクションを Django でどう使うかは、あとの「transaction.atomic」の節で詳しく見ます。

    on_delete は、データベースではなく Django が実行する

    意外なのは、on_delete=models.CASCADE(親を消したら子も消す)や PROTECT(子があれば親を消させない)が、データベースの決まりには書かれていないことです。データベースにできた外部キー制約を見ても、「親が消されたら子も消す」という指定は入っていませんでした。

    Django の公式文書は、CASCADE について「SQL の ON DELETE CASCADE の動きを Django が再現する」と説明しています[2]。実際に講座を1件消すと、Django は次の順番で削除の命令を送っていました。

    1. その講座に付いていた分類の対応(中間テーブルの行)を消す

    2. その講座への申込を消す

    3. 最後に講座そのものを消す

    Django の公式文書にあるとおり、削除のように何回も問い合わせる操作では、Django が自動でトランザクションを使います[7]。この3つも1つのまとまりとして実行され、途中で失敗すれば全部が取り消されます。また、講座を受け持っている講師を消そうとすると、PROTECT の指定により Django が ProtectedError を出して止めました。

    なお、2026年8月に公開された Django 6.1 からは、DB_CASCADE のように、削除の扱いをデータベースに任せる指定も選べるようになりました[2]。

    1対1:OneToOneField

    「講師1人に、ログイン用のユーザーが1つ」のような関係が 1対1(One to One) です。Django の公式文書は、OneToOneField を「unique=True を付けた ForeignKey に近いもの」と説明しています[2]。

    データベースの中では、講師のテーブル(school_instructor)は次の3つの列になりました。

    • id:講師の番号(主キー)

    • name:名前

    • user_id:ログイン用ユーザーの番号。ユーザーの表に実在する番号しか入らない(外部キー制約)うえに、同じ番号は1回しか使えない(一意制約)

    ForeignKey との違いは、この 一意制約(UNIQUE) が付いていることです。一意制約は「同じ値を2回入れられない」という決まりで、同じユーザーを2人の講師に結びつけることはできません。

    PostgreSQL では、一意制約を作ると、その列に一意のインデックスが自動で作られます[5]。そのため、ForeignKey のような別のインデックスは作られていません。

    画像
    1対1は、外部キーの列に「同じ値は1回まで」の決まりを足した形

    多対多:ManyToManyField

    中間テーブルを Django が自動で作る場合

    「1つの講座に分類がいくつも付き、1つの分類にも講座がいくつも属する」関係が 多対多(Many to Many) です。講座のテーブルにも分類のテーブルにも、相手の id を1つの列で持たせることはできません。

    そこで、2つの表の間に「どの講座に、どの分類が付いているか」だけを記録する 中間テーブル を作ります。Django の公式文書は、多対多のために中間の表を裏で作り、その名前はモデルのテーブル名と項目名から付ける、と説明しています[2]。

    tags = models.ManyToManyField(Tag, blank=True, related_name="courses")

    この1行で、データベースには school_course_tags という3つ目の表ができました。中身は、id のほかに2つの列だけです。

    • course_id:講座の番号

    • tag_id:分類の番号

    講座と分類の組み合わせに一意制約が付き、同じ分類を同じ講座に2回付けることはできません。コードでは 講座.tags.add(和食) と書くだけで、Django がこの中間テーブルに1行を足します。

    画像
    多対多は、2つの表の間に「組み合わせだけを記録する表」を挟んで表す

    中間テーブルを自分で定義する場合(through)

    「受講者が講座に申し込む」関係も多対多ですが、こちらは「いつ申し込んだか」も記録したい関係です。自動の中間テーブルには、id の組み合わせしか入りません。

    このようなときは、through で中間テーブルを自分のモデルとして定義します[2]。この例では、申込(Enrollment)のモデルに申込日を持たせました。

    データベースの中では、申込のテーブル(school_enrollment)は次の4つの列になりました。

    • id:申込の番号(主キー)

    • student_id:受講者の番号

    • course_id:講座の番号

    • applied_on:申込日

    自動の場合と違い、一意制約は自分で書いたもの(unique_enrollment)だけが付きます。同じ講座への二重の申込を防ぎたいなら、このように自分で制約を書いておきます。

    業務システムでは、つながりそのものに日付・年度・数量などの情報を持たせたい場面が多くあります。最初から through で中間テーブルを定義しておくと、あとから項目を足すのも簡単です。

    画像
    through を使うと、中間テーブルに申込日のような項目を足せる。

    PostgreSQL にできたもの

    5つのモデルから、PostgreSQL には次の6つのテーブルができました。多対多の分類の分だけ、モデルより1つ多くなっています。

    • school_instructor(講師)

    • school_tag(分類)

    • school_student(受講者)

    • school_course(講座)

    • school_course_tags(講座と分類の中間テーブル。Django が自動で作成)

    • school_enrollment(申込。自分で定義した中間テーブル)

    名前の付き方にも決まりがあります。テーブルは「アプリ名_モデル名」、外部キーの列は「項目名_id」、制約やインデックスには、重ならないように短い英数字(ハッシュ)が付きます。

    主キーの id は、行を足すたびに番号が自動で振られる列(PostgreSQL の identity 列)で作られていました[3]。

    また、分類の名前(unique=True の CharField)には、一意制約とは別にもう1つインデックスが作られました。Django の公式文書によると、PostgreSQL で文字の列にインデックスを付けるとき、「〜を含む」「〜で始まる」の検索(LIKE)に使える追加のインデックスを作るためです[3]。

    画像
    5つのモデルから作られた6つのテーブルと、外部キーのつながり

    N+1 問題:知らないうちに問い合わせが増える

    ORM を使った開発で、とてもよく耳にするのが「N+1 問題」です。コードは正しく動き、画面にも正しい内容が出るのに、裏でデータベースへの問い合わせが何十回、何百回と増えてしまう問題です。料理教室の例で、なぜ起きるのか、どう直すのかを順に見ていきます。

    どんなときに起きるのか

    講座の一覧の画面に、それぞれの講座の講師の名前も並べるとします。Django で素直に書くと、次のようになります。

    for c in Course.objects.all():
        print(c.title, c.instructor.name)

    このコードは正しく動きます。ただし裏では、データベースへの問い合わせが「1回+講座の数」だけ行われています。

    「N」と「1」の意味

    名前の「N+1」は、問い合わせの回数を表しています。

    • 1:最初に、講座の一覧を取りにいく1回

    • N:講座1件ごとに、その講師を取りにいく回数(講座が N 件なら N 回)

    合わせて N+1 回、という意味です。

    なぜこうなるのか

    Django は、講座を取り出した時点では、つながっている講師の中身までは取りにいきません。c.instructor と書いて講師が必要になったときに、その講座の講師だけを改めて取りにいきます[8]。

    必要になるまで取りにいかないのは、使わないデータを読まずに済むという良い面もあります。ところが、繰り返しの中で毎回つながる相手を使うと、1件ごとに問い合わせが起きてしまいます。

    買い物にたとえると、メモを受け取ってから、メモの品を1品ずつ店まで往復して買うようなものです。まとめて1回で買えば済むのに、品数の分だけ往復が増えます。

    画像
    N+1 問題は、1品ずつ店へ往復するおつかいに似ている
    画像
    何もしないと、講座の一覧を取ったあと、講座の数だけ講師を取りにいく

    実際に数えてみた

    記事用の料理教室に講座を3件入れ、問い合わせの回数を記録しました。上のコードでは、講座の一覧に1回、講師に3回で、合計4回でした。

    講座が100件なら101回、1,000件なら1,001回になる計算です。1回ずつは一瞬でも、画面を開くたびに数百回の往復が起きると、表示が目に見えて遅くなります。

    開発中はデータが数件しかないため、遅さに気づきにくいのも厄介な点です。本番でデータが増えてから「この画面だけ遅い」と気づく、というのがよくある流れです。

    画像
    講座の数が増えるほど、問い合わせの回数も増える

    直し方1:select_related(ForeignKey・1対1)

    講座から講師のように、つながる相手が1つに決まる場合は select_related を使います。

    for c in Course.objects.select_related("instructor"):
        print(c.title, c.instructor.name)

    Django は講座の表と講師の表をつないで(JOIN)、講座と講師を1回の問い合わせでまとめて取り出します。実際に数えても、講座が3件のときの問い合わせは1回だけでした。Django の公式文書によると、select_related が使えるのは ForeignKey と1対1のつながりだけです[8]。

    直し方2:prefetch_related(多対多・逆向き)

    講座ごとの分類(多対多)を並べる場合も、何もしなければ同じように講座の数だけ問い合わせが増え、3件で4回でした。こちらは prefetch_related を使います。

    for c in Course.objects.prefetch_related("tags"):
        print(c.title, [t.name for t in c.tags.all()])

    付けると、問い合わせは「講座の一覧」と「講座1・2・3の分類をまとめて」の2回になりました。どの講座にどの分類が付くかの組み合わせは、Django が Python の中で行います[8]。講師から受け持ちの講座をたどるような、逆向きのつながりにも使えます[8]。

    画像
    つながる相手が1つなら select_related、いくつもあるなら prefetch_related

    気づくための工夫

    N+1 問題は、エラーにならないため、意識して確かめないと見つかりません。特に気をつけたいのは、一覧の画面で、つながる相手の名前などを並べるところです。

    開発中は、画面ごとの問い合わせの回数を表示する道具を使うと見つけやすくなります。Django のテストには、問い合わせが決めた回数どおりかを確かめる assertNumQueries も用意されています。

    transaction.atomic:全部成功か、全部なかったことに

    業務システムでは、1つの操作で、いくつもの表に書き込むことがよくあります。このとき、途中で失敗して片方だけが保存されると、あとで直すのがとても大変です。ここでは、Django でいくつもの保存をひとまとまりにする transaction.atomic を見ていきます。

    Django の既定は「1つの命令ごとにすぐ確定」

    Django の公式文書によると、Django は既定で「自動確定(autocommit)」のモードで動きます。トランザクションの中でない限り、1つ1つの問い合わせは、すぐにデータベースに確定されます[7]。

    ここでいう「確定」は、変更をほかの利用者からも見える状態にし、あとから取り消せなくすることです。つまり何もしなければ、1つ目の保存が終わった時点で、それはもう取り消せません。

    片方だけ残ると、何が困るのか

    料理教室で、新しい講師を登録する画面を考えます。1つの操作の中で、次の2つを保存します。

    1. ログイン用のユーザーを作る

    2. そのユーザーとつながる講師を作る(1対1)

    試しに、講師の名前を決めた長さ(50文字)より長くして、2つ目の保存でエラーになるようにしました。何もしないと、エラーのあとにも、1つ目のユーザーだけがデータベースに残っていました。

    この状態になると、困ることがいくつも出てきます。

    • やり直せない:同じ人をもう一度登録しようとすると、ユーザー名がすでに使われているため断られます。実際に同じユーザー名でもう一度作ると、一意制約のエラーになりました。

    • 原因が分かりにくい:残ったユーザーは講師の画面には出てこないため、なぜ登録できないのかが、画面からは分かりません。

    • 直すのに手間がかかる:半端に残ったデータを探し出し、本番のデータベースから手で消す必要があります。

    外部キー制約は「存在しない相手を指す行」は防いでくれます。しかし「相手がいないまま残った行」は、決まりの上では正しいため防げません。途中で止まった状態を残さないためには、トランザクションが必要です。

    画像
    atomic がないと、ユーザーだけが確定して残る。atomic があれば、まとめて取り消される

    transaction.atomic で包む

    Django では、ひとまとまりにしたい保存を transaction.atomic で包みます。

    from django.db import transaction
    
    with transaction.atomic():
        user = User.objects.create(username=username)
        Instructor.objects.create(name=name, user=user)

    Django の公式文書は、atomic を「その中ではデータベースの原子性が保証されるコードのまとまり」を作るものと説明しています。まとまりが問題なく終われば変更は確定され、例外(エラー)が出れば取り消されます[7]。

    原子性(atomicity)は「それ以上分けられない」という意味です。まとまりの中の変更を、途中まで当てることはせず、「全部か、ゼロか」のどちらかとして扱います。

    同じ実験を atomic で包んで行うと、エラーのあとにユーザーも残っていませんでした。PostgreSQL の記録を見ると、Django は次の順番で命令を送っていました。

    1. BEGIN(まとまりの始め)

    2. ユーザーを足す

    3. 講師を足す → 名前が長すぎるというエラー

    4. ROLLBACK(まとまりの中の変更をすべて取り消す)

    成功した場合は、最後が ROLLBACK ではなく COMMIT(まとめて確定)になります。関数全体をまとまりにしたいときは、関数の上に @transaction.atomic と書く形も使えます[7]。

    画像
    atomic の中の保存は BEGIN から始まり、すべて成功すれば COMMIT、途中で失敗すれば ROLLBACK になる

    なお、外部キー制約の「確認をトランザクションの最後まで待つ」指定(ForeignKey の節)は、このまとまりの最後、つまり COMMIT のときに確認される、という意味です。

    画面の処理を丸ごと包む方法もある

    設定で ATOMIC_REQUESTS を有効にすると、画面1回分の処理(ビュー)全体が、1つのトランザクションになります。問題なく画面を返せれば確定し、例外が出れば取り消されます[7]。

    手軽な方法ですが、公式文書は、アクセスが増えると効率が悪くなることにも注意を促しています[7]。画面ごとに丸ごと包むか、必要な処理だけを atomic で包むかは、システムの規模や処理の中身で決めます。

    注意1:例外は atomic の外で受け止める

    atomic を使うときに、いちばん間違えやすい点です。Django は、まとまりを抜けるときに「正常に抜けたか、例外で抜けたか」を見て、確定するか取り消すかを決めます[7]。

    そのため、まとまりの中でエラーを受け止めて握りつぶすと、Django は失敗に気づけません。公式文書も「atomic の中で例外を捕まえるのは避ける」と書いています[7]。

    # 避けたい書き方:中でエラーを握りつぶす
    with transaction.atomic():
        user = User.objects.create(username=username)
        try:
            Instructor.objects.create(name=name, user=user)
        except DatabaseError:
            pass
    
    # よい書き方:atomic の外で受け止める
    try:
        with transaction.atomic():
            user = User.objects.create(username=username)
            Instructor.objects.create(name=name, user=user)
    except DatabaseError:
        # 画面に「登録できませんでした」と出すなど
        ...

    実際に上の書き方のまま、続けてデータベースを読もうとすると、TransactionManagementError(まとまりが終わるまで問い合わせはできない)というエラーで止まりました。データベースでエラーが起きたあとのまとまりは壊れた状態になり、最後に取り消すしかないためです[7]。

    注意2:メールの送信などは on_commit で

    トランザクションで取り消せるのは、データベースの中の変更だけです。まとまりの途中で送ったメールや、外のサービスへの通知は、取り消しても戻りません。

    このような処理は、transaction.on_commit に登録します。登録した処理は、まとまりが確定したあとにだけ呼ばれ、取り消された場合は捨てられて呼ばれません[7]。

    with transaction.atomic():
        user = User.objects.create(username=username)
        Instructor.objects.create(name=name, user=user)
        transaction.on_commit(send_welcome_mail)  # 確定したあとに送る

    実際に試すと、途中でエラーになったときはメールの処理が呼ばれず、成功したときは、まとまりを抜けて確定したあとに呼ばれていました。

    注意3:入れ子にすると、一部だけ取り消せる

    atomic の中に、もう1つ atomic を書くこともできます。内側の atomic は「セーブポイント」になります[7]。セーブポイントは、まとまりの途中に付ける目印で、そこまでだけを取り消せます。

    試しに、外側でユーザーを作り、内側で講師の登録を失敗させ、外側で別の名前の講師を作り直しました。結果は、内側の失敗だけが取り消され、ユーザーと作り直した講師が残りました。

    ただし、外側のまとまりがあとで失敗すれば、内側で成功した分も含めて、すべて取り消されます[7]。入れ子にしても、最後に確定するのは一番外側のまとまりです。

    画像
    例外は外で受け止める、外への処理は on_commit、入れ子は一部だけ取り消せる

    制約とトランザクションは、役割が違う

    ここまでに見た外部キー制約や一意制約は、「おかしな値を入れさせない」ための決まりです。トランザクションは、「途中で止まった状態を残さない」ための仕組みです。

    どちらか一方では、データの食い違いは防ぎきれません。データベースの決まりと atomic を組み合わせて、初めてデータが壊れにくくなります。なお、次に見る migrate も、PostgreSQL では同じトランザクションの仕組みを使って表を作っています。

    makemigrations の内部で起きていること

    ここからは、モデルからテーブルができるまでの2つの命令を見ていきます。まず python manage.py makemigrations です。

    1. 前回までの状態を、マイグレーションファイルから組み立てる

    Django は、アプリの migrations フォルダにあるファイルを番号順に読み、その中の操作を順にメモリ上で再生します[1]。こうして「前回 makemigrations を実行したときのモデルの形」を組み立てます。

    2. models.py と比べる

    組み立てた前回の形と、いまの models.py を比べて、何が変わったかを調べます[1]。ここで大事なのは、比べる相手が データベースではなく、マイグレーションファイル だということです[1]。そのため、makemigrations はデータベースに一切変更を加えません。

    3. 差分を「操作」として書き出す

    見つかった差分を、「モデルを作る」「項目を足す」といった操作の並びにして、新しいファイルに書き出します。今回の例では、次のように表示されました。

    Migrations for 'school':
      school/migrations/0001_initial.py
        + Create model Student
        + Create model Tag
        + Create model Instructor
        + Create model Course
        + Create model Enrollment
        + Add field students to course
        + Add field tags to course
        + Create constraint unique_enrollment on model enrollment

    できたファイルの中身は、Python のコードです。

    class Migration(migrations.Migration):
        dependencies = [...]   # 先に当てておくべきマイグレーション
        operations = [         # データベースに加える変更の一覧
            migrations.CreateModel(name="Student", ...),
            migrations.CreateModel(name="Course", ...),
            migrations.AddConstraint(model_name="enrollment", ...),
            # ほかの表の作成なども続く
        ]
    • dependencies:このファイルより先に当てておくべきマイグレーション。講師がログイン用ユーザーとつながるため、ユーザーのテーブルを作るマイグレーションが先に必要になります

    • operations:データベースに加える変更の一覧。SQL ではなく、「何をしたいか」を書いたものです

    画像
    makemigrations は、過去のファイルから前回の形を組み立て、models.py と比べ、差分を新しいファイルに書き出す。データベースの形は変えない

    項目を1つ足すと

    講座に「定員」を足して、もう一度 makemigrations を実行しました。

    capacity = models.PositiveSmallIntegerField("定員", default=12)

    すると、0002_course_capacity.py という2つ目のファイルができ、中身は「講座に capacity を足す」という操作1つだけでした。依存先には ("school", "0001_initial") が書かれ、0001 の次に当てるファイルだと分かるようになっています。

    続けてもう一度実行すると、No changes detected in app 'school'(変更はありません)と表示されました。ファイルから組み立てた形と models.py が、もう一致しているためです。

    migrate の内部で起きていること

    次は python manage.py migrate です。こちらが、実際にデータベースを変える命令です。

    1. どこまで当てたかを、django_migrations の表で確認する

    Django は、データベースの中に django_migrations というテーブルを作り、当て終わったマイグレーションを1行ずつ記録しています。実際に中を見ると、「school アプリの 0001_initial を、2026年10月25日 02:20 に当てた」というように、アプリ名・ファイル名・当てた日時が1行ずつ残っていました。

    migrate は、まずこの表を見て、まだ当てていないファイルを探します。

    2. 依存関係に沿って、当てる順番を決める

    各ファイルの dependencies をたどり、先に必要なものから順に並べます。python manage.py migrate --plan を付けると、実行せずに順番だけを確認できます。今回は、Django に最初から入っているユーザーなどのマイグレーションが先に並び、その後に school.0001_initial が続きました。

    3. 操作を SQL に変えて実行する

    ファイルの操作を、使っているデータベース向けの SQL に変えて実行します。どのような SQL になるかは、python manage.py sqlmigrate school 0001 で、実行せずに見ることができます[1]。

    今回の 0001 では、30行ほどの SQL が表示されました。たとえば受講者の表を作る部分は、次の1行です。

    CREATE TABLE "school_student" ("id" bigint NOT NULL PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY, "name" varchar(50) NOT NULL);

    「school_student という表を作り、id(自動で番号が振られる主キー)と name(50文字までの文字)の2つの列を持たせる」という意味です。models.py に書いた CharField(max_length=50) が varchar(50) に置き換わっていることが分かります。

    全体の流れは、次のように読み取れます。

    • まず「表を作る」命令で、6つの表をすべて作る

    • そのあと、外部キー制約とインデックスをまとめて足す

    • through を使った受講者の多対多は、「何もしない」と表示される(中間テーブルは申込のモデルとして作り済みのため)

    • 全体が「BEGIN(始め)」と「COMMIT(確定)」で囲まれている

    4. PostgreSQL では、1つのトランザクションで当てる

    最後の点が、PostgreSQL を使う利点の1つです。Django の公式文書によると、テーブルの作成や変更もトランザクションで扱える PostgreSQL と SQLite では、マイグレーションの操作は、既定でトランザクションの中で実行されます[1]。上の sqlmigrate の出力も、ファイル1つ分の命令全体が BEGIN と COMMIT で囲まれていました。

    前の節で見た atomic と同じ考え方で、途中で失敗すれば、そのマイグレーションの変更はまとめて取り消されます。テーブルが半分だけできた状態にはなりません。一方、MySQL や Oracle ではトランザクションを使わずに実行されると、同じ文書に書かれています[1]。

    5. 当て終わったら、django_migrations に記録する

    成功すると、django_migrations に1行が足されます。python manage.py showmigrations school を実行すると、当て終わったものに [X] が付いて表示されます。

    school
     [X] 0001_initial
     [X] 0002_course_capacity
    画像
    migrate は、記録の表で当て終わったものを確認し、残りを順に SQL に変えて、1つずつトランザクションで実行する

    項目を足したときの SQL

    定員を足した 0002 の SQL は、2行だけでした。1行目で、既に入っている講座にも12を入れながら定員の列を足し、2行目でデータベース側の既定値を外しています。default=12 は、新しく講座を作るときに Django の側で入れる値として扱われるためです。データベース側に既定値を持たせたい場合は、db_default という指定を使います[2]。

    PositiveSmallIntegerField(0以上の小さな整数)を指定したことで、定員の列には「0以上でなければならない」という決まり(CHECK 制約)も付きました。Python のコードで決めた「0以上」が、データベースの決まりとしても守られます。

    実務で気をつけていること

    ORM とマイグレーションの仕組みを知ると、運用で守るべきことも見えてきます。NDシステムズが Django で開発するときに気をつけている点をまとめます。

    1. マイグレーションファイルは、コードと一緒に保存する:公式文書も、ファイルはコードの一部としてコミットし、配布するものとしています[1]。開発用・本番のどちらでも、同じファイルを同じ順番で当てます。

    2. 本番に当てる前に、sqlmigrate で SQL を確認する:大きな表に列を足す、制約を足すといった変更は、どのような SQL になるかを先に見ておきます。

    3. データベースを直接書き換えない:Django は、マイグレーションファイルとだけ比べます[1]。手作業で表を変えると、ファイルと実物が食い違い、あとのマイグレーションで失敗する原因になります。

    4. データの移し替えも、マイグレーションとして書く:列の形を変えるときに、既存のデータを新しい形に移す処理も、マイグレーションファイルに Python で書けます。手順が記録に残り、どのデータベースでも同じように実行できます。

    5. 一覧の画面は、問い合わせの回数を確かめる:つながる相手を並べる画面では、select_related や prefetch_related を付け忘れていないかを見ます。データが少ない開発中こそ、回数で確かめます。

    6. いくつもの表に書く処理は、atomic でまとめる:片方だけが保存された状態は、見つけるのも直すのも大変です。メールの送信など、取り消せない処理は on_commit で確定のあとに回します。

    画像
    ORM とマイグレーションを使うときの6つの確認

    まとめ

    • ORM は、Python のクラスとデータベースのテーブルを対応づけ、SQL を書かずにデータを読み書きできるようにする仕組み

    • ForeignKey は「_id の列+外部キー制約+インデックス」、OneToOneField はそれに一意制約が付いた形、ManyToManyField は中間テーブルになる

    • on_delete の CASCADE や PROTECT は、データベースではなく Django が実行している(Django 6.1 からはデータベースに任せる指定も選べる)

    • N+1 問題は、つながる相手を1件ずつ取りにいくことで起きる。ForeignKey・1対1は select_related、多対多・逆向きは prefetch_related でまとめて取る

    • Django の既定は1つの命令ごとにすぐ確定する。いくつもの保存は transaction.atomic で包み、全部成功か全部取り消しにする

    • makemigrations はデータベースに触れず、過去のファイルと models.py を比べて差分のファイルを作る

    • migrate は django_migrations の記録を見て、残りを SQL に変え、PostgreSQL では1つずつトランザクションで当てる

    ORM のおかげで SQL を書く場面は減りますが、裏でどのようなテーブルと SQL ができているかを知っていると、設計の判断や不具合の調査に迷わなくなります。NDシステムズは、これからも使っている技術の仕組みを一つずつ確認し、学んだことを発信していきます。

    NDシステムズのサービスについて

    NDシステムズは、月額制のホームページ制作を中心に、事業のデジタル化を支援しています。独自システム開発は、顧客や受注の管理など、1つの業務に絞ったシステムを承ります。初回の無料相談(オンライン・30分)は、お問い合わせのフォームまたはメールで承ります。


    参考文献

    1. Migrations(Django 5.2 公式文書)(英語)

    2. Model field reference(Django 公式文書)(英語)

    3. Databases(Django 5.2 公式文書)(英語)

    4. Security in Django(Django 5.2 公式文書)(英語)

    5. Constraints(PostgreSQL 16 公式文書)(英語)

    6. CREATE TABLE(PostgreSQL 16 公式文書)(英語)

    7. Database transactions(Django 5.2 公式文書)(英語)

    8. QuerySet API reference(Django 5.2 公式文書)(英語)

     
     
    福岡県久留米市のNDシステムズです。IT・AI、語学、会計、数学、九州北部の風景などについて、調べて考えたことを書いています。記事は筆者が個人として調べた執筆時点の内容で、専門家の助言ではありません。最新の情報は出典でご確認ください。

    あなたへのおすすめ