データベースマイグレーションとは、テーブルや列などの構造変更をファイルに記録し、同じ変更を開発環境や本番環境へ順番に適用できるようにする仕組みです。
FastAPIでSQLAlchemyのモデルを使う場合は、Alembicを組み合わせると変更履歴を管理できます。
Laravelのマイグレーションはフレームワークに組み込まれていますが、FastAPIとAlembicは別々の道具です。
そのため、FastAPIでは接続先とモデル情報をAlembicへ明示し、生成された変更内容を確認してから適用する流れを理解しておく必要があります。
FastAPI、SQLAlchemy、Alembicの役割
Alembicは、SQLAlchemyで扱うデータベース構造の変更をリビジョンファイルとして記録し、適用や巻き戻しを行うためのツールです。
ここでいうリビジョンは、ある時点の変更内容と前後関係を表すバージョン単位を指します。
- FastAPI：Web APIの入口や処理を実装する
- SQLAlchemy：Pythonのモデルとデータベースを対応づける
- Alembic：データベース構造の変更履歴を作成し、適用する
基本的な流れは、SQLAlchemyのモデルを変更し、その差分をもとにリビジョンを作り、内容を確認してからデータベースへ適用するという順序です。
差分からの生成は作業の出発点であり、生成結果の確認や必要な手直しまで省けるという意味ではありません。
Alembicの導入手順
1．Alembicをインストールする
pip install alembicFastAPIのプロジェクトで使っているPython環境にAlembicを追加します。
2．設定ファイルを作成する
alembic init alembic初期化すると、プロジェクトにalembic/ディレクトリとalembic.iniが作成されます。
リビジョンファイルは、通常このディレクトリ内のversions/で管理します。
3．接続先とモデル情報を設定する
alembic.iniには、Alembicが接続するデータベースのURLを設定します。
次の記述は、PostgreSQLへ接続する形式の例です。
sqlalchemy.url = postgresql+asyncpg://user:password@localhost:5432/dbname非同期ドライバーを使う場合は、env.py側にも接続方式に合った設定が必要です。
同期接続の設定を前提としたままURLだけを置き換えるのではなく、プロジェクトのSQLAlchemy構成とそろえてください。
次に、alembic/env.pyからモデルのBase.metadataを参照し、target_metadataへ渡します。
from myapp.models import Base
target_metadata = Base.metadatatarget_metadataを設定すると、Alembicはモデルが表す構造とデータベースの状態を比較し、リビジョンの候補を組み立てられます。
4．リビジョン候補を生成する
alembic revision --autogenerate -m "create users table"--autogenerateは差分を検出し、変更用スクリプトの候補を作成します。
作成後は、意図したテーブルや列だけが対象になっているか、適用処理と巻き戻し処理が対応しているかを確認します。
5．変更を適用する
alembic upgrade headheadは、現在のリビジョン系列の先頭を表します。
このコマンドは、未適用の変更を先頭まで順に反映します。
6．直前の変更を巻き戻す
alembic downgrade -1-1は、一つ前のリビジョンへ戻す指定です。
Alembicでは戻り先を指定して実行するため、どの変更を取り消すのかを確認してから操作します。
AlembicとLaravelマイグレーションの違い
両者はどちらも変更履歴をコードとして残しますが、フレームワークとの結びつきと変更ファイルの作り方が異なります。
| 比較項目 | AlembicとFastAPI | Laravel |
|---|---|---|
| 位置づけ | Alembicを別途導入し、FastAPIのプロジェクトに合わせて設定する | マイグレーション機能がフレームワークに組み込まれている |
| 変更ファイル | SQLAlchemyのモデルとの差分から候補を生成し、必要に応じてPythonで編集する | マイグレーションファイルに変更内容を記述する |
| 適用 | alembic upgrade headなどで対象リビジョンまで進める |
マイグレーション用コマンドで未適用の変更を進める |
| 巻き戻し | downgradeで戻り先を指定する |
rollbackやresetを利用できる |
| 保存場所 | alembic/versions/でリビジョンを管理する |
database/migrations/で管理する |
| 周辺機能 | モデル、マイグレーション、テスト用データなどの構成を個別に決める | モデル、ファクトリ、シーダーを同じフレームワーク内で扱える |
Laravelに慣れている場合、Alembicの初期設定は手数が多く見えます。
一方で、Alembicはリビジョンの適用先を明示し、必要な変更処理をPythonで調整できるため、SQLAlchemyの構成に合わせて管理しやすい点が特徴です。
Laravel側のマイグレーション、シーディング、Factoryの関係は、Laravelのマイグレーションと初期データ設計の解説で確認できます。
Alembicを使う利点と注意点
利点
- SQLAlchemyのモデル情報をリビジョン作成の起点にできる
- 生成した内容をPythonで調整できる
- 変更履歴をファイルとして共有し、チームで同じ順序にそろえられる
upgradeとdowngradeで適用先を指定できる
注意点
- 接続先と
target_metadataをプロジェクトに合わせて設定する必要がある - 非同期接続を使う場合は、ドライバーだけでなく
env.pyの構成も確認する - 生成されたリビジョンをそのまま確定せず、変更内容を確認する
- ファイル名、変更単位、適用順序についてチーム内のルールをそろえる
データ移行、テスト、継続的インテグレーションまで含めた運用は、FastAPI、SQLAlchemy、AlembicによるDBマイグレーション運用で詳しく扱っています。
導入時に確認する項目
- 接続URLが対象のデータベースとドライバーに合っているか
target_metadataが使用中のモデルを参照しているか- 生成された適用処理と巻き戻し処理が意図どおりか
- リビジョンファイルをチームで共有できる状態になっているか
- 変更ファイルの命名と粒度に共通ルールがあるか
FastAPIでAlembicを使うときは、モデル変更、リビジョン作成、内容確認、適用という流れを分けて考えると管理しやすくなります。
Laravelとの違いは優劣ではなく、統合された機能を使うか、SQLAlchemyの構成に合わせて個別に組み立てるかという設計上の違いです。