こんにちは、かつコーチです。
前回の記事で、db.create_all()にはテーブル構造の変更を反映できないという弱点を紹介しました。
今回は、その弱点を解消するFlask-Migrateを使って、モデルの変更を安全にデータベースへ反映する方法を解説します。
マイグレーションとは？
データベースの変更履歴を管理する仕組み
マイグレーションとは、データベースのテーブル構造（スキーマ）の変更を、バージョン管理のように記録・適用する仕組みのことです。
「カラムを追加した」「型を変更した」といった変更を1つ1つファイルとして記録し、必要に応じて過去の状態に戻すこともできます。
Gitでコードの変更履歴を管理するように、マイグレーションではデータベースの変更履歴を管理すると考えると分かりやすいです。
なぜdb.create_all()だけでは不十分なのか
前回解説したdb.create_all()は、「まだ存在しないテーブル」を新規作成することしかできません。
すでに存在するテーブルにカラムを追加したり、型を変更したりする操作には対応していないのです。
開発が進むにつれてモデルの変更は避けられないため、実運用のプロジェクトでは必ずマイグレーションの仕組みを導入します。
基本の書き方・実装手順
手順1: Flask-Migrateのインストールと初期設定
pip install flask-migrate
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
app = Flask(__name__)
app.config["SQLALCHEMY_DATABASE_URI"] = "sqlite:///app.db"
db = SQLAlchemy(app)
migrate = Migrate(app, db)
Migrate(app, db)の1行を追加するだけで、マイグレーション機能が使えるようになります。
手順2: マイグレーション環境を初期化する
ターミナルで以下のコマンドを実行します。
flask db init
プロジェクト直下にmigrationsというフォルダが作成されます。
このコマンドは、プロジェクトごとに最初の1回だけ実行します。
手順3: マイグレーションファイルを生成する
モデルを定義（または変更）した後、次のコマンドで変更内容を検出してファイルを生成します。
flask db migrate -m "create task table"
-mのあとのメッセージは、Gitのコミットメッセージのような役割で、後から履歴を見返すときに何を変更したか分かるようにするためのものです。
このコマンドを実行すると、migrations/versions/フォルダの中に、変更内容を反映したPythonファイルが自動生成されます。
手順4: マイグレーションを適用する
生成されたファイルの内容を確認したら、実際にデータベースへ反映します。
flask db upgrade
これで、モデルの変更内容がデータベースのテーブル構造に反映されます。
以降、モデルを変更するたびに「手順3→手順4」を繰り返すのが基本的な開発フローになります。
つまずきやすい設定・注意点
生成されたマイグレーションファイルは必ず確認する
flask db migrateは便利な機能ですが、変更内容を100%正確に検出できるとは限りません。
特に、カラム名の変更（リネーム）は「削除して新規追加」と誤検出されることがあり、既存データが失われる可能性があります。
生成されたmigrations/versions/内のファイルを開き、意図した変更（add_columnやdrop_columnなど）になっているかを確認してからflask db upgradeを実行する習慣をつけましょう。
環境変数FLASK_APPの設定を忘れない
flask db系のコマンドは、Flaskアプリのファイルがどこにあるかを認識する必要があります。
export FLASK_APP=app.py
このコマンドを実行しておかないと、flask db initなどがアプリを見つけられずエラーになることがあります。
よくあるつまずきポイント・エラー対処
Target database is not up to date
❌ Before：他のメンバーが先にflask db migrateでマイグレーションファイルを作成・共有していたのに、自分の環境でflask db upgradeを実行せずに新しい変更でflask db migrateを実行してしまい、Target database is not up to dateというエラーが出る
✅ After：新しい変更を加える前に、必ずflask db upgradeで自分の環境のデータベースを最新の状態に揃えてから、flask db migrateを実行する
私がチーム開発でこのエラーに遭遇したとき、原因は単純に「pullしたけどupgradeを忘れていた」ことでした。
マイグレーションはコードのようにGitで共有されますが、実際のデータベースへの適用は各自の環境で手動実行する必要がある、という点を忘れがちです。
マイグレーションファイルがコンフリクトする
❌ Before：複数人が同時に別々のブランチでflask db migrateを実行し、それぞれのマイグレーションファイルの「親」の指定がずれてしまい、flask db upgrade時にMultiple head revisions are presentというエラーが出る
✅ After：flask db merge heads -m "merge migrations"を実行して、分岐したマイグレーション履歴を1つに統合する
チーム開発でマイグレーションを扱う際は、機能ブランチをマージする前に一度最新のmainブランチのマイグレーションを取り込んでから、自分のマイグレーションを作り直すと、この問題を予防しやすくなります。
応用・一歩先の使い方
ロールバックで変更を1つ前に戻す
マイグレーションを適用した後に問題が見つかった場合、1つ前の状態に戻すこともできます。
flask db downgrade
このコマンドは、直前に適用したマイグレーションを取り消します。
本番環境で使う際は、データが失われる操作（カラム削除など）を巻き戻すと元のデータは復元されない点に注意してください。
マイグレーション履歴を確認する
flask db history
これまでに作成されたマイグレーションの一覧を、適用順に確認できます。
「今、データベースがどのバージョンの状態にあるか」を把握したいときに便利です。
まとめ
この記事のポイント
- Flask-Migrateは、モデルの変更を安全にデータベースへ反映するための仕組み
- 基本フローは「
flask db init（初回のみ）→migrate→upgrade」 - 自動生成されたマイグレーションファイルは、適用前に必ず内容を確認する
- チーム開発では、変更前に
flask db upgradeで環境を最新化してから作業する flask db downgradeで変更を1つ前の状態に戻せる
次に読むべき記事
データベースの管理方法が身についたら、次はユーザー管理の基本であるログイン機能を実装してみましょう。
「Flask-Loginでログイン機能を実装する」で解説しています。
タグ: Flask, 中級者向け, データベース