サイトアイコン IT & ライフハックブログ｜学びと実践のためのアイデア集

FastAPIでAlembicを使う方法：DBマイグレーション手順とLaravelとの違い

greeden
close up photo of mining rig

Photo by panumas nikhomkhai on Pexels.com

データベースマイグレーションとは、テーブルや列などの構造変更をファイルに記録し、同じ変更を開発環境や本番環境へ順番に適用できるようにする仕組みです。
FastAPIでSQLAlchemyのモデルを使う場合は、Alembicを組み合わせると変更履歴を管理できます。

Laravelのマイグレーションはフレームワークに組み込まれていますが、FastAPIとAlembicは別々の道具です。
そのため、FastAPIでは接続先とモデル情報をAlembicへ明示し、生成された変更内容を確認してから適用する流れを理解しておく必要があります。

FastAPI、SQLAlchemy、Alembicの役割

Alembicは、SQLAlchemyで扱うデータベース構造の変更をリビジョンファイルとして記録し、適用や巻き戻しを行うためのツールです。
ここでいうリビジョンは、ある時点の変更内容と前後関係を表すバージョン単位を指します。

基本的な流れは、SQLAlchemyのモデルを変更し、その差分をもとにリビジョンを作り、内容を確認してからデータベースへ適用するという順序です。
差分からの生成は作業の出発点であり、生成結果の確認や必要な手直しまで省けるという意味ではありません。

Alembicの導入手順

1．Alembicをインストールする

pip install alembic

FastAPIのプロジェクトで使っている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.metadata

target_metadataを設定すると、Alembicはモデルが表す構造とデータベースの状態を比較し、リビジョンの候補を組み立てられます。

4．リビジョン候補を生成する

alembic revision --autogenerate -m "create users table"

--autogenerateは差分を検出し、変更用スクリプトの候補を作成します。
作成後は、意図したテーブルや列だけが対象になっているか、適用処理と巻き戻し処理が対応しているかを確認します。

5．変更を適用する

alembic upgrade head

headは、現在のリビジョン系列の先頭を表します。
このコマンドは、未適用の変更を先頭まで順に反映します。

6．直前の変更を巻き戻す

alembic downgrade -1

-1は、一つ前のリビジョンへ戻す指定です。
Alembicでは戻り先を指定して実行するため、どの変更を取り消すのかを確認してから操作します。

AlembicとLaravelマイグレーションの違い

両者はどちらも変更履歴をコードとして残しますが、フレームワークとの結びつきと変更ファイルの作り方が異なります。

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を使う利点と注意点

利点

注意点

データ移行、テスト、継続的インテグレーションまで含めた運用は、FastAPI、SQLAlchemy、AlembicによるDBマイグレーション運用で詳しく扱っています。

導入時に確認する項目

FastAPIでAlembicを使うときは、モデル変更、リビジョン作成、内容確認、適用という流れを分けて考えると管理しやすくなります。
Laravelとの違いは優劣ではなく、統合された機能を使うか、SQLAlchemyの構成に合わせて個別に組み立てるかという設計上の違いです。

モバイルバージョンを終了