SQLAlchemy モデル — データベーステーブルの設計

この章では、ネイティブの SQLAlchemy ORM を使ってデータモデルを定義し、FastAPI の依存性注入を通じてデータベースセッションを管理する方法を学びます。


FastAPI にはなぜ組み込みの ORM がないのか?

Django には組み込みの ORM があり、Flask では Flask-SQLAlchemy が推奨されます。

FastAPI には組み込み ORM がありません。最も適したツールを選ぶことを期待しており、SQLAlchemy + Pydanticコミュニティで公认されている最適な組み合わせです。

(venv) $ pip install sqlalchemy

データベース接続の設定

例

# ファイルパス: database.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, DeclarativeBase

# SQLite データベースファイルのパス
SQLALCHEMY_DATABASE_URL = "sqlite:///./blog.db"

# エンジンの作成:check_same_thread は SQLite 専用のパラメータ
engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False}   # SQLite 固有:スレッド間の使用を許可
)

# セッションファクトリを作成
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# Base クラス:すべての ORM モデルはこれを継承
class Base(DeclarativeBase):
    pass

check_same_thread=Falsecheck_same_thread は FastAPI における SQLite の必須設定です。デフォルトでは SQLite は同じ接続をスレッド間で使用できませんが、Web アプリでは各リクエストが異なるスレッドで処理される可能性があります。

依存性注入: get_db

例

# ファイルパス: database.py に追記
from fastapi import Depends

def get_db():
    """FastAPI の依存性注入:リクエストごとに独立したデータベースセッションを作成"""
    db = SessionLocal()
    try:
        yield db          # リクエスト期間中はこのセッションを使用
    finally:
        db.close()        # リクエスト終了後にセッションを自動クローズし、接続リークを防止

Depends(get_db)get_db は FastAPI の依存性注入システムであり、ルート関数は依存性注入によって自動的にデータベースセッションを取得します。


モデルの定義: Post と Category

例

# ファイルパス: models.py
from sqlalchemy import Column, Integer, String, Text, DateTime, ForeignKey
from sqlalchemy.orm import relationship
from datetime import datetime
from database import Base

class Category(Base):
    """記事カテゴリ"""
    __tablename__ = "categories"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(50), unique=True, nullable=False)
    slug = Column(String(50), unique=True, nullable=False)
    # back_populates による双方向リレーション
    posts = relationship("Post", back_populates="category")


class Post(Base):
    """ブログ記事"""
    __tablename__ = "posts"
    id = Column(Integer, primary_key=True, index=True)
    title = Column(String(200), nullable=False)
    slug = Column(String(200), unique=True, nullable=False)
    summary = Column(Text, default="")
    content = Column(Text, nullable=False)
    category_id = Column(Integer, ForeignKey("categories.id"), nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)
    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
    # Category との双方向リレーション
    category = relationship("Category", back_populates="posts")

FastAPI で使用されるのはネイティブ SQLAlchemy(Flask-SQLAlchemy のdb.Modelではありません)。注意:Column のインポート、Base の継承、relationship の書き方の違い。後で対照表があります。


データベーステーブルの初期化

例

# ファイルパス: main.py 起動イベントでテーブルを作成
from fastapi import FastAPI
from database import engine, Base
from models import Category, Post   # モデルクラスがインポートされていることを確認して、Base.metadata が認識できるようにする

app = FastAPI()

@app.on_event("startup")
def on_startup():
    """アプリ起動時にデータベーステーブルを自動作成(開発時のみ使用)"""
    Base.metadata.create_all(bind=engine)

後で Alembic マイグレーション(第6章)に切り替えます。create_allクイックプロトタイプ段階でのみ使用します。


テストデータの挿入

Python スクリプトでテストデータを挿入します:

例

# ファイルパス: seed.py(一度実行するだけでOK)
from database import SessionLocal
from models import Category, Post

db = SessionLocal()

# カテゴリを作成
py = Category(name="Python", slug="python")
css = Category(name="CSS", slug="css")
fastapi = Category(name="FastAPI", slug="fastapi")
db.add_all([py, css, fastapi])
db.commit()

# 記事を作成
db.add_all([
    Post(title="FastAPI 入門完全ガイド", slug="fastapi-guide",
         summary="ゼロから学ぶ FastAPI", content="<h2>なぜ FastAPI を選ぶのか?</h2><p>...</p>",
         category_id=fastapi.id),
    Post(title="Python コルーチン詳解", slug="python-coroutine",
         summary="asyncio を理解する", content="<h2>コルーチンとは?</h2><p>...</p>",
         category_id=py.id),
    Post(title="CSS Grid レイアウト実践", slug="css-grid",
         summary="Grid でレスポンシブレイアウトを実装", content="<h2>Grid 入門</h2><p>...</p>",
         category_id=css.id),
])
db.commit()
db.close()
print("テストデータの挿入が完了しました!")

実行python seed.py、データベースに3件の記事が挿入されます。


4つのフレームワークのORM書き方対照

操作DjangoFlask-SQLAlchemyFastAPI(ネイティブ SQLAlchemy)
基底クラスmodels.Modeldb.ModelBase (DeclarativeBase)
フィールドmodels.CharField()db.Column(...)Column(...)
外部キーForeignKey(to, on_delete)db.ForeignKey('table.col')ForeignKey('table.col')
リレーション自動逆参照db.relationship + backrefrelationship + back_populates
セッション自動管理db.sessionSessionLocal() + Depends

本章のまとめ

この章では、FastAPI における SQLAlchemy の統合を習得しました。create_engine + SessionLocal によるデータベース接続の設定、DeclarativeBase によるモデル基底クラスの定義、get_db 依存性注入によるセッション管理、Column/relationship によるフィールドとリレーションの定義です。

Flask-SQLAlchemy と比較すると、ネイティブ SQLAlchemy は記述がやや多めですが、完全にオープンソースで制御可能です。

その他の拡張