Alembic 1.20.0とは？SQLAlchemy DB Migration Tool

ページ内ナビ

概要

AlembicはSQLAlchemyを基盤に、リレーショナルDBのスキーマ変更をPythonスクリプトとして作成・順序管理・適用するマイグレーションツールです。upgrade/downgrade、autogenerate、transactional DDL、複数branchのmerge、SQLite向けbatch migrationまで扱えます。

特徴と向いている用途

公式資料に基づく紹介・実機未検証 · 内容確認日：2026-10-06

主な特徴

migration environmentとrevision scriptでschema変更を履歴化する

alembic initでproject固有のmigration environmentを作り、各revisionにupgrade()とdowngrade()を記述します。接続方法やscript templateをproject側で変更できるため、database topologyや運用規約に合わせて構成できます。

出典：[2][4]

autogenerateでmodel metadataとdatabase schemaの差分から候補scriptを作る

SQLAlchemyのMetaDataと現在のdatabase schemaを比較し、追加・削除・変更候補をmigration scriptとして生成できます。transactional DDLやbranch/merge、SQLiteのtable recreateを行うbatch modeも用意されています。

出典：[2][5]

向いている用途

schema変更をcode review可能な履歴として管理したいPython backendに向く

SQLAlchemy modelとdatabase schemaを継続的に変更するserviceで、migrationをsource controlへ置き、releaseごとにupgrade pathを再現したい場合に適します。複数branchで並行開発する場合もrevision graphとして扱えます。

出典：[2][4]

導入前の確認

autogenerateを完成品として扱わず、1.20.0のconstraint警告もreviewする

autogenerateが作るのはcandidate migrationで、生成内容は手動reviewが前提です。Alembic 1.20.0はPython 3.10以上とSQLAlchemy 2.0以上を要求し、unnamed CHECK constraintや名前のないconstraintのdropについて警告を追加しています。constraint naming conventionとdowngrade内容を確認してから適用してください。

出典：[3][5][6]

参考にした公式資料

[1]sqlalchemy/alembic — GitHub repository(2026-10-06)
[2]Alembic 1.20.0 — README(2026-10-06)
[3]Alembic 1.20.0 — pyproject.toml(2026-10-06)
[4]Alembic 1.20.0 tutorial(2026-10-06)
[5]Alembic 1.20.0 autogenerate documentation(2026-10-06)
[6]Alembic 1.20.0 release(2026-10-06)
[7]Alembic MIT license(2026-10-06)

編集部からの補足

autogenerateはmigration作成の初期作業を減らせますが、そのまま本番適用する機能ではありません。constraint名、data migration、downgradeの可逆性をcode reviewの対象として運用することが重要です。

3ステップで試す

1
Alembic 1.20.0とSQLAlchemyを導入する
Alembicを対象projectと同じPython環境へversion固定で導入します。
python -m pip install "alembic==1.20.0" "SQLAlchemy==2.1.3"
2
migration environmentを作成する
公式tutorialの開始手順に沿ってalembic.ini、env.py、versions directory等を生成します。
alembic init alembic
3
最初のrevisionを作って履歴を確認する
databaseへ変更を適用せず、version管理されるmigration scriptが生成されることを確認します。実DBへ適用する前に接続設定とupgrade内容を編集してください。
alembic revision -m "baseline" && alembic history

公式READMEで確認

成長

成長の推移 · 直近30日

4,431 Stars

推移データを蓄積中です。

Built with

Python

カテゴリとタグ

GitHubデータ

GitHubのデータGitHubの詳細データを見る

GitHubで見る

GitHub Topics

python
sql
sqlalchemy

Stars: 4,431
Forks: 382
Watchers: 24
Open Issues: 120
Contributors: 199
所有者種別: Organization
主要言語: Python
ライセンス: MIT
リポジトリ最終更新: 2026/10/05