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 モデルがどこにあるかを知りません。
例
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 フィールドを追加する
例
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つのフレームワークのマイグレーションツール比較
| 操作 | Django | Flask(Flask-Migrate) | FastAPI(Alembic) |
|---|---|---|---|
| 初期化 | 不要 | flask db init | alembic init alembic |
| マイグレーションの生成 | makemigrations | flask db migrate -m "説明" | alembic revision --autogenerate -m "説明" |
| マイグレーションの実行 | migrate | flask db upgrade | alembic upgrade head |
| ロールバック | migrate app 0001 | flask db downgrade | alembic downgrade -1 |
| 自動化の度合い | 最高 | 中 | env.py の手動設定が必要 |
本章のまとめ
この章では、Alembic の一連の流れを習得しました:alembic init で初期化、env.py を設定してモデルに接続、revision --autogenerate でマイグレーションを生成、upgrade head で実行、downgrade でロールバック。
Alembic は Django/Flask のマイグレーションツールより設定手順が多いですが、より低レベルで柔軟です。
その他の拡張次章の予告:記事が増えると検索とページネーションが必要になります。次章では、キーワードの複合検索と offset/limit ベースのページネーション機能を実装します。