---

もう怖くない！Alembicで始めるデータベースのバージョン管理

「本番環境のデータベース、ALTER TABLE叩くの怖すぎる…」
「え、隣の人が開発DBに直接カラム追加した？こっちのコードが動かなくなったんだけど！」
「このマイグレーション、どのブランチで適用されたんだっけ…？」

Webアプリケーション開発に携わる者なら、誰しも一度はデータベースのスキーマ変更にまつわる冷や汗をかいた経験があるのではないでしょうか。手動でのSQL実行はミスを誘発しやすく、一度の間違いが致命的なデータ損失につながることもあります。チーム開発においては、誰がいつ、どのような変更を加えたのかが不明確になり、開発環境はあっという間にカオスと化します。

私たちは、Gitを使ってソースコードを当たり前のようにバージョン管理しています。誰が、いつ、何を、なぜ変更したのかが一目瞭然で、過去の状態にいつでも戻せる安心感があります。では、なぜアプリケーションの根幹をなすデータベースの「構造（スキーマ）」も同じように管理しないのでしょうか？

この問いに対する強力な答えが、データベースマイグレーションツールです。そして、Pythonエコシステムにおいて最も信頼され、広く使われているのが、今回ご紹介する Alembic です。

Alembicを導入すれば、データベーススキーマの変更をコードとして管理し、バージョン付けし、安全かつ再現可能な方法で適用できるようになります。手動での ALTER TABLE の恐怖から解放され、チーム開発はもっとスムーズになります。

この記事は、Alembicを初めて使う方や、過去に挑戦して挫折した方を対象に、その基本概念からセットアップ、日々の開発ワークフロー、そしてチームで実践するための高度なテクニックまでを、可能な限り丁寧に解説する網羅的なガイドです。この記事を読み終える頃には、あなたは自信を持ってデータベースのバージョン管理を行い、「もうスキーマ変更は怖くない！」と言えるようになっているはずです。

第1章: Alembicの基本を理解する

Alembicの世界に飛び込む前に、まずはその背景にある「データベースマイグレーション」という概念と、Alembicがどのように機能するのかを理解しておきましょう。

1-1. データベースマイグレーションとは？

データベースマイグレーションとは、一言で言えば「データベーススキーマの変更を、バージョン管理された一連のスクリプトによって段階的に行うプロセス」のことです。

Gitでコミットを積み重ねてコードの歴史を管理するように、マイグレーションツールでは「マイグレーションスクリプト」という単位でスキーマの変更履歴を管理します。

例えば、アプリケーションの初期開発で users テーブルを作成する、という変更は最初のマイグレーションスクリプトになります。次に、機能追加で users テーブルに email カラムを追加する必要が出てきたら、新しいマイグレーションスクリプトを作成します。

このアプローチには、以下のような絶大なメリットがあります。

• 再現性: 新しい開発者がプロジェクトに参加した際、マイグレーションスクリプトを最初から最後まで実行するだけで、最新のデータベーススキーマをローカル環境に再現できます。
• 信頼性: 変更内容がコード（スクリプト）として残るため、レビューが可能です。本番環境への適用も、手動ではなくスクリプトを実行するだけなので、ヒューマンエラーが劇的に減少します。
• 履歴管理: なぜこのカラムが追加されたのか、いつテーブル構造が変わったのか、といった変更の意図と経緯を追跡できます。
• ロールバック: 問題が発生した場合、特定のバージョンに戻す（ダウングレードする）ことが可能です。

ちなみに、マイグレーションには「スキーママイグレーション」と「データマイグレーション」の2種類があります。
* スキーママイグレーション: テーブルの作成、カラムの追加・削除、インデックスの作成など、データベースの構造を変更します。Alembicが主戦場とするのはこちらです。
* データマイグレーション: 既存のデータを移行・変換します。例えば、full_name カラムを first_name と last_name に分割する際、既存のデータを新しいカラムに移行するような処理です。Alembicはこれもサポートしています。

1-2. Alembicのアーキテクチャ

Alembicは、いくつかの主要なコンポーネントで構成されています。alembic init コマンドで初期化すると、これらのファイルやディレクトリが生成されます。

• alembic コマンドラインツール: マイグレーションスクリプトの生成、適用、状態確認など、すべての操作を行うためのインターフェースです。
• alembic.ini: Alembic自体の設定ファイルです。データベースへの接続情報や、スクリプトの場所などを記述します。
• env.py: マイグレーションスクリプトが実行される際の「実行環境」を定義するPythonスクリプトです。データベース接続の確立や、SQLAlchemyモデルの読み込みなど、重要な役割を担います。
• versions/ ディレクトリ: 生成されたマイグレーションスクリプト（.pyファイル）が格納される場所です。各スクリプトには一意のリビジョンIDが付きます。
• script.py.mako: マイグレーションスクリプトを生成する際のテンプレートファイルです。Makoというテンプレートエンジンが使われています。

これらのコンポーネントが連携し、堅牢なマイグレーションシステムを構築しています。

1-3. AlembicとSQLAlchemyの関係

Alembicを語る上で、SQLAlchemy との関係は切っても切れません。Alembicは、SQLAlchemyプロジェクトの一部として開発された、SQLAlchemyのためのマイグレーションツールです。

SQLAlchemyは、PythonにおけるデファクトスタンダードなORM（Object-Relational Mapper）およびSQLツールキットです。
* SQLAlchemy Core: Pythonの式を使ってSQLを構築し、データベースエンジンに依存しない形でクエリを実行できる低レベルなライブラリです。
* SQLAlchemy ORM: Pythonのクラス（モデル）をデータベースのテーブルにマッピングし、オブジェクト操作でデータベースを扱えるようにする高レベルなライブラリです。

Alembicは、このSQLAlchemy Coreの能力を最大限に活用しています。マイグレーションスクリプト内で op.create_table() のようなコマンドを実行すると、AlembicはそれをSQLAlchemy Coreの機能を使って、接続先のデータベース（PostgreSQL, MySQL, SQLiteなど）の方言に合わせた適切なDDL（Data Definition Language、例: CREATE TABLE ...）に変換して実行します。これにより、私たちはデータベースごとのSQL構文の違いを意識することなく、Pythonコードでスキーマ変更を記述できるのです。

そして、Alembicの最も強力な機能の一つが autogenerate（自動生成） です。これは、私たちが定義したSQLAlchemyのモデル（Pythonクラス）の状態と、現在のデータベースのスキーマ状態を比較し、その差分を検出してマイグレーションスクリプトを自動で生成してくれる機能です。これにより、面倒な ALTER TABLE 文を自分で書く手間が大幅に省けます。

この強力な連携こそが、AlembicがPython開発者にとって最高の選択肢である理由なのです。

第2章: Alembic環境のセットアップ

それでは、実際にAlembicをプロジェクトに導入してみましょう。ここでは、簡単なブログアプリケーションを例に、環境構築から設定までをステップバイステップで進めていきます。

2-1. プロジェクトの準備

まずは、プロジェクト用のディレクトリを作成し、Pythonの仮想環境を有効にします。仮想環境を使うことで、プロジェクトごとにライブラリのバージョンを分離でき、依存関係の衝突を防げます。

“`bash

プロジェクトディレクトリを作成して移動

mkdir my-blog-project
cd my-blog-project

Python仮想環境を作成

python -m venv venv

仮想環境を有効化 (macOS/Linux)

source venv/bin/activate

(Windowsの場合)

venv\Scripts\activate

“`

次に、AlembicとSQLAlchemy、そして使用するデータベースのドライバをインストールします。今回は、広く使われているPostgreSQLを例に進めます。

“`bash

必要なライブラリをインストール

pip install alembic sqlalchemy psycopg2-binary
``
*alembic: Alembic本体です。
*sqlalchemy: Alembicが依存しているSQLAlchemyです。
*psycopg2-binary: PythonからPostgreSQLに接続するためのドライバです。MySQLを使う場合はmysqlclientやPyMySQL`、SQLiteの場合は追加のドライバは不要です。

2-2. Alembicリポジトリの初期化

ライブラリの準備ができたら、いよいよAlembicの環境を初期化します。プロジェクトのルートディレクトリで以下のコマンドを実行してください。

bash
alembic init alembic

このコマンドは、alembic という名前のディレクトリを作成し、その中にAlembicの設定ファイルを一式生成します。

my-blog-project/
├── alembic/
│ ├── versions/ # マイグレーションスクリプトが格納される
│ ├── env.py # 実行環境設定スクリプト
│ └── script.py.mako # スクリプトテンプレート
├── alembic.ini # Alembic設定ファイル
└── venv/

次に、生成されたファイルを私たちのプロジェクトに合わせて設定していきましょう。

1. alembic.ini の設定

このファイルはAlembicのメイン設定ファイルです。最も重要な設定は、データベースへの接続情報 sqlalchemy.url です。

alembic.ini を開いて、[alembic] セクションにある sqlalchemy.url の行を編集します。

“`ini

alembic.ini

[alembic]

… 他の設定 …

データベースへの接続URI

例: postgresql://user:password@host:port/dbname

sqlalchemy.url = postgresql://blog_user:password@localhost/blog_db

… 他の設定 …

“`

セキュリティTIPS: このように設定ファイルに直接パスワードを書き込むのは、セキュリティ上好ましくありません。実際のプロジェクトでは、環境変数から読み込むのが一般的です。env.py を少し変更することで、これに対応できます（後述）。

2. env.py の設定

env.py はAlembicの心臓部とも言えるファイルです。ここで、Alembicが autogenerate 機能を使うために、私たちのアプリケーションのモデル定義（テーブルの構造）をどこから読み込むかを設定します。

まず、私たちのアプリケーションのモデルを定義するためのファイルを作成しましょう。プロジェクトルートに app/models.py というファイルを作成します。

my-blog-project/
├── alembic/
├── app/
│ └── models.py # ここにモデルを定義する
├── alembic.ini
└── venv/

次に、env.py を編集して、この models.py を読み込み、そのメタデータをAlembicに教えます。

env.py の上部にある import 文の近くに、プロジェクトのパスを通すためのコードを追加します。

“`python

env.py

… 既存のimport文 …

from logging.config import fileConfig

— ここから追加 —

import os
import sys
from sqlalchemy import engine_from_config
from sqlalchemy import pool

プロジェクトのルートディレクトリをPythonのパスに追加

これにより、’app’モジュールをインポートできるようになる

sys.path.append(os.path.join(os.path.dirname(file), ‘..’))

— ここまで追加 —

from alembic import context

…

“`

そして、ファイルの中腹あたりにある target_metadata の設定を探し、以下のように変更します。

“`python

env.py

… (中略) …

— ここを変更 —

元々: target_metadata = None

app/models.py から Base.metadata をインポートして設定する

from app.models import Base
target_metadata = Base.metadata

— ここまで変更 —

… (後略) …

“`

この target_metadata = Base.metadata という一行が極めて重要です。Base.metadata は、SQLAlchemyのモデル定義を集約したオブジェクトです。これを target_metadata に設定することで、Alembicの autogenerate 機能は「あるべき姿（モデル定義）」を知ることができます。そして、sqlalchemy.url から接続した実際のデータベースの状態と比較し、差分を検出するのです。

2-3. SQLAlchemyモデルの定義

それでは、env.py で参照設定した app/models.py に、ブログアプリケーションの基本的なモデルを定義しましょう。User と Post テーブルを作成します。

“`python

app/models.py

from sqlalchemy import (
Column,
Integer,
String,
Text,
DateTime,
ForeignKey,
)
from sqlalchemy.orm import relationship, declarative_base
from sqlalchemy.sql import func

declarative_base()は、モデルクラスが継承するためのベースクラスを返すファクトリ関数

このBaseを継承したクラスは、SQLAlchemyによってテーブルとしてマッピングされる

Base = declarative_base()

class User(Base):
tablename = ‘users’

id = Column(Integer, primary_key=True)
username = Column(String(50), nullable=False, unique=True)
created_at = Column(DateTime, server_default=func.now())

posts = relationship("Post", back_populates="author")

def __repr__(self):
    return f"<User(username='{self.username}')>"

class Post(Base):
tablename = ‘posts’

id = Column(Integer, primary_key=True)
title = Column(String(200), nullable=False)
content = Column(Text, nullable=False)
created_at = Column(DateTime, server_default=func.now())
author_id = Column(Integer, ForeignKey('users.id'), nullable=False)

author = relationship("User", back_populates="posts")

def __repr__(self):
    return f"<Post(title='{self.title}')>"

“`

これで、Alembicを使うためのすべての準備が整いました。プロジェクト構造は以下のようになっているはずです。

my-blog-project/
├── alembic/
│ ├── versions/
│ ├── env.py
│ └── script.py.mako
├── app/
│ └── models.py
├── alembic.ini
└── venv/

第3章: 初めてのマイグレーション

準備が整ったところで、いよいよ最初のマイグレーションを実行し、データベースにテーブルを作成してみましょう。

3-1. マイグレーションスクリプトの自動生成 (autogenerate)

私たちの手元には、あるべきDBの姿を定義した app/models.py があります。一方、データベースはまだ空っぽの状態です。この差分をAlembicに検出させ、マイグレーションスクリプトを自動生成してもらいましょう。

ターミナルで以下のコマンドを実行します。

bash
alembic revision --autogenerate -m "Create user and post tables"

• alembic revision: 新しいリビジョン（マイグレーションスクリプト）を作成するコマンドです。
• --autogenerate: env.pyで設定したtarget_metadataと実際のDBを比較し、変更を自動検出します。
• -m "...": このマイグレーションが何をするのかを説明する短いメッセージです。Gitのコミットメッセージのように、分かりやすい名前を付けましょう。

成功すると、alembic/versions/ ディレクトリに新しいファイルが作成されます。

INFO [alembic.autogenerate.compare] Detected new table 'users'
INFO [alembic.autogenerate.compare] Detected new table 'posts'
Generating /path/to/my-blog-project/alembic/versions/xxxxxxxxxxxx_create_user_and_post_tables.py ... done

ファイル名は xxxxxxxxxxxx_create_user_and_post_tables.py のようになります。xxxxxxxxxxxx の部分は、実行ごとに生成される一意のリビジョンIDです。

この生成されたファイルの中身を見てみましょう。

“`python

alembic/versions/xxxxxxxxxxxx_create_user_and_post_tables.py

“””Create user and post tables

Revision ID: xxxxxxxxxxxx
Revises:
Create Date: 2023-10-28 15:00:00.000000

“””
from typing import Sequence, Union

from alembic import op
import sqlalchemy as sa

revision identifiers, used by Alembic.

revision: str = ‘xxxxxxxxxxxx’ # このリビジョンのID
down_revision: Union[str, None] = None # 1つ前のリビジョンID (今回は最初なのでNone)
branch_labels: Union[str, Sequence[str], None] = None
depends_on: Union[str, Sequence[str], None] = None

def upgrade() -> None:
# ### commands auto generated by Alembic – please adjust! ###
op.create_table(‘users’,
sa.Column(‘id’, sa.Integer(), nullable=False),
sa.Column(‘username’, sa.String(length=50), nullable=False),
sa.Column(‘created_at’, sa.DateTime(), server_default=sa.text(‘now()’), nullable=True),
sa.PrimaryKeyConstraint(‘id’),
sa.UniqueConstraint(‘username’)
)
op.create_table(‘posts’,
sa.Column(‘id’, sa.Integer(), nullable=False),
sa.Column(‘title’, sa.String(length=200), nullable=False),
sa.Column(‘content’, sa.Text(), nullable=False),
sa.Column(‘created_at’, sa.DateTime(), server_default=sa.text(‘now()’), nullable=True),
sa.Column(‘author_id’, sa.Integer(), nullable=False),
sa.ForeignKeyConstraint([‘author_id’], [‘users.id’], ),
sa.PrimaryKeyConstraint(‘id’)
)
# ### end Alembic commands ###

def downgrade() -> None:
# ### commands auto generated by Alembic – please adjust! ###
op.drop_table(‘posts’)
op.drop_table(‘users’)
# ### end Alembic commands ###
“`

重要なのは upgrade() と downgrade() の2つの関数です。

• upgrade(): このバージョンにマイグレーションする（進める）際に実行される処理です。op.create_table() が呼ばれ、users と posts テーブルを作成するコードが自動生成されています。
• downgrade(): このバージョンから前のバージョンにロールバックする（戻す）際に実行される処理です。upgrade() とは逆の操作、つまり op.drop_table() が記述されています。

op は Alembic Operations のオブジェクトで、create_table, add_column, drop_index といった、データベースのスキーマを操作するための様々なメソッドを提供します。

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

スクリプトが生成されただけでは、まだデータベースは空のままです。このスクリプトをデータベースに適用しましょう。

bash
alembic upgrade head

• alembic upgrade: マイグレーションを適用するコマンドです。
• head: 「最新のリビジョンまで」を意味します。特定のバージョンを指定することも可能です（例: alembic upgrade xxxxxxxxxxxx）。

このコマンドを実行すると、upgrade() 関数の中身が実行され、データベースにSQLが発行されます。

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO [alembic.runtime.migration] Will assume transactional DDL.
INFO [alembic.runtime.migration] Running upgrade -> xxxxxxxxxxxx, Create user and post tables

これで、データベースに users テーブルと posts テーブルが作成されました。psqlなどのデータベースクライアントで確認してみてください。

sql
\d users
Table "public.users"
Column | Type | Collation | Nullable | Default
------------+-----------------------+-----------+----------+-----------------------------------
id | integer | | not null | nextval('users_id_seq'::regclass)
username | character varying(50) | | not null |
created_at | timestamp without time zone | | | now()
Indexes:
"users_pkey" PRIMARY KEY, btree (id)
"users_username_key" UNIQUE CONSTRAINT, btree (username)
Referenced by:
TABLE "posts" CONSTRAINT "posts_author_id_fkey" FOREIGN KEY (author_id) REFERENCES users(id)

見事にテーブルが作成されていますね！

また、もう一つ重要なテーブルが自動で作成されていることに気づくでしょう。それは alembic_version テーブルです。

“`sql
SELECT * FROM alembic_version;
version_num

---

xxxxxxxxxxxx
(1 row)
“`

このテーブルには、現在データベースがどのリビジョンまで適用されているかが記録されています。Alembicは常にこのテーブルを参照して、次にどの upgrade または downgrade 処理を実行すべきかを判断します。このテーブルを手動で編集してはいけません。

3-3. マイグレーションのダウングレード

万が一、適用したマイグレーションに問題があり、元に戻したくなった場合は downgrade コマンドを使います。

“`bash

1つ前のリビジョンに戻す

alembic downgrade -1
“`

これを実行すると、リビジョン xxxxxxxxxxxx の downgrade() 関数が実行され、テーブルが削除されます。alembic_version テーブルのレコードも削除されます（テーブル自体は残ります）。

INFO [alembic.runtime.migration] Context impl PostgresqlImpl.
INFO [alembic.runtime.migration] Will assume transactional DDL.
INFO [alembic.runtime.migration] Running downgrade xxxxxxxxxxxx -> , Create user and post tables

base を指定すると、すべてのマイグレーションが適用される前の初期状態に戻すこともできます。

bash
alembic downgrade base

このように、upgradeとdowngradeを正しく記述しておくことで、データベースの状態を自由に行き来できるようになります。これがAlembicがもたらす安心感の源泉です。

第4章: 実践的なマイグレーションワークフロー

基本的な使い方が分かったところで、次は日々の開発で発生する、より実践的なシナリオを見ていきましょう。

4-1. モデルの変更と追加マイグレーション

アプリケーション開発を進める中で、モデルの変更は日常茶飯事です。例えば、users テーブルにメールアドレスを保存するための email カラムを追加したくなったとしましょう。

まず、app/models.py の User モデルを修正します。

“`python

app/models.py

class User(Base):
tablename = ‘users’

id = Column(Integer, primary_key=True)
username = Column(String(50), nullable=False, unique=True)
email = Column(String(100), nullable=False, unique=True) # この行を追加
created_at = Column(DateTime, server_default=func.now())

posts = relationship("Post", back_populates="author")

# ... (後略) ...

“`

モデルを修正したら、やることは先ほどと同じです。autogenerate で変更を検出させます。

bash
alembic revision --autogenerate -m "Add email column to user table"

新しいリビジョンが生成されます。中身を見てみましょう。

“`python

alembic/versions/yyyyyyyyyyyy_add_email_column_to_user_table.py

“””Add email column to user table

Revision ID: yyyyyyyyyyyy
Revises: xxxxxxxxxxxx # 1つ前のリビジョンIDが自動で設定される
Create Date: 2023-10-28 15:30:00.000000

“””

…

def upgrade() -> None:
# ### commands auto generated by Alembic – please adjust! ###
op.add_column(‘users’, sa.Column(‘email’, sa.String(length=100), nullable=False))
op.create_unique_constraint(None, ‘users’, [‘email’])
# ### end Alembic commands ###

def downgrade() -> None:
# ### commands auto generated by Alembic – please adjust! ###
op.drop_constraint(None, ‘users’, type_=’unique’)
op.drop_column(‘users’, ‘email’)
# ### end Alembic commands ###
“`

down_revision に一つ前のリビジョンID (xxxxxxxxxxxx) が正しく設定されていることが分かります。これにより、マイグレーションの歴史が一本の鎖のようにつながります。upgrade() には op.add_column が、downgrade() には op.drop_column が記述されており、完璧です。

注意点: 既存のテーブルに nullable=False (NOT NULL) のカラムを追加する場合、既存のレコードに何の値を入れるかという問題が発生します。autogenerate はこれを機械的に処理できないため、データベースによってはエラーになります。この場合、
1. nullable=True でカラムを追加する。
2. データマイグレーションで既存レコードにデフォルト値を設定する。
3. カラムを nullable=False に変更する。
という3ステップのマイグレーションが必要になることがあります。常に生成されたスクリプトを確認し、必要に応じて手動で調整する癖をつけましょう。

では、このマイグレーションを適用します。

bash
alembic upgrade head

これで、users テーブルに email カラムが追加されました。

4-2. Autogenerateが検出できない変更

autogenerate は魔法のように便利ですが、万能ではありません。以下のような変更は、多くの場合自動で検出できません。

• テーブル名やカラム名の変更
• CHECK 制約の追加・削除
• サーバーサイドデフォルト（server_default）の変更
• 特定の種類のインデックス（関数ベースインデックスなど）

例えば、users テーブルの username カラムを user_name に変更したい場合、autogenerate は「username カラムが削除され、user_name カラムが新しく追加された」と誤って検出してしまいます。これではデータが失われてしまいます。

このような場合は、手動でマイグレーションスクリプトを調整する必要があります。

1. まず、空のマイグレーションスクリプトを作成します。
   bash
alembic revision -m "Rename username to user_name in users table"
--autogenerate を付けないことで、中身が空の upgrade/downgrade 関数を持つスクリプトが生成されます。

2. 生成されたスクリプトを編集し、op.alter_column() を使ってカラム名を変更する処理を記述します。

   “`python

   alembic/versions/zzzzzzzzzzzz_rename_username_to_user_name.py

   …

   def upgrade() -> None:
   op.alter_column(‘users’, ‘username’, new_column_name=’user_name’)

   def downgrade() -> None:
   op.alter_column(‘users’, ‘user_name’, new_column_name=’username’)
   “`

このように、autogenerate に頼りきりになるのではなく、その限界を理解し、必要に応じて手動でスクリプトを記述・修正するスキルが重要です。困ったときは、op オブジェクトが持つ豊富なメソッドを Alembicの公式ドキュメント で確認しましょう。op.execute() を使えば、任意のSQLを実行することも可能です。

4-3. 複数の開発者が関わるブランチ戦略

チーム開発では、複数の開発者が同時に異なる機能開発を進めるのが普通です。これは、Gitではブランチを切ることで対応しますが、Alembicのマイグレーションはどうなるのでしょうか？ここに、Alembicのもう一つの強力な機能「ブランチマイグレーション」が登場します。

シナリオ:
main ブランチの最新リビジョンが R1 の状態だとします。

1. 開発者Aは feature/add-tags ブランチを作成し、posts テーブルにタグ機能を追加するためのマイグレーション A1 を作成しました (down_revisionはR1)。
2. 開発者Bは feature/user-profile ブランチを作成し、users テーブルにプロフィール情報を追加するためのマイグレーション B1 を作成しました (down_revisionは同じくR1)。

この時点で、マイグレーションの歴史は分岐しています。

-> A1 (head) [feature/add-tags]
/
...-R1
\
-> B1 (head) [feature/user-profile]

alembic heads コマンドを打つと、A1 と B1 の2つのhead（最新リビジョン）が表示されます。

ここで、開発者Aの feature/add-tags が先に main ブランチにマージされたとします。main のDBは R1 -> A1 と進みます。

次に、開発者Bが feature/user-profile を main にマージしようとすると問題が起こります。B1 は R1 の次に来ることを期待していますが、main の最新はすでに A1 です。

この衝突を解決するのが alembic merge コマンドです。開発者Bは、マージされた main を自分のブランチに取り込み（git pull origin main）、以下のコマンドを実行します。

“`bash

A1とB1のリビジョンIDを指定してマージポイントを作成

alembic merge
“`

すると、Alembicは M1 という新しい「マージリビジョン」を生成します。

“`python

alembic/versions/M1_merge_heads.py

“””merge heads

Revision ID: M1
Revises: A1, B1 # 2つのリビジョンを親に持つ
Create Date: 2023-10-28 16:00:00.000000
“””

…

upgrade/downgradeは空でよい

def upgrade() -> None:
pass

def downgrade() -> None:
pass
“`

このマージリビジョンの特徴は、Revises (Alembicの内部では down_revision) がタプルになり、2つの親リビジョンを持つことです。これにより、分岐した歴史が一つに統合されます。

-> A1 ->
/ \
...-R1 -> M1 (head)
\ /
-> B1 ->

この状態で alembic upgrade head を実行すると、Alembicは現在のDB状態（A1）とターゲットの M1 を比較し、まだ適用されていない B1 の upgrade() を実行してから M1 に進みます。これにより、どちらの機能のスキーマ変更も正しく適用された状態になります。

このブランチとマージの仕組みを理解することが、チーム開発でAlembicを円滑に運用する鍵となります。

4-4. データマイグレーション

スキーマの変更だけでなく、データの変換が必要になることもあります。例えば、「users テーブルに is_active カラムを追加し、既存の全ユーザーをデフォルトで有効（active）にしたい」というケースを考えます。

まず、スキーマ変更のマイグレーションを作成します。default=True を付けておくと、新しい行には自動で True が入りますが、既存の行は NULL のままです。

“`bash

app/models.py で is_active を追加

alembic revision –autogenerate … を実行

“`

次に、生成されたスクリプトにデータ更新処理を追加します。

“`python

…

from sqlalchemy.sql import table, column
from sqlalchemy import Boolean

def upgrade() -> None:
op.add_column(‘users’, sa.Column(‘is_active’, sa.Boolean(), nullable=False, server_default=’true’))

# --- データマイグレーションの追加 ---
# ここでモデルを直接インポートすると、将来モデルが変更された場合に
# この古いマイグレーションが壊れる可能性がある。
# そのため、Alembicではアドホックなテーブルオブジェクトを作成することが推奨される。
users_table = table('users',
    column('is_active', Boolean)
)
# 既存の全ユーザーの is_active を True に更新
op.execute(
    users_table.update().values(is_active=True)
)
# --- ここまで ---

def downgrade() -> None:
op.drop_column(‘users’, ‘is_active’)
“`

downgrade でデータを元に戻すのは複雑、あるいは不可能なことが多い（この例ではカラムごと消すので不要）ため、データマイグレーションは特に慎重に行う必要があります。重要なデータの変換は、アプリケーションコード側でバッチ処理として実装する方が安全な場合もあります。

第5章: 高度なトピックとベストプラクティス

Alembicを使いこなすための、さらに一歩進んだトピックと、現場で培われたベストプラクティスを紹介します。

5-1. 本番環境へのデプロイ戦略

ローカルで開発したマイグレーションを、本番環境へ安全にデプロイするにはどうすればよいでしょうか。

• CI/CDパイプラインに組み込む: デプロイプロセスの一部として、alembic upgrade head コマンドを自動で実行するように設定します。これにより、コードのデプロイとDBスキーマの更新が常に同期されます。
• 必ずバックアップを取る: alembic upgrade を実行する直前に、必ずデータベースのバックアップを取得するステップをパイプラインに組み込みましょう。万が一の事態に備えることが、プロフェッショナルの条件です。
• トランザクショナルDDL: PostgreSQLなど一部のデータベースは、DDL（CREATE TABLEなど）をトランザクション内で実行できます。env.py のデフォルト設定ではこれが有効になっており、マイグレーションスクリプトの実行中にエラーが発生した場合、すべての変更が自動でロールバックされます。非常に安全な機能なので、対応DBでは必ず有効にしておきましょう。
• ゼロダウンタイムマイグレーション: サービスを停止させずにマイグレーションを行うための高度なテクニックです。例えば、カラムを削除するような破壊的変更は、一度に行いません。
  1. Release 1: カラムを削除するマイグレーションは適用せず、アプリケーションコード側でそのカラムを参照しないように修正してデプロイ。
  2. Release 2: すべてのアプリケーションサーバーが新しいコードに置き換わったら、安全にカラムを削除するマイグレーション（op.drop_column）を適用。
     このように、スキーマ変更とコード変更を複数のリリースに分けることで、ダウンタイムを回避します。

5-2. alembic.ini と env.py のカスタマイズ

alembic.ini は、開発、ステージング、本番など、複数の環境設定を記述できます。

“`ini

alembic.ini

[alembic]
sqlalchemy.url = postgresql://dev:pass@localhost/dev_db

[production]
sqlalchemy.url = postgresql://prod:pass@prod_host/prod_db

[staging]
sqlalchemy.url = postgresql://staging:pass@staging_host/staging_db
“`

コマンド実行時に -n オプションで名前を指定することで、使用する設定を切り替えられます。

“`bash

productionのDB設定でマイグレーションを実行

alembic -n production upgrade head
“`

また、設定ファイルにパスワードを直書きするのを避けるため、env.py で環境変数を読み込むようにカスタマイズするのが一般的です。env.py の run_migrations_online 関数内を少し変更します。

“`python

env.py 内の run_migrations_online()

…

config.set_main_option(‘sqlalchemy.url’, ‘…’) の行をコメントアウトまたは削除し、

以下のように書き換える

環境変数からデータベースURLを構築

db_url = os.environ.get(‘DATABASE_URL’)
if not db_url:
raise ValueError(“DATABASE_URL environment variable is not set”)

connectable = create_engine(db_url) # create_engineを直接使う

with connectable.connect() as connection:
context.configure(
connection=connection,
target_metadata=target_metadata
# …
)

…

“`

5-3. マイグレーションスクリプトのテスト

「このマイグレーション、downgrade したらちゃんと元に戻るかな？」「意図せずデータが消えたりしないかな？」
この不安を解消するのが、マイグレーションのテストです。pytest などのテストフレームワークを使い、マイグレーションの正しさを自動で検証できます。

テストの基本的な流れは以下の通りです。
1. テスト用の空のデータベースを準備する。
2. alembic upgrade head を実行し、スキーマを最新の状態にする。
3. スキーマが期待通りになっているかアサーションで確認する。
4. alembic downgrade base を実行し、スキーマを初期状態に戻す。
5. すべてのテーブルが削除されていることをアサーションで確認する。

この「アップグレード -> ダウングレード」の往復テストを行うことで、downgrade 関数の記述ミスや、破壊的な変更による問題を事前に検知できます。

“`python

tests/test_migrations.py (pytestの例)

import pytest
from alembic.config import Config
from alembic import command
from sqlalchemy import create_engine, inspect

@pytest.fixture(scope=”session”)
def alembic_config():
“””テスト用のAlembic設定を返すFixture”””
# テストDBのURLなど、テスト用の設定を読み込む
return Config(“alembic.ini”) # 必要に応じてテスト用iniファイルを用意

def test_migrations_up_and_down(alembic_config):
“””マイグレーションが head まで upgrade し、base まで downgrade できることをテスト”””

# テストDBのURLを取得
db_url = alembic_config.get_main_option("sqlalchemy.url")

# 念のためテストDBをクリーンな状態にする
engine = create_engine(db_url)
# (既存のテーブルを全て削除する処理)
engine.dispose()

# 1. headまでアップグレード
command.upgrade(alembic_config, "head")

# 2. baseまでダウングレード
command.downgrade(alembic_config, "base")

# 3. 再度headまでアップグレードできることを確認（クリーンな状態から適用できるか）
command.upgrade(alembic_config, "head")

# (オプション) Inspectorを使ってテーブルの存在確認など、より詳細なテストも可能
inspector = inspect(create_engine(db_url))
assert "users" in inspector.get_table_names()
assert "posts" in inspector.get_table_names()

“`
このようなテストをCIに組み込んでおけば、マージ前にマイグレーションの安全性を担保でき、チーム全体の開発品質が向上します。

5-4. よくある落とし穴と対処法

• autogenerate への過信: 生成されたスクリプトは必ず目視でレビューしましょう。特に、カラム名の変更や制約の変更が意図通りか確認が必要です。
• 手動でのDB変更: 絶対にやってはいけません。DBの状態とAlembicが認識している状態にズレが生じ、autogenerateが奇妙な差分を検出する原因になります。全てのスキーマ変更はAlembicを通して行う、というルールをチームで徹底しましょう。
• downgrade の省略: 「どうせ戻さないから」とdowngradeを空のままにするのは避けましょう。予期せぬ問題でロールバックが必要になった際に、あなたを救ってくれるのは正しく書かれたdowngrade処理です。
• 長期間放置されたブランチのマージ: マイグレーションのコンフリクトが複雑になりがちです。可能な限り、mainブランチの変更をこまめに取り込み、alembic merge が必要になったら速やかに対処しましょう。

まとめ

この記事では、データベースマイグレーションツールAlembicの基本概念から、日々の開発で役立つ実践的なワークフロー、そしてチームで運用するための高度なテクニックまでを駆け足で解説してきました。

Alembicは、単に ALTER TABLE を自動化するツールではありません。それは、アプリケーションの心臓部であるデータベースのスキーマに秩序と規律、そして安心感をもたらすための「文化」そのものです。

• スキーマ変更はすべてバージョン管理されたコードになる。
• 誰が、いつ、なぜ変更したのか、その歴史を追跡できる。
• 新しい環境のセットアップは、コマンド一発で完了する。
• 本番環境への適用は、自動化され、信頼性が高い。
• チーム開発でのスキーマのコンフリクトも、体系的な方法で解決できる。

Alembicを導入することで、あなたはもう、深夜のデータベース操作に怯える必要はありません。自信を持って、迅速かつ安全にアプリケーションを進化させ続けることができるようになります。

さあ、あなたのプロジェクトに pip install alembic を。そして、手動でのスキーマ変更の恐怖に別れを告げましょう。もう、何も怖くないのですから。