先生と生徒の会話形式で理解しよう

生徒

「先生、Flaskでデータベースの変更を管理する方法ってありますか？」

先生

「あるよ。Flask-Migrateというツールを使えば、データベースの構造変更を自動で管理できるんだ。」

生徒

「それって難しくないですか？初心者でも使えますか？」

先生

「大丈夫！丁寧に説明するから、一緒にFlask-Migrateの基本からマイグレーションファイルの作成、適用まで見ていこう。」

1. Flask-Migrateとは？マイグレーションって何？

Flask-Migrateとは、FlaskとSQLAlchemyを使うときに、データベースの構造変更を安全かつ自動的に管理してくれる便利な拡張機能です。アプリを作っていると「カラムを追加したい」「テーブル名を変えたい」など、あとから設計を変更したくなる場面が必ず出てきます。こうした変更を毎回手作業でSQLを書いて行うのは大変で、ミスも起こりやすくなります。

そこで役に立つのがマイグレーション（migration）という仕組みです。マイグレーションとは、簡単に言えば「データベースの設計図を更新していく作業」のこと。プログラムのモデル（設計図）が変わったとき、その変更をデータベース側に反映させるための手順を管理する技術です。

たとえば、ユーザー情報を保存するテーブルに、あとから「メールアドレス」や「登録日時」を追加したいとしましょう。このような変更を加える場合、Flask-Migrateを使えば、自動で変更内容をまとめたファイルを作り、データベースに適用できます。面倒なSQLを書かなくてもよいので、初心者でも安心して扱えます。

実際にどのように設計図（モデル）がマイグレーションに変わるのか、イメージしやすいようにごく簡単なモデル例を紹介します。


# これは「ユーザー」テーブルのシンプルな設計図（モデル）です
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(64))

このようにPythonコードで書いたモデルをもとに、Flask-Migrateが「データベースにどんなテーブルを作ればいいか」を判断し、必要なマイグレーションファイルを生成してくれます。プログラムの変更がそのまま設計変更につながるため、管理がとても楽になるのです。

2. Flask-Migrateを使う準備

Flask-Migrateを使い始めるためには、まず必要なライブラリをインストールし、Flaskアプリに設定していく準備が必要です。難しく見えるかもしれませんが、実際はとてもシンプルで、初心者でも落ちついて進めれば問題ありません。ここでは「なぜその設定が必要なのか」もふまえて、順番にわかりやすく説明します。

まずはFlask-Migrateをインストールします。パッケージ管理ツール pip を使い、次のコマンドを実行しましょう。


pip install Flask-Migrate

次にアプリケーション側の設定です。Flask-Migrateは SQLAlchemy と一緒に動きます。そのため、Flaskアプリに「データベースをどう扱うのか」を知らせる設定と、Migrate をアプリ・データベースに紐づける処理が必要になります。以下はその最小構成の例です。


from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

app = Flask(__name__)

# どのデータベースを使うか指定（今回は初心者にやさしい SQLite）
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///sample.db'

# データベース操作のための仕組みを用意
db = SQLAlchemy(app)

# Flask と SQLAlchemy をマイグレーション機能に接続する
migrate = Migrate(app, db)

このコードがあることで、Flask-Migrate は「アプリのモデルを読み取り、変更点を検出してファイルを作成する」準備が整います。特に SQLite はファイルだけで動くデータベースなので、初心者でも扱いやすく、マイグレーションの練習にも最適です。まずはこの基本設定が正しく書けることが第一歩となります。

3. マイグレーション環境を初期化しよう

Flask-Migrateを使うための準備ができたら、次は「マイグレーション環境」を作成していきます。これは、データベースの変更履歴を保存したり、Flask-Migrateが管理に必要とする設定ファイルを配置したりするための大事なステップです。初期化といっても特別な作業ではなく、1つのコマンドを実行するだけで自動的にフォルダ構造が整います。

まずはコマンドプロンプト（またはターミナル）を開き、Flaskアプリがあるフォルダに移動して次のコマンドを入力します。


flask db init

このコマンドを実行すると、migrationsというフォルダが新しく作成されます。このフォルダには、後ほど生成されるマイグレーションファイルや、Flask-Migrateが動くために必要な設定ファイルがまとめて管理されます。

初心者の方はこの段階で「何か難しいことが起きているのでは？」と思うかもしれませんが、実際には“マイグレーション専用の作業スペースをつくっただけ”と考えるとイメージしやすくなります。ここで初期化をしておくことで、後のマイグレーション作成や反映がスムーズに行えるようになります。

この作業はプロジェクトで最初の1回だけ行えば大丈夫です。次のステップから、いよいよデータベースの設計をマイグレーションとして反映していく準備が整います。

4. モデルを定義しよう（データベースの設計図）

Flaskでデータベースを扱う際、中心となるのがモデル（model）と呼ばれる“設計図”です。モデルを定義することで、「どんな情報を保存するのか」「どんな種類のデータか」といった内容をアプリに伝えることができます。これは家を建てる前に図面を用意するのと同じで、データベースを正しく作るうえで欠かせない作業です。

まずは、もっともシンプルなユーザーテーブルの例を見てみましょう。


# Userモデルは「ユーザー情報を保存する箱」をイメージするとわかりやすいです
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)  # ユーザーを識別する番号
    name = db.Column(db.String(64))               # 名前を保存するカラム

このモデルを定義すると、データベースには「User」という名前のテーブルが作られ、その中に ID と名前を保存するための2つのカラムが用意されます。特に primary_key=True は「この値で1人のユーザーを区別する」という意味で、とても重要な設定です。

初心者の方は「クラスを書いただけで本当にテーブルができるの？」と驚くかもしれませんが、SQLAlchemy がこのモデルを読み取ってデータベースに反映する仕組みを作ってくれるため、複雑なSQLを書く必要はありません。まずはモデル＝テーブルの設計図、と理解して慣れていくとスムーズです。

5. マイグレーションファイルを作成する

モデルを定義したら、次にflask db migrateコマンドを使って、マイグレーションファイルを自動で作成します。


flask db migrate -m "create user table"

-mのあとに書いたメッセージは、変更内容のメモのようなものです。

このコマンドにより、migrations/versionsフォルダに「〇〇_create_user_table.py」というファイルが作られます。

6. マイグレーションをデータベースに適用しよう

最後に、マイグレーションファイルを実際のデータベースに適用します。このとき使うコマンドがこちらです。


flask db upgrade

このコマンドを実行すると、定義したモデル通りにデータベースが作られたり変更されたりします。

7. カラムを追加・変更したいときも同じ手順

たとえば、Userモデルに「email」というカラムを追加したくなった場合、まずはモデルに以下のように行を追加します。


class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(64))
    email = db.Column(db.String(120))  # ← 追加！

その後、以下の手順をもう一度実行するだけでOKです。

flask db migrate -m "add email to user"
flask db upgrade

このように、Flask-Migrateを使えば、既存のデータを消さずに安全に変更が反映できるのです。

8. マイグレーションファイルを使うと何が便利？

マイグレーションファイルを使うと、次のようなメリットがあります：

人間が手作業でSQLを書く必要がない（自動化されて安心）
どんな変更をしたのか記録が残る（履歴管理ができる）
複数人で開発するときにトラブルが減る（みんな同じ設計図になる）

つまり、Flask-Migrateを使うことで、効率的で安全なデータベース運用ができるようになります。

9. SQLiteを使った初心者向け実行結果の例

ここでは、実際にflask db upgradeを実行したときの出力例を紹介します。


    INFO  [alembic.runtime.migration] Running upgrade -> 1a2b3c4d, create user table

このようなメッセージが表示されれば、マイグレーションの適用に成功したということです。

10. よくあるエラーとその対処法

「Can't locate revision identified by ...」というエラーは、マイグレーションファイルが足りない、または削除されたときに起こります。

この場合は、migrations/versionsフォルダを見て、ファイルが存在するか確認してください。

また、環境を一度リセットしてやり直す場合は、SQLiteのsample.dbを削除し、マイグレーションを初期化してやり直します。

まとめ

Flaskでアプリケーションを開発するとき、画面づくりやルーティングといった目に見える部分に注目しがちですが、実際に長く運用していくためにはデータベースの変更を安全かつ確実に管理する仕組みが欠かせません。とくに複数人で開発を進める場合や、あとから機能を追加したい場面では、設計図にあたるモデルを更新し、その変更をそのまま反映できる柔軟な環境が必要になります。こうした場面で役立つのが、今回学んだFlask-Migrateという仕組みです。これはFlaskとSQLAlchemyを組み合わせて使うことにより、複雑なデータベースの変更も自動的に追跡しながら履歴を残してくれるため、初心者でも扱いやすく、安心して更新作業を任せることができます。さらに、アプリケーションの規模が大きくなっても、データの構造を崩さずに管理できる点が大きな強みです。まず、Flask-Migrateを利用するための準備として、パッケージをインストールし、アプリケーション内でSQLAlchemyと連動させる設定が必要でした。環境構築を済ませたあとは、最初のマイグレーション環境を初期化し、必要なフォルダや設定ファイルを自動生成させることで、今後の変更を順序よく積み重ねられる土台が整います。それから、モデルを定義することで、データベースの構造をPythonのクラスとして表現できるようになり、アプリの成長に合わせた柔軟な変更が可能になります。たとえばユーザー情報を管理するテーブルに名前やメールアドレスを追加する場合でも、モデルに一行追加してマイグレーションを作成するだけで変更が反映されるため、煩雑なSQL文を書かずに安全な更新が行える点は大きな利点です。また、変更内容を反映する作業も、毎回同じ手順で実行できるため迷いがなく、どの環境でも同じ結果を得られる統一性があります。実際にマイグレーションファイルを生成する流れや、アップグレードによって実際のデータベースに反映する動きも確認しながら進めることで、しくみを理解しやすくなります。とくに、既存のデータを保持したまま構造だけ安全に変えられる点は、実務でも欠かせない重要な仕組みです。初心者にとっても、変化の履歴がファイルとして残るため、あとから確認しやすく、どこでどんな変更が行われたのかが視覚的に理解できます。これは開発途中で起きがちな「どのバージョンが正しいのか分からない」といった混乱を防いでくれる効果もあります。さらに、アプリケーションを改良するなかで起こりやすいトラブルについても触れました。たとえば、特定のリビジョンを見つけられないエラーや、古いマイグレーションファイルが残ってしまう問題など、よくあるつまずきにも正しく対処できれば、安心して開発が進められます。こうした知識は、一度理解してしまえばどのプロジェクトでも活かすことができ、データベースを伴うWebアプリケーションの開発における基礎的な技術となっていきます。最後に、今回の学びを簡単なサンプルコードでも確認しておきましょう。モデルに新しいカラムを追加し、マイグレーションを自動生成して適用するまでの流れは次のようになります。

サンプルコード


# モデルにカラムを追加
class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(64))
    email = db.Column(db.String(120))  # 新しいカラム

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

# マイグレーションを反映
# flask db upgrade

このように、コマンドを実行するだけで必要な変更を自動で作成し、データベースへ適用できます。アプリの成長に応じてモデルを拡張しながら、整合性を保った状態で運用していける点はとても魅力的です。実際の開発現場でも広く使われている仕組みであり、覚えておくことで作業の効率も格段に向上します。初心者でも扱いやすく、少しずつ理解を積み重ねながら取り組んでいけるため、これから本格的にWebアプリを作っていきたい人にとって大きな助けになるでしょう。

先生と生徒の振り返り会話

生徒

「今日の学びで、一番驚いたのはデータベースの変更を自動で管理できることでした。てっきり自分で全部書かないといけないと思っていました。」

先生

「そう感じる人は多いよ。最初は難しそうに見えるけれど、実際に触ってみると流れが決まっていて扱いやすいでしょう。」

生徒

「はい。モデルを変えたあとにマイグレーションを作ってアップグレードするだけなので、思ったより迷わず進められました。」

先生

「その感覚が大事なんだ。変更を安全に管理する仕組みを持つことで、アプリを成長させても破綻しにくくなる。実務でも必ず役に立つ知識だよ。」

生徒

「これなら新しいカラムを追加するのも怖くないです。間違えて全部壊してしまう心配が少ない感じがして安心できます。」

先生