Alembic は、SQLAlchemy を用いるプロジェクトにおいて、データベーススキーマのバージョン管理およびマイグレーションを実施するための軽量なツールです。
データベースの変更履歴を管理し、スキーマ変更の適用やロールバックを容易に行うことが可能となります。

基本的な導入手順

1. インストール

まず、プロジェクトに Alembic を追加します。

pip install alembic

2. 初期化

Alembic をプロジェクトに組み込むため、以下のコマンドで初期設定ファイル群を生成します。

alembic init alembic

これにより、プロジェクトルートに alembic.ini と、alembic/ ディレクトリ（env.py、script.py.mako、および versions/）が作成されます。

3. alembic.ini の設定

alembic.ini 内の sqlalchemy.url に、対象となるデータベース接続用の URL を設定します。
例：

[alembic]
sqlalchemy.url = postgresql://user:password@localhost/dbname

4. env.py の設定

env.py は、Alembic が実際にマイグレーションを実行する際の環境設定スクリプトです。
主なポイントは以下の通りです。

• モデルのインポート:
  プロジェクト内の SQLAlchemy モデルの定義が Base.metadata に登録されるように設定します。
  例えば、models/base.py に Base を定義し、各モデル（例：setting_group.py）を models/__init__.py でインポートすることで、全モデルが正しく反映されます。
• データベース接続:
  alembic.ini に記載された sqlalchemy.url を取得し、データベースエンジンを生成します。
• オンライン・オフラインモード:
  env.py 内で、オンラインモード（実際にデータベースへ接続してマイグレーション実行）とオフラインモード（SQL スクリプト生成）の処理を定義しています。

下記は、基本的な env.py の例です。

from logging.config import fileConfig
from sqlalchemy import create_engine, pool
from alembic import context
import sys, os

# プロジェクトのルートディレクトリを検索パスに追加
sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))

# モデルのインポート（必ず全モデルをインポートしておく）
from models.base import Base
# 例: models/__init__.py 内で from . import setting_group としていること

config = context.config
DATABASE_URL = config.get_main_option("sqlalchemy.url")
if not DATABASE_URL:
    raise ValueError("alembic.ini の 'sqlalchemy.url' が設定されていません。")

if config.config_file_name is not None:
    fileConfig(config.config_file_name)

# ターゲットメタデータの設定
target_metadata = Base.metadata

def run_migrations_offline() -> None:
    context.configure(
        url=DATABASE_URL,
        target_metadata=target_metadata,
        literal_binds=True,
        dialect_opts={"paramstyle": "named"},
    )
    with context.begin_transaction():
        context.run_migrations()

def run_migrations_online() -> None:
    connectable = create_engine(DATABASE_URL, poolclass=pool.NullPool)
    with connectable.connect() as connection:
        context.configure(connection=connection, target_metadata=target_metadata)
        with context.begin_transaction():
            context.run_migrations()

if context.is_offline_mode():
    run_migrations_offline()
else:
    run_migrations_online()

マイグレーションファイルの生成と適用

1. マイグレーションファイルの生成

モデルに変更（新規作成、カラム追加・削除など）を加えた場合、以下のコマンドでマイグレーションファイルを自動生成します。

alembic revision --autogenerate -m "変更内容のコメント"

※ --autogenerate オプションは、target_metadata に基づき、データベースとのスキーマ差分を検出してマイグレーションファイルに反映します。

2. マイグレーションの適用

生成したマイグレーションファイルをデータベースに反映するには、以下のコマンドを使用します。

alembic upgrade head

head は最新のマイグレーションリビジョンを意味します。
また、誤った変更を取り消す場合は以下のようにロールバックが可能です。

alembic downgrade -1

便利な Alembic コマンドおよびオプション

Alembic には、マイグレーションの状態確認や管理に役立つコマンドが多数用意されています。

1. alembic history --verbose

• 概要:
  過去のマイグレーション履歴を詳細情報（リビジョンID、依存関係、作成日時、コメントなど）と共に表示します。
• 利用シーン:
  マイグレーションの順序や内容、依存関係を確認する際、またトラブルシュートのために詳細な情報が必要な場合に有用です。

2. alembic stamp head

• 概要:
  実際のスキーマ変更を伴わずに、データベースのバージョン管理テーブル（通常は alembic_version）に対して、最新リビジョン（head）を設定します。
• 利用シーン:
  既存のデータベースに対して Alembic を初導入する場合や、手動で変更を適用済みと見なすためにバージョン情報を更新する場合に使用します。

3. alembic current

• 概要:
  データベースに現在適用されているリビジョン（バージョン）を表示します。
• 利用シーン:
  適用済みのマイグレーション状態を確認し、現状のバージョンを把握する際に有効です。

4. alembic heads

• 概要:
  現在のマイグレーション履歴における全ての最新リビジョン（ヘッド）を一覧表示します。
• 利用シーン:
  複数の開発ブランチなどで分岐が発生している場合、最新のリビジョンを確認する際に用います。

5. alembic branches

• 概要:
  マイグレーション履歴の中で、分岐しているリビジョン（ブランチ）を表示します。
• 利用シーン:
  分岐の状況を把握し、複数の変更ラインが存在する場合に管理を容易にするために役立ちます。

6. alembic show

• 概要:
  指定したリビジョンの詳細情報を表示します。変更内容、依存関係、コメントなどを確認することが可能です。
• 利用シーン:
  特定のマイグレーション内容を精査し、問題箇所の特定や変更理由の確認を行う際に使用します。

7. alembic merge

• 概要:
  異なるブランチで作成された複数の最新リビジョンを統合（マージ）し、一つのリビジョンとして管理します。
  例： alembic merge -m "Merge heads" <revision1> <revision2>
• 利用シーン:
  複数の開発ブランチが並行して進む場合に、最終的な統合を行い、管理を一元化する際に有用です。

8. --sql オプション

• 概要:
  upgrade や downgrade コマンド実行時に --sql オプションを付与すると、実際のデータベース操作を行わずに、実行される SQL スクリプトを出力します。
  例： alembic upgrade head --sql
• 利用シーン:
  マイグレーション内容を事前に確認したい場合や、生成された SQL を検証・手動適用する必要がある場合に利用されます。

まとめ

Alembic は、SQLAlchemy プロジェクトにおけるデータベーススキーマのバージョン管理・マイグレーションをシンプルかつ柔軟に実現するツールです。
基本的な導入手順としては、インストール、初期化、設定ファイル（alembic.ini、env.py）の編集、そしてモデルの適切なインポートが必要となります。
その後、revision コマンドによるマイグレーションファイルの生成、upgrade/downgrade によるスキーマ変更の適用、さらには各種状態確認や統合のための便利なコマンドを活用することで、安定した運用が可能となります。

本記事で紹介した各コマンドとそのオプションを状況に応じて使い分けることで、プロジェクトにおけるデータベース管理がより効率的かつ確実に実施できるようになるでしょう。