API Reference

The API reference is automatically generated from the docstrings in the code, and is useful for finding out what methods and attributes are available for a given class.

Note

Private methods and attributes are not included in the API reference.

Overview

SQLSpec is organized into several core modules, each serving a specific purpose:

Core Components:

• Base - Main SQLSpec registry and configuration management

• Core - SQL processing (statements, parameters, results, compilation)

• Driver - Base driver classes and mixins for database operations

Database Connectivity:

• Adapters - Database-specific adapters (PostgreSQL, SQLite, DuckDB, etc.)

Query Building:

• Builder - Fluent SQL builder API for programmatic query construction

Framework Integration:

• Extensions - Web framework integrations (Litestar, FastAPI, Flask, etc.)

Quick Navigation

SQLSpec Base

Main entry point for SQLSpec. Configure databases and manage sessions.

Base

Database Adapters

Adapter implementations for PostgreSQL, SQLite, DuckDB, MySQL, Oracle, and more.

Adapters

SQL Builder

Fluent API for building SQL queries programmatically with method chaining.

Builder

Query Stack

Immutable multi-statement execution with native pipelines, sequential fallbacks, and stack-aware telemetry.

Query Stack

Core Components

Statement processing, parameter binding, result handling, and SQL compilation.

Core

Driver System

Base driver classes and mixins for sync/async database operations.

Driver

Framework Extensions

Integration modules for Litestar, FastAPI, Flask, Sanic, and Starlette.

Extensions

Module Organization

SQLSpec follows a layered architecture:

1. User-Facing API (sqlspec.base, sqlspec.builder)

   • SQLSpec - Main registry class

   • SQL Builder - Fluent query construction

2. Adapter Layer (sqlspec.adapters.*)

   • Database-specific configurations

   • Driver implementations

   • Parameter style handling

3. Core Processing (sqlspec.core)

   • SQL statement parsing and validation

   • Parameter binding and conversion

   • Result set processing

   • Statement caching

4. Driver Foundation (sqlspec.driver)

   • Base sync/async drivers

   • Transaction management

   • Query execution mixins

5. Framework Integration (sqlspec.extensions.*)

   • Dependency injection

   • Lifecycle management

   • Framework-specific utilities

Available API References

• Base
• Adapters
• Builder
• Query Stack
• Core
• Driver
• Extensions

Common Workflows

Setting Up a Database:

1. Import adapter config: from sqlspec.adapters.asyncpg import AsyncpgConfig

2. Create SQLSpec instance: sql = SQLSpec()

3. Add configuration: db = sql.add_config(AsyncpgConfig(...))

4. Get session: async with sql.provide_session(db) as session:

Building Queries:

1. Import builder: from sqlspec import sql

2. Chain methods: query = sql.select("*").from_("users").where("active = true")

3. Convert to SQL: stmt = query.to_statement()

4. Execute: result = await session.execute(stmt)

Processing Results:

1. Execute query: result = await session.execute(sql)

2. Get all rows: result.all() (list of dicts)

3. Get one row: result.one() (raises if not exactly one)

4. Get first row: result.get_first() (returns first or None)

5. Map to models: result.all(schema_type=User) or result.one(schema_type=User)

See Also

• Getting Started - Getting started guide

• Usage - Usage documentation

• SQLSpec Example Library - Code examples

• Contributing - Contributing guide

Type Hints and Protocols

SQLSpec makes extensive use of type hints and protocols for type safety:

• sqlspec.protocols - Protocol definitions for runtime type checking

• sqlspec.typing - Type aliases and generic types

• sqlspec.utils.type_guards - Type guard functions

All public APIs are fully typed and compatible with mypy, pyright, and other type checkers.