はじめに
このドキュメントは、SQLAlchemy と Alembic を使った開発における基本的な使い方や、できることを自分用にまとめた備忘録です。
個人の備忘録程度の走り書きとなっておりますが、温かい目で見守っていただければ幸いです。
Python アプリケーションにおけるデータベース操作を柔軟かつ安全に行うための参考として記録しています。
1. SQLAlchemy とは
SQLAlchemy は Python の ORM（Object Relational Mapper）ライブラリであり、以下の特徴を持ちます：
- Python クラスでデータベースのテーブル定義ができる
- SQL を直接書かずにクエリが作成できる（ORM機能）
- 必要に応じて生SQL文も実行可能
- 複数のデータベース（SQLite, PostgreSQL, MySQL など）に対応
できること
- データベースとの接続管理
- モデル定義（テーブルを Python クラスで定義）
- クエリの作成（
session.query()など） - レコードの追加、更新、削除
- トランザクション管理
参考文献
2. Alembic とは
Alembic は SQLAlchemy の開発チームが提供するマイグレーションツールです。DBスキーマのバージョン管理をコードベースで行えるのが特徴です。
できること
- モデルの変更を差分として自動検出
- マイグレーションスクリプトの自動生成
- マイグレーション（upgrade/downgrade）の実行
- 複数のマイグレーションバージョンの管理
参考文献
3. SQLAlchemy + Alembic を使うと何が便利になるか？
| 機能 | 説明 |
|---|---|
| テーブル設計を Python で完結 | SQL を書かずにテーブル作成が可能 |
| スキーマ変更を追跡・管理できる | Alembic によってマイグレーションが容易に |
| チーム開発でのスキーマ同期 | DBの状態をコードで管理することで、環境ごとの差異を防げる |
| バージョンの巻き戻しも簡単 | downgrade 機能により、以前の状態に戻せる |
4. 具体的な開発フロー例
- モデル定義
from sqlalchemy import Column, Integer, String
from sqlalchemy.ext.declarative import declarative_base
Base = declarative_base()
class User(Base):
__tablename__ = 'users'
id = Column(Integer, primary_key=True)
name = Column(String(50))
- Alembic 初期化
alembic init alembic
- マイグレーションスクリプトの生成
alembic revision --autogenerate -m "create users table"
- マイグレーションの適用
alembic upgrade head
-
コードの変更とマイグレーション
モデルにカラムを追加→再度autogenerateで差分検知→upgradeで適用
5. 補足：環境構築のポイント
-
alembic.iniファイルで接続先データベースを設定 -
env.pyファイルで SQLAlchemy のBaseを読み込ませる必要あり - Docker や CI/CD 環境にも組み込み可能
まとめ
SQLAlchemy と Alembic を使うことで、
- Python コードでデータベース操作を完結できる
- スキーマ変更をバージョン管理できる
- チーム開発での DB 管理がしやすくなる
開発や運用での柔軟性・安全性が大きく向上します。DB設計・運用をコードで統一的に管理したいなら、SQLAlchemy + Alembic の組み合わせは非常に有効です！