Sqlalchemy Postgres

This is a comprehensive setup guide for building database layers with SQLAlchemy 2.0, Pydantic, and PostgreSQL. It walks you through the modern async stack with proper type safety using Mapped[] annotations, separating ORM models from Pydantic schemas, and implementing the repository pattern. The workflows cover everything from initial setup to migrations with Alembic, and it pushes you toward production-ready patterns like connection pooling and async sessions with FastAPI. The auto-detection is smart enough to kick in when you mention database-related terms. Honestly, this is less of a quick reference and more of an opinionated project structure, which is exactly what you want when starting a new FastAPI project with a database.

skills.sh installs: 507
GitHub stars: 17
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add cfircoo/claude-code-toolkit --skill sqlalchemy-postgres --agent claude-code

Installs into .claude/skills of the current project.

Files

<essential_principles>

SQLAlchemy 2.0 + Pydantic + PostgreSQL Best Practices

This skill provides expert guidance for building production-ready database layers.

Stack

SQLAlchemy 2.0 with async support (asyncpg driver)
Pydantic v2 for validation and serialization
Alembic for migrations
PostgreSQL only

Core Principles

1. Separation of Concerns

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

2. Type Safety First Always use SQLAlchemy 2.0 style with Mapped[] type annotations:

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. Async by Default Use async engine and sessions for FastAPI:

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

SKILL.md on GitHub

Details

Repository: github.com/cfircoo/claude-code-toolkit
Categories: Backend & APIs, Python, Databases
First seen: Jun 3, 2026