【保存版】マイグレーションって何？Python初心者のための完全ガイド

はじめに

「マイグレーションって何？」

プログラミングを学び始めると、この言葉に必ず出会います。DjangoやFlaskのチュートリアルを進めていると、突然 python manage.py migrate というコマンドが出てきて、「これは一体何をしているんだろう？」と疑問に思った方も多いのではないでしょうか。

この記事では、データベースの基礎知識がない方でも理解できるよう、マイグレーションの概念から実践的なツール選定まで、図解を交えて徹底的に解説します。

この記事の対象読者

• プログラミング初心者で、データベース自体もよく分かっていない方
• 「マイグレーションって何？」と検索してこの記事にたどり着いた方
• DjangoやFlaskを学習中で、マイグレーションコマンドの意味を知りたい方

この記事で得られること

• データベースとテーブルの基本的な理解
• マイグレーションの概念と必要性
• 手動管理 vs ツール利用の違い（As-Is / To-Be分析）
• 主要なPythonマイグレーションツールの選び方（Fit & Gap分析）

---

1. 前提知識の整理：データベースとテーブルとは

マイグレーションを理解するには、まず「データベース」と「テーブル」を知る必要があります。難しく考える必要はありません。Excelをイメージしてください。

データベース ＝ Excelファイル

データベースは、データを整理して保存する場所です。Excelファイル（.xlsx）のようなものだと考えてください。

テーブル ＝ Excelのシート

テーブルは、データベースの中にある「表」です。Excelでいうと1つ1つのシートに相当します。

カラム（列）と レコード（行）

用語	Excelでの相当	説明
カラム（Column）	列（A列、B列...）	データの種類（名前、年齢など）
レコード（Row）	行（1行目、2行目...）	1件分のデータ

実際のテーブルの例

たとえば、ブログアプリを作るとします。「ユーザー」と「投稿記事」という2つのテーブルが必要です。

この図は「ER図（Entity-Relationship Diagram）」と呼ばれ、テーブル同士の関係を表します。

• USERS テーブル：ユーザー情報を保存
• POSTS テーブル：投稿記事を保存
• ||--o{：「1対多」の関係（1人のユーザーが複数の投稿を持てる）

ここまでのポイント

データベース = データを保存する箱（Excelファイル）
テーブル = データの表（Excelのシート）
カラム = 列（データの種類）
レコード = 行（1件分のデータ）

---

2. マイグレーションとは

言葉の意味

「マイグレーション（Migration）」は、英語で「移行」「移動」「移住」という意味です。

IT業界では広い意味で使われますが、この記事では**「データベースの構造（テーブル設計）を変更・管理する仕組み」**に焦点を当てて解説します。

身近な例で理解する

マイグレーションは「引っ越し」に例えると分かりやすいです。

ただ荷物（データ）を運ぶだけでなく、新しい家の間取り（テーブル構造）に合わせて整理し直す作業も含まれます。

データベースマイグレーションの具体例

開発を進めていると、テーブル構造の変更が必要になることがよくあります。

例1：カラムの追加
ユーザーテーブルに「電話番号」カラムを追加したい

例2：カラムの変更
「名前」カラムの文字数上限を50文字から100文字に変更したい

例3：テーブルの追加
新しく「コメント」テーブルを作りたい

これらの変更を安全に、そして履歴を残しながら行う仕組みが「マイグレーション」です。

マイグレーションが解決する課題

マイグレーションツールがない場合、以下の問題が発生します。

問題	具体的な状況
履歴が残らない	いつ、誰が、何を変更したか分からない
共有が難しい	チームメンバーに変更内容を正確に伝えられない
戻せない	間違えた変更を元に戻すのが大変
環境差異	開発環境と本番環境でテーブル構造がズレる

---

3. なぜマイグレーションツールが必要なのか

手動でSQLを管理する場合の辛さ

マイグレーションツールを使わない場合、開発者は「SQL文」を直接書いてデータベースを操作します。

-- ユーザーテーブルに電話番号カラムを追加するSQL
ALTER TABLE users ADD COLUMN phone_number VARCHAR(20);

一見シンプルですが、実際の開発現場では以下の問題が発生します。

問題1：どのSQLを実行したか分からなくなる

開発が進むと、SQLファイルが大量に生成されます。

migrations/
├── 001_create_users.sql
├── 002_create_posts.sql
├── 003_add_phone_to_users.sql
├── 004_create_comments.sql
├── 005_modify_posts_title.sql
├── 006_add_index_to_users.sql
└── ... (どんどん増える)

「どこまで実行したっけ？」「この環境は003まで？005まで？」という混乱が生じます。

問題2：実行順序を間違えると壊れる

SQLは順番が重要です。例えば：

• 003 で users テーブルにカラムを追加
• 004 で users テーブルを参照する comments テーブルを作成

この順番を間違えると、エラーが発生します。

問題3：チームでの共有が大変

「昨日、テーブル構造を変更したからSQL実行しておいて」

このようなコミュニケーションミスで、チームメンバー間でデータベースの状態がバラバラになります。

問題4：戻すのが困難

「やっぱり前の設計の方が良かった」と思っても、手動で元に戻すSQLを書く必要があります。しかも、その「戻すSQL」も間違える可能性があります。

---

4. As-Is / To-Be 分析：手動管理 vs ツール導入

ここでは、ビジネス分析でよく使われる「As-Is / To-Be フレームワーク」を用いて、手動管理とツール導入の違いを明確にします。

As-Is（現状）：手動SQL管理の課題

現状の課題一覧

カテゴリ	課題	影響度
管理	実行済み/未実行の追跡が困難	高
共有	チーム間での変更共有が口頭ベース	高
復旧	ロールバック（巻き戻し）が手作業	高
品質	実行順序ミスによるエラー	中
効率	毎回同じ確認作業が必要	中

To-Be（あるべき姿）：マイグレーションツール導入後

導入後の改善効果

カテゴリ	改善内容	効果
管理	実行履歴を自動追跡	◎
共有	ファイルをGitで共有するだけ	◎
復旧	コマンド1つでロールバック	◎
品質	実行順序を自動管理	○
効率	確認作業が不要	○

Before / After 比較表

観点	Before（手動管理）	After（ツール導入）
変更の記録	SQLファイルを手動作成	Pythonコードから自動生成
実行管理	自分でどこまで実行したか覚える	ツールが自動で履歴管理
チーム共有	SQLファイルを送付＋口頭説明	Gitにpush/pullするだけ
元に戻す	逆のSQLを手動で作成・実行	migrate --rollback で一発
環境の統一	各自の環境で差異が発生しがち	全員が同じ状態を再現可能

---

5. 開発フローの違い（シーケンス図で理解）

実際の開発フローを、シーケンス図で比較してみましょう。

手動SQL管理の場合

手動管理の問題点

1. ステップ5-6：実行履歴の管理が開発者の記憶頼み
2. ステップ7：口頭やチャットでの連絡は抜け漏れが発生しやすい
3. ステップ8-10：各メンバーが「実行済みか？」を毎回確認する必要がある

マイグレーションツール利用の場合

ツール利用のメリット

1. ステップ3-4：変更内容を自動検知してファイル生成
2. ステップ7：実行履歴がデータベースに自動記録される
3. ステップ11-12：チームメンバーは migrate コマンドを打つだけ
4. ステップ12：ツールが「未適用の変更」だけを自動判別して実行

---

6. Fit & Gap 分析：どのツールを選ぶべきか

Pythonには主に3つのマイグレーションツールがあります。「Fit & Gap 分析」を用いて、あなたの状況に最適なツールを選びましょう。

主要ツールの概要

ツール	対応フレームワーク	難易度	特徴
Django Migrations	Django専用	★☆☆	標準搭載、最も簡単
Alembic	フレームワーク非依存	★★☆	柔軟性が高い
Flask-Migrate	Flask用	★★☆	Alembicのラッパー

Fit & Gap 分析表

あなたの状況（左列）と各ツールの適合度を確認してください。

判断軸	Django Migrations	Alembic	Flask-Migrate
Djangoを使っている	◎ 最適	△ 非推奨	× 不可
Flaskを使っている	× 不可	○ 可能	◎ 最適
FastAPIを使っている	× 不可	◎ 最適	× 不可
フレームワークを使わない	× 不可	◎ 最適	× 不可
初心者で簡単に始めたい	◎ 最適	△ やや複雑	○ 良い
細かいカスタマイズが必要	○ 可能	◎ 最適	○ 可能
チュートリアルが充実	◎ 豊富	○ 中程度	○ 中程度

選定フローチャート

Gap（不足・課題）の対処法

各ツールには弱点もあります。事前に把握しておきましょう。

ツール	Gap（弱点）	対処法
Django Migrations	Django以外では使えない	他フレームワークならAlembicを選択
Alembic	初期設定がやや複雑	公式チュートリアルを順番に実行
Flask-Migrate	内部はAlembicなので、複雑な操作はAlembicの知識が必要	基本操作で十分な場合は問題なし

---

7. Pythonの主要マイグレーションツール紹介

7.1 Django Migrations

DjangoというWebフレームワークに標準搭載されているマイグレーション機能です。

特徴

• 追加インストール不要：Djangoをインストールすれば使える
• 自動検知：モデルの変更を自動で検知してマイグレーションファイルを生成
• 初心者にやさしい：シンプルな2コマンドで完結

基本的な使い方

# models.py（モデル定義）
from django.db import models

class User(models.Model):
    name = models.CharField(max_length=100)
    email = models.EmailField()
    # ↓ 新しくカラムを追加したい場合
    phone = models.CharField(max_length=20, blank=True)

# ステップ1：変更を検知してマイグレーションファイルを作成
python manage.py makemigrations

# ステップ2：データベースに反映
python manage.py migrate

便利なコマンド

コマンド	説明
makemigrations	変更を検知してファイル作成
migrate	データベースに反映
showmigrations	適用状況を一覧表示
migrate app_name 0001	特定のバージョンに戻す

7.2 Alembic

SQLAlchemyというデータベース操作ライブラリと組み合わせて使うマイグレーションツールです。

特徴

• フレームワーク非依存：Flask、FastAPI、スクリプト単体でも使える
• 柔軟性が高い：細かいカスタマイズが可能
• SQLAlchemy必須：SQLAlchemyの知識が前提

基本的な使い方

# 初期化（最初に1回だけ）
alembic init alembic

# マイグレーションファイルを自動生成
alembic revision --autogenerate -m "add phone column"

# データベースに反映
alembic upgrade head

便利なコマンド

コマンド	説明
revision --autogenerate	変更を検知してファイル作成
upgrade head	最新状態に更新
downgrade -1	1つ前の状態に戻す
current	現在の適用状況を表示
history	マイグレーション履歴を表示

7.3 Flask-Migrate

FlaskでAlembicを簡単に使えるようにした拡張機能です。

特徴

• Flaskに最適化：Flaskのコマンドラインから操作可能
• 内部はAlembic：Alembicの機能をそのまま利用できる
• セットアップが簡単：Flask-SQLAlchemyと組み合わせて使う

基本的な使い方

# app.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

app = Flask(__name__)
db = SQLAlchemy(app)
migrate = Migrate(app, db)

# 初期化
flask db init

# マイグレーションファイル作成
flask db migrate -m "add phone column"

# データベースに反映
flask db upgrade

便利なコマンド

コマンド	説明
flask db init	初期化（最初に1回）
flask db migrate	変更を検知してファイル作成
flask db upgrade	データベースに反映
flask db downgrade	1つ前に戻す

---

8. マイグレーションの実行フロー全体像

最後に、マイグレーションの全体的な流れをまとめます。

各フェーズのポイント

フェーズ	ポイント
開発	必ずローカル環境で動作確認してからコミット
共有	マイグレーションファイルは必ずGit管理
デプロイ	本番環境では必ずバックアップを取ってから実行
ロールバック	問題があればすぐに戻せる状態にしておく

---

まとめ

マイグレーションとは

データベースの構造（テーブル設計）を、安全に・履歴を残しながら変更する仕組み

なぜ必要か

• 手動SQL管理は履歴管理・チーム共有・復旧が困難
• ツールを使えば「コマンド1つ」で解決

ツールの選び方

状況	推奨ツール
Djangoを使っている	Django Migrations
Flaskを使っている	Flask-Migrate
FastAPIを使っている	Alembic
フレームワークを使わない	Alembic

次のステップ

1. 自分が使うフレームワークを決める
2. 対応するマイグレーションツールの公式チュートリアルを実行
3. 小さなプロジェクトで実際に試してみる

マイグレーションは、最初は「よく分からないコマンド」に見えますが、使いこなせるようになると開発効率が格段に上がります。ぜひ実際に手を動かして試してみてください！

---

参考リンク

• Django公式ドキュメント - Migrations
• Alembic公式ドキュメント
• Flask-Migrate公式ドキュメント