prompts/docs/skills/async-fastapi-sqlmodel/SKILL.md

name, description, x-personal-mcp

name	description	x-personal-mcp
async-fastapi-sqlmodel	Explain and apply async database principles for FastAPI, SQLAlchemy 2.x, and SQLModel. Use when: learning or reviewing cached AsyncEngine and session-factory lifecycles, AsyncSession scopes and injection, FastAPI lifespan and yield dependencies, transaction boundaries, concurrency safety, implicit ORM I/O, pooling, testing, or SQLModel integration.	id version tags capabilities async-fastapi-sqlmodel 1.2.0 fastapi sqlalchemy sqlmodel async asyncio database transactions resource-lifecycle architecture resource://skills/async-fastapi-sqlmodel/document

Async FastAPI, SQLAlchemy, and SQLModel

Use this skill to explain how an async database layer works, why the recommended patterns exist, and how to evaluate code against them. Teach the runtime model before suggesting implementation changes.

Primary targets: PostgreSQL with asyncpg and SQLite with aiosqlite.

Engine and session mechanics mirror the nicegui-db template repository. Treat that template as the implementation baseline, then explain the rationale, lifecycle constraints, and tradeoffs behind its cached engines, session factories, context managers, dependency wiring, and with_session decorator. Source-specific claims in the references link to the reviewed template commit so behavior remains auditable as the template evolves.

When to Use

• Explain an async engine, session factory, session, connection, or transaction.
• Review FastAPI lifespan or dependency-based database management.
• Diagnose shared-session concurrency, implicit I/O, cleanup, or transaction problems.
• Compare SQLModel's model conveniences with SQLAlchemy's async runtime APIs.
• Decide whether a context manager, AsyncExitStack, eager loading, pooling option, or explicit transaction is appropriate.

Outcome

Produce a focused technical explanation that:

• Defines the objects involved and identifies who owns each one.
• Traces acquisition, use, transaction behavior, and cleanup.
• Separates required invariants from defaults and situational choices.
• Explains failure modes and concurrency consequences.
• Uses a minimal canonical pattern when code clarifies the mechanics.
• Links claims to the relevant reference and upstream documentation.

Do not default to producing a project plan. Give sequencing advice only when the user explicitly asks for implementation steps.

Mental Model

Keep three ownership scopes distinct:

Scope	Object	Purpose	Typical owner
Application process	Cached AsyncEngine and lifespan-owned async_sessionmaker	Dialect, connection pool, schema initialization, and repeatable session configuration	FastAPI lifespan
Request or concurrent task	AsyncSession	Mutable ORM identity map and transactional state	A yield dependency or explicit unit of work
Atomic operation	SessionTransaction	Commit all changes together or roll them back together	Service or use-case boundary

The engine is a long-lived factory and pool, not a single database connection. The session is a mutable unit-of-work object, not a concurrency-safe global. A transaction is a consistency boundary, not merely a call to commit().

Core Principles

Match lifetime to ownership

• Resolve one cached AsyncEngine per database URL during the active application lifecycle.
• Enter one owning engine scope per URL; initialize registered SQLModel metadata by default, then dispose the engine and clear cached resolution on exit.
• Configure the application async_sessionmaker inside the engine lifecycle; use the template's cached factory resolver only for standalone helpers that cannot receive the application factory.
• Close each session deterministically with async with or a FastAPI dependency that yields once.

See engine lifecycle and session management.

Isolate mutable session state

An AsyncSession represents one stateful transaction in progress. Never use one session in multiple concurrent tasks, including branches of asyncio.gather(). Give each task its own session. Template-style @with_session functions inject one only when the session argument is omitted; a supplied session remains caller-owned, and explicit None is forwarded unchanged.

See session management.

Make I/O visible

Async ORM code must not unexpectedly issue SQL during ordinary attribute access. Load relationships and deferred columns explicitly with eager loader options such as selectinload(), use awaitable_attrs or refresh() for deliberate fallback loading, and consider lazy="raise" where accidental access should fail fast. expire_on_commit=False is a common async configuration because post-commit expiration can otherwise turn attribute reads into implicit I/O.

See implicit ORM I/O.

Put transactions around business invariants

Use async with session.begin(): when several operations must commit or roll back as one unit. A successful exit flushes and commits; an exception rolls back. Reads still participate in SQLAlchemy's autobegin behavior unless the connection uses true DBAPI autocommit, so describe a path as read-only because of application intent and permissions, not because a session silently has no transaction.

Use begin_nested() only for a real SAVEPOINT requirement and account for backend-specific behavior. In SQLAlchemy 2.x, calling session.commit() commits the outermost transaction, not the current savepoint.

See transaction boundaries.

Keep framework boundaries explicit

FastAPI lifespan owns resources shared by many requests. A dependency with one yield owns request-scoped resources and runs cleanup after use. These are related context-manager mechanisms but solve different lifetime problems.

Use AsyncExitStack when lifespan acquires a variable, conditional, or mixed collection of context-managed resources. It records cleanup as resources are acquired and unwinds callbacks in reverse order. A single engine should use the direct engine context manager; AsyncExitStack is a composition tool, not a requirement.

See FastAPI database integration.

Use SQLModel as the primary modeling layer

Default to SQLModel for table models and API data models in FastAPI applications. A SQLModel table model is also a SQLAlchemy model, and every SQLModel model is also a Pydantic model, so shared base models can reduce schema duplication while preserving access to SQLAlchemy's full ORM.

SQLModel does not replace SQLAlchemy's async engine, session, transaction, or loader mechanics. Its main tutorial currently demonstrates synchronous sessions and its advanced guide still lists comprehensive async documentation as future work. For async applications, combine SQLModel models and statements with SQLAlchemy's AsyncSession APIs. Use SQLAlchemy declarative models only when a concrete unsupported mapping or library constraint justifies the exception.

See SQLModel integration.

Configure from evidence

Pool sizing, overflow, recycle, pre-ping, isolation, statement timeouts, and health checks depend on the driver, database, deployment concurrency, and failure model. Explain defaults and tradeoffs before recommending values. Avoid treating pool checkout as proof that a useful query can succeed.

See observability and resilience.

Test through the production seam

Keep the production engine and session-factory construction path intact in tests. Select a dedicated PostgreSQL, local SQLite, or in-memory SQLite URL at that seam, then override the request-session dependency only for the test lifetime. Use a test-scoped outer transaction with SAVEPOINT-backed session commits when application code calls commit(); it exercises normal transaction behavior while cleanup remains deterministic.

In-memory SQLite is suitable for serial tests. For multiple simultaneous sessions, use a named shared-cache SQLite URL or a temporary file, and retain PostgreSQL integration coverage for PostgreSQL-specific behavior.

See database testing and fixture data.

Reference Map

Concept	Reference
Engine lifecycle and ownership	Engine lifecycle reference
Session factory and scope	Session management reference
Transaction boundaries	Transaction boundaries reference
FastAPI lifespan composition	FastAPI integration reference
FastAPI dependency injection	FastAPI integration reference
Implicit I/O control in ORM	Implicit I/O reference
Observability and resilience	Observability reference
SQLModel-first modeling	SQLModel integration reference
CRUD repository and standalone functions	Basic CRUD reference
Test database selection and fixture data	Database testing reference

Canonical Composition Pattern

The framework-independent primitives live in engine lifecycle, session management, and transaction boundaries. Their canonical FastAPI adaptation, including lifespan state and Annotated dependencies, lives in FastAPI database integration.

For background work that outlives a request, inject the shared factory and create a new session inside that task instead of retaining the request's session.

Explanation Procedure

1. Identify the exact concept or observed behavior in question.
2. Name the owning scope: application, request/task, or transaction.
3. Trace what state the object holds and where actual database I/O can occur.
4. Explain normal entry, successful exit, exceptional exit, and concurrent use.
5. Distinguish an invariant from a recommended default or backend-specific choice.
6. Load only the matching reference documents and cite upstream sources.
7. Show the smallest useful code pattern or contrast when prose is insufficient.
8. End with concrete checks the reader can use to inspect their own code.

When reviewing code, verify:

• The URL uses an asyncio-compatible dialect.
• Engine creation and disposal have one clear owner.
• Every session has a bounded lifetime and is not shared across tasks.
• Transaction boundaries match business invariants and exception behavior.
• Relationship and deferred-column access cannot surprise the event loop with implicit I/O.
• Pool and timeout settings are justified by deployment behavior.
• Tests exercise rollback, cleanup, concurrency, and lifespan behavior where relevant.
• Tests use a dedicated database target and preserve production session mechanics.

Anti-Patterns to Flag

• Creating engines inside request handlers.
• Sharing one AsyncSession across concurrent tasks.
• Implicit commit/rollback behavior with unclear ownership.
• Global mutable session state.
• Lifespan cleanup that depends on implicit garbage collection.
• Treating AsyncExitStack as mandatory for a fixed single resource.
• Treating SQLModel's synchronous tutorial examples as the async runtime pattern.
• Allowing lazy relationship access to hide database I/O.
• Copying pool settings without relating them to worker count and database capacity.

Output Contract

Answer in the shape best suited to the question, usually:

1. Direct explanation.
2. Underlying lifecycle or transaction mechanics.
3. Required invariants and situational tradeoffs.
4. Minimal example or code-review findings when useful.
5. Verification questions and source links.

References

!!! info "Primary sources"

• SQLAlchemy asyncio extension
• SQLAlchemy transaction management
• FastAPI lifespan events
• FastAPI dependencies with yield
• Python AsyncExitStack
• SQLModel session dependency pattern