sqlalchemy-postgres

<essential_principles>

SQLAlchemy 2.0 + Pydantic + PostgreSQL のベストプラクティス

このスキルでは、本番環境に対応したデータベースレイヤーの構築に関する専門的なガイダンスを提供します。

スタック

• SQLAlchemy 2.0（非同期サポート、asyncpg ドライバー）
• Pydantic v2（検証とシリアライズ）
• Alembic（マイグレーション）
• PostgreSQL のみ

基本原則

1. 関心の分離

models/       # SQLAlchemy ORM models (database layer)
schemas/      # Pydantic schemas (API layer)
repositories/ # Data access patterns
services/     # Business logic

2. 型安全性を最優先 常に Mapped[] 型アノテーションを使い、SQLAlchemy 2.0 スタイルに従います。

from sqlalchemy.orm import Mapped, mapped_column

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(100))

3. デフォルトで非同期 FastAPI では非同期エンジンとセッションを使用します。

from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
engine = create_async_engine("postgresql+asyncpg://...")

4. Pydantic と SQLAlchemy の連携 モデルとスキーマは分離しつつ、相互にマッピングできるようにします。

# Schema reads from ORM
class UserRead(BaseModel):
    model_config = ConfigDict(from_attributes=True)

5. リポジトリパターン テスト容易性とクリーンなコードのために、データベース操作を抽象化します。 </essential_principles>

どのようなサポートが必要ですか？

1. データベースレイヤーのセットアップ - SQLAlchemy + Pydantic + Alembic を一から初期化する
2. モデルの定義 - Pydantic スキーマを備えた SQLAlchemy モデルを作成する
3. マイグレーションの作成 - Alembic のマイグレーションを生成・管理する
4. クエリパターン - 非同期 CRUD、JOIN、Eager Loading、最適化
5. 完全な実装 - 機能に必要なデータベースレイヤー全体を実装する

| 応答 | ワークフロー | |----------|----------| | 1, "setup", "initialize", "start" | workflows/setup-database.md | | 2, "model", "define", "create model" | workflows/define-models.md | | 3, "migration", "alembic", "schema change" | workflows/create-migration.md | | 4, "query", "crud", "repository" | workflows/query-patterns.md | | 5, "full", "complete", "feature" | setup → define-models → create-migration を実行 |

自動検出のトリガー（ユーザーが次の内容に言及した場合、このスキルを使用します）：

• database, db, sqlalchemy, postgres, postgresql
• model, migration, alembic
• repository, crud, query
• async session, connection pool

<reference_index>

ドメイン知識

リファレンス	目的
references/best-practices.md	本番環境のパターン、セキュリティ、パフォーマンス
references/patterns.md	リポジトリ、Unit of Work、一般的なクエリ
references/async-patterns.md	非同期セッション管理、FastAPI との連携
</reference_index>

<workflows_index>

ワークフロー	目的
workflows/setup-database.md	データベースレイヤー全体を初期化する
workflows/define-models.md	モデル、スキーマ、リレーションシップを作成する
workflows/create-migration.md	Alembic のマイグレーションワークフロー
workflows/query-patterns.md	CRUD 操作と最適化
</workflows_index>

<quick_reference>

ファイル構成

src/
├── db/
│   ├── __init__.py
│   ├── base.py          # DeclarativeBase
│   ├── session.py       # Engine + async session factory
│   └── dependencies.py  # FastAPI dependency
├── models/
│   ├── __init__.py
│   └── user.py          # SQLAlchemy models
├── schemas/
│   ├── __init__.py
│   └── user.py          # Pydantic schemas
├── repositories/
│   ├── __init__.py
│   ├── base.py          # Generic repository
│   └── user.py          # User repository
└── alembic/
    ├── alembic.ini
    ├── env.py
    └── versions/

必須のインポート

# Models
from sqlalchemy import String, Integer, ForeignKey, DateTime
from sqlalchemy.orm import Mapped, mapped_column, relationship, DeclarativeBase

# Async
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker

# Pydantic
from pydantic import BaseModel, ConfigDict, Field

接続文字列

# PostgreSQL async
DATABASE_URL = "postgresql+asyncpg://user:pass@localhost:5432/dbname"

</quick_reference>

<success_criteria> 次の条件を満たすと、データベースレイヤーは完成です。

• 非同期エンジンとセッションファクトリーが設定されている
• 共通フィールド（id、created_at、updated_at）を備えたベースモデルがある
• モデルで Mapped[] 型アノテーションが使用されている
• from_attributes=True を指定した Pydantic スキーマがある
• Alembic が非同期用に設定されている
• リポジトリパターンが実装されている
• セッション注入用の FastAPI 依存関係がある
• 本番環境用のコネクションプーリングが設定されている </success_criteria>