SQLAlchemy 2.0+ Patterns (Async · PostgreSQL)

Rules for writing SQLAlchemy 2.0 / 2.1 code where PostgreSQL is the database and async is the execution model. Everything here is 2.0-style — no legacy Column() class attributes, session.query(), or declarative_base().

Project-agnostic: examples use generic names (User, Order). Adapt names to the project; never copy example session names or pool numbers as if they were rules.

Versions: works on SQLAlchemy 2.0 and 2.1 (current release line). On 2.1: Python ≥ 3.11, install sqlalchemy[asyncio] (greenlet is no longer pulled in by default), and always name the driver in the URL (postgresql+asyncpg:// / postgresql+psycopg://). Upgrade notes: references/migration-2.1.md.

Quick Reference Cheatsheet