SQLSpec Skill

SQLSpec is a type-safe SQL query mapper for Python -- NOT an ORM. It provides flexible connectivity with consistent interfaces across 15+ database adapters. Write raw SQL, use the builder API, or load SQL from files. All statements pass through a sqlglot-powered AST pipeline for validation and dialect conversion.

Match-Your-Framework — read first

sqlspec ships first-party extensions for four web frameworks. If your project uses one of these, jump directly to the matching integration guide and skip the others:

• Litestar — SQLSpecPlugin with full DI, CLI, observability. The rest of this SKILL.md covers Litestar by default; also see references/extensions.md.
• FastAPI → references/fastapi-integration.md — Depends(plugin.provide_session()) DI, Annotated[...] handlers, filter providers.
• Flask → references/flask-integration.md — plugin.init_app(app), pull-based plugin.get_session(), async-via-portal.
• Starlette → references/starlette-integration.md — request.state-based session access, lifespan wrapping, middleware variants.

sqlspec has no first-party Sanic integration — other frameworks are not supported out-of-the-box.

Shared topics that apply to every framework live in references/commit-modes.md (autocommit / manual middleware) and references/multi-database.md (multi-config registry). Read the framework guide first, then those for depth.

The rest of this SKILL.md covers framework-agnostic topics: adapter setup, query builder, driver methods, filters, observability, migrations, the ADK extension, and data-dictionary introspection.