Alembic データベースマイグレーション

この章では、Alembic を使ってデータベース構造の変更を管理する方法を学び、Django Migration や Flask-Migrate との違いや共通点を理解します。


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

Base.metadata.create_all()同様に重大な欠陥があります:テーブルが存在しない場合にのみ作成され、既存のテーブル構造を変更しても自動的に同期されません。

AlembicSQLAlchemy 公式のマイグレーションツールであり、Django のmakemigrations/migrateと Flask の Flask-Migrate は、基盤となる設計が Alembic を参考にしています。


インストールと初期化

(venv) $ pip install alembic
(venv) $ alembic init alembic
Creating directory alembic/... done

生成されるディレクトリ構造:

alembic/
├── versions/          # 迁移脚本存放目录
├── env.py             # 迁移环境配置(需手动修改!)
└── script.py.mako     # 迁移脚本模板
alembic.ini            # Alembic 配置文件

env.py を設定してモデルに接続する

これが重要なステップです——Alembic はデフォルトでは、あなたの SQLAlchemy モデルがどこにあるかを知りません。

例

# ファイルパス:alembic/env.py(重要な部分を変更)
import sys
from pathlib import Path

# プロジェクトのルートディレクトリを sys.path に追加(自分のモジュールをインポートできるようにする)
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

from database import Base, engine
from models import Category, Post   # すべてのモデルをインポートし、Base.metadata にそれらが含まれるようにする

# target_metadata はモデルのメタデータに設定する必要がある
target_metadata = Base.metadata

同時に修正するalembic.iniのデータベース接続:

# 文件路径:alembic.ini
sqlalchemy.url = sqlite:///./blog.db

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

ステップコマンド説明Django との対応
初期化alembic init alembicマイグレーション環境を作成(一度だけ)—
生成alembic revision --autogenerate -m "説明"モデルの変更を検出し、マイグレーションスクリプトを生成makemigrations
実行alembic upgrade head未適用のマイグレーションをすべて実行migrate

マイグレーションの生成と実行

(venv) $ alembic revision --autogenerate -m "初始化 Post 和 Category 模型"
INFO  [alembic.autogenerate] Detected added table 'categories'
INFO  [alembic.autogenerate] Detected added table 'posts'
Generating alembic/versions/xxxx_initial.py ... done

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

実践:read_count フィールドを追加する

例

# ファイルパス:models.py の Post クラスに追加
class Post(Base):
    # ... 既存のフィールド ...
    read_count = Column(Integer, default=0)   # 閲覧回数
(venv) $ alembic revision --autogenerate -m "Post 新增 read_count 字段"
(venv) $ alembic upgrade head

ロールバック

(venv) $ alembic downgrade -1        # 回退到上一个版本

alembic upgrade headのheadは最新バージョンを表します。具体的なバージョン番号を指定することもできます:alembic upgrade xxxx(バージョン ID)。


3つのフレームワークのマイグレーションツール比較

操作DjangoFlask(Flask-Migrate)FastAPI(Alembic)
初期化不要flask db initalembic init alembic
マイグレーションの生成makemigrationsflask db migrate -m "説明"alembic revision --autogenerate -m "説明"
マイグレーションの実行migrateflask db upgradealembic upgrade head
ロールバックmigrate app 0001flask db downgradealembic downgrade -1
自動化の度合い最高中env.py の手動設定が必要

本章のまとめ

この章では、Alembic の一連の流れを習得しました:alembic init で初期化、env.py を設定してモデルに接続、revision --autogenerate でマイグレーションを生成、upgrade head で実行、downgrade でロールバック。

Alembic は Django/Flask のマイグレーションツールより設定手順が多いですが、より低レベルで柔軟です。

次章の予告:記事が増えると検索とページネーションが必要になります。次章では、キーワードの複合検索と offset/limit ベースのページネーション機能を実装します。

その他の拡張