FastAPI + SQLAlchemy：create_all と Alembic の使い分けと移行手順

お疲れ様です。tkmiです。

FastAPIでDBを扱う際、テーブルの作成方法として create_all と Alembic（マイグレーションツール）の2つがよく登場します。
「最初は create_all で動いていたのに、後から Alembic を導入しようとしてエラーになった」という経験をしたことはないでしょうか。

この記事では、それぞれの役割と使い分け、そして create_all から Alembic へ移行する際のポイントを整理します。

create_all とは？

create_all は SQLAlchemy が提供するメソッドで、定義済みの Model クラスを元にテーブルを自動生成します。

# python
from database import Base, engine

Base.metadata.create_all(bind=engine)

アプリ起動時に呼び出すことで、テーブルが存在しなければ作成されます。

挙動の特徴

カラムの追加・変更・削除を Model に加えても、既存テーブルには一切反映されません。
これが create_all の最大の制約です。 

create_all を使うべき場面

create_all が適しているのは、次のような状況です。

• 個人開発・学習目的のプロジェクト

• 開発初期のプロトタイピング：スキーマがまだ固まっておらず、頻繁に変更する段階

• テスト環境：テスト実行のたびに DB を作り直す場合
  

とにかく「今すぐ動かしたい」「スキーマを気軽に試したい」という場面では create_all は便利な選択肢です。DB を削除してアプリを再起動するだけでテーブルが再作成されるため、移り変わりの速い開発初期に向いています。

Alembic を使うべき場面

Alembic はマイグレーション管理ツールで、スキーマの変更履歴をファイルとして管理し、既存テーブルへの変更を安全に適用できます。

次のような状況になったら Alembic への移行を検討しましょう。

• チーム開発に移行するとき：スキーマ変更を全員に同期する必要がある

• 本番環境にデプロイするとき：既存データを保持したまま変更を適用しなければならない

• カラムの追加・変更・削除が発生するとき：create_all では対応できない

create_all から Alembic への移行手順

「開発初期は create_all で進めていたが、本番リリースが近づいてきたので Alembic を導入したい」というケースはよくあります。ここが落とし穴になりやすいポイントです。

問題：既存テーブルとの衝突

Alembic のマイグレーションを初めて実行しようとすると、create_all で既に作成済みのテーブルが存在するため、次のようなエラーが発生します。

sqlalchemy.exc.OperationalError: (sqlite3.OperationalError) table "users" already exists

Alembic は alembic_version テーブルで「どこまで適用済みか」を管理していますが、初回実行時はこのテーブルが存在しないため「何も適用されていない」と判断し、テーブルを新規作成しようとしてエラーになります。

解決策：alembic stamp head

現在の DB の状態を「全マイグレーション適用済み」として Alembic に認識させます。

# bash
alembic stamp head

これにより alembic_version テーブルが作成され、以降の差分変更から正常に管理できるようになります。

移行の流れ

1. Alembic をインストール・初期設定

pip install alembic
alembic init alembic

2. alembic.ini と env.py を設定

   （DB接続URLと Base の import を設定）

3. 初回マイグレーションファイルを生成

alembic revision --autogenerate -m "initial"

4. 既存 DB に現状を「適用済み」としてマーク

alembic stamp head

5. 以降はスキーマ変更のたびに

alembic revision --autogenerate -m "add column xxx"
alembic upgrade head

データを残したい場合は手順4が必須です。逆に開発環境でデータが不要であれば、DB を一度削除して alembic upgrade head で作り直す方がシンプルです。

まとめ

create_all は「とにかく動かす」ための道具、Alembic は「変化を管理しながら育てる」ための道具です。開発フェーズに合わせて切り替えていくのが実務での自然な流れです。

移行のタイミングで alembic stamp head を知っているかどうかで、詰まる時間が大きく変わります。ぜひ覚えておいてください。