Flask-Migrate — データベースマイグレーション

この章では、Flask-Migrate を使ってデータベース構造の変更を安全に管理し、Django migration との対応関係を理解します。


なぜずっと db.create_all() を使ってはいけないのか?

db.create_all()致命的な欠陥が2つあります:

  • テーブルが存在しないときだけ作成する。モデルを変更(フィールド追加など)しても、既存のテーブルは更新されない
  • 変更履歴が残らない。以前のデータベース状態にロールバックできない

データベースマイグレーションデータベースにとっての Git のようなものです。構造が変わるたびにバージョンファイルを生成し、アップグレードとロールバックをサポートします。

Flask-MigrateAlembic の Flask 拡張で、SQLAlchemy 専用に設計されています。


インストールと設定

(venv) $ pip install flask-migrate

例

# ファイルパス:app.py
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///blog.db'

db = SQLAlchemy(app)
migrate = Migrate(app, db)    # app と db を Migrate にバインドします

マイグレーション3ステップ

手順コマンド役割Django に対応
初期化flask db initmigrations/ ディレクトリを作成(一度だけ実行)—
生成flask db migrate -m "説明"モデルの変更を検出し、マイグレーションスクリプトを生成makemigrations
実行flask db upgradeマイグレーションスクリプトをデータベースに適用migrate

ステップ1:マイグレーションディレクトリを初期化

(venv) $ flask db init
Creating directory migrations/...  done

実行後に生成されるmigrations/ディレクトリ(Git の .git ディレクトリに類似)。一度だけ実行するだけでよい。

ステップ2:マイグレーションファイルを生成

(venv) $ flask db migrate -m "初始化 Post 和 Category 模型"
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
Generating migrations/versions/xxxx_initial.py ... done

まだモデル変更がない場合でも、既存のモデルに対してこのコマンドを実行するだけでOKです。

ステップ3:マイグレーションを実行

(venv) $ flask db upgrade
INFO  [alembic.runtime.migration] Running upgrade  -> xxxx, 初始化

実践:Post モデルにフィールドを追加

製品要件の変更により、記事に読書回数を追加する必要があるとします。

例

# ファイルパス:models.py の Post クラスに追加
class Post(db.Model):
    # ... 既存フィールド ...
    read_count = db.Column(db.Integer, default=0)  # 追加:読書回数

モデルを変更したら、マイグレーションを実行:

(venv) $ flask db migrate -m "Post 模型新增 read_count 字段"
(venv) $ flask db upgrade

これでデータベースのpostsテーブルに自動的にread_count列が追加され、既存データは影響を受けません。

マイグレーション履歴を確認

現在のデータベースがどのバージョンかを確認:

(venv) $ flask db current

すべてのマイグレーション履歴を確認:

(venv) $ flask db history

マイグレーションをロールバック

マイグレーションは取り消し可能です:

(venv) $ flask db downgrade   # 回退到上一个版本

これによりread_count列が削除され、前回のマイグレーションのすべての変更が取り消されます。

すべての操作が自動ロールバックできるわけではありません(SQLite での列の削除など)。ロールバック前に確認してください。flask db current現在のバージョンを確認し、何をロールバックするのかを理解してください。本番環境ではロールバック前に必ずデータをバックアップしてください。


Flask-Migrate vs Django Migration 対照

操作Flask(Flask-Migrate)Django
初期化flask db init不要(プロジェクトに migrations ディレクトリが同梱)
マイグレーション生成flask db migrate -m "説明"python manage.py makemigrations
マイグレーション実行flask db upgradepython manage.py migrate
ロールバックflask db downgradepython manage.py migrate app 0001
履歴確認flask db historypython manage.py showmigrations
自動化の度合い初期化が必要、検出は Alembic に依存全自動、追加設定不要

Django のマイグレーションシステムはより自動化・統合されています。Flask も Flask-Migrate を通じて同等レベルの機能を実現しています。


本章のまとめ

この章では Flask-Migrate の完全な流れを学びました:flask db init で初期化、flask db migrate でマイグレーションスクリプト生成、flask db upgrade でマイグレーション実行、flask db downgrade でロールバックです。

今後 models.py を変更するたびにこの3ステップの流れを行えば、データベース構造の変更は常に履歴として追跡できます。

その他の拡張