はじめに
PythonでORMライブラリを使用するときにSQLAlchemy + alembicの組み合わせが多いと思います。
過去新規アサインしたエンジニアが、alembicにてマイグレーションする方法が分からず、環境構築で止まっており、そのときにまとめた手順が好評だったため共有できればと思い記事を書きました。
Alembicとは
Alembicは、Pythonで書かれたデータベーススキーマのバージョン管理ツールです。
主にSQLAlchemyを使用したデータベースマイグレーションに利用されます。
このドキュメントでは、Alembicの基本的なコマンドとその使い方について説明します。
インストール
Alembicを使用するには、Pythonのパッケージマネージャーであるpipを使ってインストールします。
pip install alembic
セットアップ
Alembicの初期設定を行います。
alembic init <ディレクトリ名>
#
# 例) alembic init alembic
#
# 以下ディレクトリとファイルが生成される
# alembic/
# | - README
# | - env.py
# | - script.py.mako
# | - versions/
# alembic.ini
生成されたディレクトリ内の alembic.ini ファイルを編集し、データベースの接続情報を設定します。
主要なコマンド
以下コマンド実行する場合は、alembic.iniと同じディレクトリ階層にて実行すること。
マイグレーションスクリプトの作成
新しいマイグレーションスクリプトを作成します。
alembic revision -m "マイグレーション名"
#
# 例) alembic revision -m "add users table"
#
# 以下のマイグレーションファイルが生成される
# マイグレーション名の前にランダムな英数文字が入る
# alembic/
# | - README
# | - env.py
# | - script.py.mako
# | - versions/
# | | - 2f265898d6dd_add_users_table.py
# alembic.ini
マイグレーションバージョン一覧
作成したマイグレーションスクリプトのバージョン一覧を表示します。
alembic history
# 以下形式のバージョン一覧を確認できる
# 例）になるため実際のマイグレーションバージョン一覧とは異なります。
#
# a2c7dc5d156b-> 2f265898d6dd (head), add users table
# <base> -> a2c7dc5d156b, maigration init
現在のステータス確認
現在のデータベースの状態や適用されていないマイグレーションを確認します。
alembic current
# 以下形式の現在の適用されているマイグレーションを確認できる
# 上記、マイグレーションバージョン一覧のadd users tableの英数字と値が一致するはずです。
# a2c7dc5d156b (head)
マイグレーションの実行
作成したマイグレーションスクリプトをデータベースに適用します。
alembic upgrade head
# headの場合、最新のマイグレーションが適用されます。
# １つ上のマイグレーションを適用したい場合は、`alembic upgrade +1`を実行します。
マイグレーションの巻き戻し
直近のマイグレーションを取り消します。
alembic downgrade -1
# -1の場合、適用されているマイグレーションのひとつ前のマイグレーションが適用されます。
# 初期のマイグレーションを適用したい場合は、`alembic downgrade base`を実行します。
その他のコマンド
他にも様々なコマンドがあります。詳細は公式ドキュメントを参照してください。
注意事項
- マイグレーションを他の開発者と共有する際は、コードレビューを行うことを推奨します。