Flask学習｜Flask-Migrateの導入方法と使用例【チャプター5-08】

一つ前のページではFlask-SQLAlchemyについて学習しました。

今回は Flask-Migrate について見ていきましょう。

FlaskとSQLAlchemyを使ってデータベースアプリケーションを作成していると、一度作ったテーブル構造（スキーマ）を後から変更したくなることがあります。

例えばユーザー情報を保存するテーブルに「電話番号」のカラムを追加したり、カラムの名前を変更したり、削除したくなることがあるでしょう。

こうしたデータベース構造（スキーマ）の変更を安全かつ効率的に管理するための仕組みが「マイグレーション」です。

本記事ではFlaskにおけるマイグレーションの基本と、それを簡単に扱えるようにしてくれるライブラリ Flask-Migrate の使い方について学んでいきます。

<<前のページ

Flaskの記事一覧

次のページ>>

マイグレーションとは？

マイグレーションとは何か？

マイグレーション（migration）とは、日本語で「移行」や「変更」を意味します。

FlaskなどのWebアプリケーションで言うマイグレーションとは、データベースの構造（スキーマ）をバージョン管理し、変更を安全に適用する仕組みを指します。

プログラムのコードはGitなどのバージョン管理ツールで履歴を追うことができますが、データベースの構造は手動で変更していると、「誰が」「いつ」「どのように」変更したのかが分かりにくくなります。

マイグレーションを導入することで、データベースの変更履歴を記録し、コードと同じように変更を管理できるようになるのです。

スキーマとは何か？

スキーマ（schema）とは、簡単に言えば「データベースの設計図」です。
例えば以下のような情報を含みます。

つまりスキーマは「このデータベースにはどんなテーブルがあり、それぞれがどんな形をしているか」を定義するものです。

このスキーマを変更する操作を行うときに、マイグレーションの力が必要になるのです。

Flask-Migrateとは？

Flask-Migrateの特徴と目的

Flask-Migrate は、FlaskとSQLAlchemyの組み合わせで使うためのマイグレーション支援ライブラリです。

マイグレーションそのものは、もともと Alembic（アレンビック） というツールが担当していますが、Alembicを直接使うのはやや難易度が高めです。

Flask-MigrateはこのAlembicをラップして使いやすくしてくれるライブラリで、Flaskのアプリケーション構成に沿って、マイグレーション処理を簡単に行えるようにしてくれます。

Flask-Migrateを使う理由

例えばSQLAlchemyで作ったモデル（User, Postなど）にフィールドを追加・削除した場合、それだけではデータベースの実体には反映されません。

この時にFlask-Migrateを使ってマイグレーションを行うと、モデルの変更内容を自動的に差分検出し、変更をデータベースに適用してくれます。

例：Userモデルにphone_numberカラムを追加 → Flask-Migrateでマイグレーションファイルを生成 → データベースに反映

Flask-MigrateとAlembicの関係性

Flask-Migrateは裏でAlembicを使用しています。

つまりマイグレーション処理自体はAlembicによって行われていますが、Flask-MigrateはそれをFlaskアプリと自然に統合できるように整えてくれる存在です。

実際に作成されるマイグレーションファイルもAlembicの形式そのもので、細かな編集も可能です。

Flask-Migrateのインストール方法と準備手順

必要なパッケージ

Flask-Migrateを使うには、以下の3つのライブラリが必要です：

1. Flask
2. Flask-SQLAlchemy
3. Flask-Migrate

このうち1と2はすでにインストール済みである前提とし、Flask-Migrateを追加でインストールします。

インストールコマンド

仮想環境が有効な状態で、以下のコマンドを実行してください。

pip install Flask-Migrate

これだけで準備は完了です。

インストール後、Flaskアプリに以下のように組み込むことで、マイグレーション機能が利用できるようになります。

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate # Flask-Migrateをインポート

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///example.db' # データベースの接続先を設定（ここではSQLiteファイルを使用）

db = SQLAlchemy(app)       # SQLAlchemyをFlaskアプリに紐づける（データベース操作用の機能を有効化）
migrate = Migrate(app, db) # Flask-MigrateをFlaskアプリとSQLAlchemyに紐づける（マイグレーション機能を有効化）

このコードにより、SQLAlchemyによって定義されたモデルの変更を、Flask-Migrate経由で反映できるようになります。

Flask-Migrateの基本コマンド解説

Flask-Migrateを導入したら、いよいよマイグレーションの操作を行っていきましょう。

この章では基本となる4つのコマンドを紹介し、それぞれが何をするのかを順を追って解説します。

ただし、Flask-Migrateを使うにはそれらのコマンドをコマンドプロンプトやVSCodeのターミナルで実行する必要があります。

VSCode左側のツリーからアプリファイルを保存しているフォルダを右クリックし、「総合ターミナルを開く」を選択してターミナルを表示させましょう。

初期化：flask db init

マイグレーション機能をプロジェクトに初期化します。

このコマンドは、マイグレーションファイルを管理するためのディレクトリ構造を生成します。最初の1回だけ実行すればOKです。

flask db init

これを実行すると、以下のように出力されます（例）。

Creating directory migrations ... done
Creating directory migrations/versions ... done
Generating config file ... done
Generating script.py.mako template ... done
Done

migrations/というフォルダが作成され、その中にマイグレーション履歴を保存するversions/ディレクトリなどが含まれます。

これはGitなどでバージョン管理しておくべき重要なフォルダです。

差分検出：flask db migrate

モデルの変更点を検出し、マイグレーションファイルを生成します。

flask db migrate -m "コメント"

このコマンドは現在のモデルの状態と、前回マイグレーションした状態を比較し、差分を自動で検出してマイグレーションファイル（変更履歴）をmigrations/versions/に生成します。

• モデルに変更を加えてからこのコマンドを実行することで、その変更に対応するマイグレーションファイルが作成されます。
• -mオプションの後には、変更の内容が分かるようなコメントをつけると良い習慣です。

適用：flask db upgrade

マイグレーションを実行し、最新の状態にデータベースを更新します。

flask db upgrade

このコマンドを実行することで、migrateで生成された変更内容が実際のデータベースに適用されます。

つまり、モデルと実データベースの構造が一致するようになります。

巻き戻し：flask db downgrade

マイグレーションを巻き戻します（前の状態に戻す）。

flask db downgrade

万が一マイグレーションで誤った変更を加えてしまった場合、このコマンドで一つ前の状態に戻すことができます。

これにより、データベースの変更にも「やり直し」が効くようになるのです。

マイグレーション操作時の注意事項

• migrateだけではデータベースは変更されません → upgradeが必要です。
• 逆にupgradeをいきなり実行しても、マイグレーションファイルが無ければ何も起きません。
• downgradeを使うときは、現在のスキーマがどこまで巻き戻るのかに注意して慎重に行いましょう。

Flask-Migrateの使用例と具体的なコード解説

ここでは実際にFlaskアプリケーションを作りながら、Flask-Migrateを用いたマイグレーションの流れを具体的に見ていきます。

初心者の方でも手順を追いやすいよう、コメントを豊富に入れたコードと合わせて説明します。

初期モデルの作成とマイグレーション

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate # Flask-Migrateをインポート

# Flaskアプリの初期化
app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///example.db' # データベースの接続先を設定（ここではSQLiteファイルを使用）

# DBとマイグレーションの初期化
db = SQLAlchemy(app)       # SQLAlchemyをFlaskアプリに紐づける（データベース操作用の機能を有効化）
migrate = Migrate(app, db) # Flask-MigrateをFlaskアプリとSQLAlchemyに紐づける（マイグレーション機能を有効化）

# モデル定義（最初の状態）
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)     # 主キー
    name = db.Column(db.String(64), nullable=False)  # ユーザー名

手順

1. 仮想環境を有効にする（必要に応じて）
2. 初期化コマンドを実行：flask db init
3. 初回マイグレーションファイルの作成：flask db migrate -m “Initial migration”
4. 実データベースへ適用：flask db upgrade

この時点で、SQLiteファイル（例：example.db）にUserテーブルが作成されます。

モデル修正後のマイグレーション手順

次に、Userモデルにemailカラムを追加してみます。

修正後のUserモデル：

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(64), nullable=False)
    email = db.Column(db.String(120), unique=True)  # 追加されたemailカラム

手順

1. モデル修正後、差分検出とマイグレーションファイル作成：flask db migrate -m “Add email column to User”
2. データベースの更新：flask db upgrade

この2ステップにより、データベースにもemailカラムが追加され、アプリのコードとデータベース構造が一致した状態になります。

マイグレーション変更の取り消し手順

直前の変更を取り消すには以下のコマンドを使います：

flask db downgrade

これにより、emailカラムが削除され、以前の状態に戻ります。これがマイグレーションの巻き戻し機能です。

まとめ

この章では、FlaskとSQLAlchemyを使ったWebアプリケーション開発において、データベースの構造変更（スキーマ変更）を安全に管理するための仕組み＝マイグレーションについて学びました。

初めは「マイグレーション」という言葉に難しさを感じたかもしれませんが、一つひとつの操作を覚えれば、データベースを手動で変更するよりもはるかに安全かつ効率的に開発を進めることができます。

Flask-Migrateを活用することで、将来的に複数人での開発や本番環境への反映も、確実で再現性のある方法で行えるようになります。

ぜひ、今のうちにしっかりと基礎を身につけておきましょう。

この知識が、あなたのFlaskアプリ開発を一歩先へ進めてくれることを願っています！

<<前のページ

Flaskの記事一覧

次のページ>>

FAQ｜Flask-Migrateの導入と操作に関するよくある質問