sqlalchemy-postgres

<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

3. Async by Default Use async engine and sessions for FastAPI:

4. Pydantic-SQLAlchemy Bridge Keep models and schemas separate but mappable:

5. Repository Pattern Abstract database operations for testability and clean code. </essential_principles>

1. Setup database layer - Initialize SQLAlchemy + Pydantic + Alembic from scratch
2. Define models - Create SQLAlchemy models with Pydantic schemas
3. Create migration - Generate and manage Alembic migrations
4. Query patterns - Async CRUD, joins, eager loading, optimization
5. Full implementation - Complete database layer for a feature

Auto-detection triggers (use this skill when user mentions):

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

<reference_index>

Domain Knowledge

<workflows_index>

<quick_reference>

File Structure

Essential Imports

Connection String

</quick_reference>

<success_criteria> Database layer is complete when:

• Async engine and session factory configured
• Base model with common fields (id, created_at, updated_at)
• Models use Mapped[] type annotations
• Pydantic schemas with from_attributes=True
• Alembic configured for async
• Repository pattern implemented
• FastAPI dependency for session injection
• Connection pooling configured for production </success_criteria>