FastAPI Extension¶

from sqlspec.extensions.fastapi import (
    DependencyDefaults,
    FieldNameType,
    FilterConfig,
    SQLSpecAsyncService,
    SQLSpecAutocommitMiddleware,
    SQLSpecManualMiddleware,
    SQLSpecPlugin,
    SQLSpecSyncService,
    provide_filters,
)

FastAPI lifespan plugin, request-scoped Depends() session/connection providers, and declarative query-parameter filter dependency builders. See the FastAPI Integration Guide for usage examples.

Plugin & Middlewares¶

SQLSpecPlugin ¶

Bases: SQLSpecPlugin

SQLSpec integration for FastAPI applications.

Extends Starlette integration with dependency injection helpers for FastAPI's Depends() system.

provide_session ¶

provide_session(key=None)

Create dependency factory for session injection.

Returns a callable that can be used with FastAPI's Depends() to inject a database session into route handlers.

Parameters:

Name	Type	Description	Default
`key`	`str \| type[AsyncDatabaseConfig \| SyncDatabaseConfig] \| AsyncDatabaseConfig \| SyncDatabaseConfig \| None`	Optional session key (str), config type for type narrowing, or None.	`None`

Returns:

Type	Description
`Callable[[Request], AsyncDriverAdapterBase \| SyncDriverAdapterBase]`	Dependency callable for FastAPI Depends().

provide_async_session ¶

provide_async_session(key=None)

Create dependency factory for async session injection.

Type-narrowed version of provide_session() that returns AsyncDriverAdapterBase. Useful when using string keys and you know the config is async.

Parameters:

Name	Type	Description	Default
`key`	`str \| None`	Optional session key for multi-database configurations.	`None`

Returns:

Type	Description
`Callable[[Request], AsyncDriverAdapterBase]`	Dependency callable that returns AsyncDriverAdapterBase.

provide_sync_session ¶

provide_sync_session(key=None)

Create dependency factory for sync session injection.

Type-narrowed version of provide_session() that returns SyncDriverAdapterBase. Useful when using string keys and you know the config is sync.

Parameters:

Name	Type	Description	Default
`key`	`str \| None`	Optional session key for multi-database configurations.	`None`

Returns:

Type	Description
`Callable[[Request], SyncDriverAdapterBase]`	Dependency callable that returns SyncDriverAdapterBase.

provide_connection ¶

provide_connection(key=None)

Create dependency factory for connection injection.

Returns a callable that can be used with FastAPI's Depends() to inject a database connection into route handlers.

Parameters:

Name	Type	Description	Default
`key`	`str \| type[AsyncDatabaseConfig \| SyncDatabaseConfig] \| AsyncDatabaseConfig \| SyncDatabaseConfig \| None`	Optional session key (str), config type for type narrowing, or None.	`None`

Returns:

Type	Description
`Callable[[Request], Any]`	Dependency callable for FastAPI Depends().

provide_async_connection ¶

provide_async_connection(key=None)

Create dependency factory for async connection injection.

Type-narrowed version of provide_connection() for async connections. Useful when using string keys and you know the config is async.

Parameters:

Name	Type	Description	Default
`key`	`str \| None`	Optional session key for multi-database configurations.	`None`

Returns:

Type	Description
`Callable[[Request], Any]`	Dependency callable for async connection.

provide_sync_connection ¶

provide_sync_connection(key=None)

Create dependency factory for sync connection injection.

Type-narrowed version of provide_connection() for sync connections. Useful when using string keys and you know the config is sync.

Parameters:

Name	Type	Description	Default
`key`	`str \| None`	Optional session key for multi-database configurations.	`None`

Returns:

Type	Description
`Callable[[Request], Any]`	Dependency callable for sync connection.

provide_filters ¶

provide_filters(config, dep_defaults=None)

Create filter dependency for FastAPI routes.

Dynamically generates a FastAPI dependency function that parses query parameters into SQLSpec filter objects. The returned callable can be used with FastAPI's Depends() for automatic filter injection.

Parameters:

Name	Type	Description	Default
`config`	`FilterConfig`	Filter configuration specifying which filters to enable.	required
`dep_defaults`	`DependencyDefaults \| None`	Optional dependency defaults for customization.	`None`

Returns:

Type	Description
`Callable[..., list[FilterTypes]]`	Callable for use with Depends() that returns list of filters.

SQLSpecAutocommitMiddleware ¶

Bases: BaseHTTPMiddleware

Middleware for autocommit transaction mode.

Acquires connection, commits on success status codes, rollbacks on error status codes.

SQLSpecManualMiddleware ¶

Bases: BaseHTTPMiddleware

Middleware for manual transaction mode.

Acquires connection from pool, stores in request.state, releases after request. No automatic commit or rollback - user code must handle transactions.

Filter Dependency Providers¶

provide_filters ¶

provide_filters(config, dep_defaults=DEPENDENCY_DEFAULTS)

Create FastAPI dependency provider for filters based on configuration.

This function dynamically generates a FastAPI dependency function that parses query parameters into SQLSpec filter objects.

Parameters:

Name	Type	Description	Default
`config`	`FilterConfig`	Filter configuration specifying which filters to enable.	required
`dep_defaults`	`DependencyDefaults`	Dependency defaults for filter configuration.	`DEPENDENCY_DEFAULTS`

Returns:

Type	Description
`Callable[..., list[FilterTypes]]`	A FastAPI dependency callable that returns list of filters.

FilterConfig ¶

Bases: TypedDict

Configuration for generated FastAPI filter dependencies.

All keys are optional. A filter dependency is created only for each enabled key. Field names are SQL-facing allowlist values; generated query parameter names and order-by aliases remain API-facing.

Attributes:

Name	Type	Description
`id_filter`	`NotRequired[type[UUID \| int \| str]]`	Type of ID filter to enable. When set, creates an `ids` collection filter.
`id_field`	`NotRequired[str]`	SQL-facing field name for ID filtering. Defaults to `"id"`.
`sort_field`	`NotRequired[SortField]`	Allowed SQL-facing field or fields for `orderBy` sorting.
`sort_field_aliases`	`NotRequired[dict[str, str]]`	Additional API-facing `orderBy` aliases mapped to configured `sort_field` values.
`sort_field_camelize`	`NotRequired[bool]`	Whether to accept camel-case aliases for configured sort fields. Defaults to `True`.
`sort_order`	`NotRequired[SortOrder]`	Default sort order. Defaults to `"desc"`.
`pagination_type`	`NotRequired[Literal['limit_offset', 'cursor']]`	Pagination strategy to enable: `"limit_offset"` or `"cursor"`.
`cursor_keys`	`NotRequired[CursorKeys]`	Field names, (field, direction) pairs, or CursorKey values. The last key must be unique per row.
`cursor_secret`	`NotRequired[str \| bytes]`	Secret enabling HMAC-SHA256 signed cursors.
`pagination_size`	`NotRequired[int]`	Default page size for limit/offset or cursor pagination.
`pagination_max_size`	`NotRequired[int]`	Largest page size a client may request. Defaults to `1000`.
`search`	`NotRequired[str \| set[str] \| list[str]]`	SQL-facing field or fields to search. Strings may be comma-separated.
`search_ignore_case`	`NotRequired[bool]`	Whether search filtering is case-insensitive. Defaults to `False`.
`created_at`	`NotRequired[bool]`	Whether to enable `created_at` before/after range filtering.
`updated_at`	`NotRequired[bool]`	Whether to enable `updated_at` before/after range filtering.
`not_in_fields`	`NotRequired[FieldNameType \| set[FieldNameType] \| list[str \| FieldNameType]]`	Field or fields that support `NOT IN` collection filtering.
`in_fields`	`NotRequired[FieldNameType \| set[FieldNameType] \| list[str \| FieldNameType]]`	Field or fields that support `IN` collection filtering.
`null_fields`	`NotRequired[str \| set[str] \| list[str]]`	Field or fields that support `IS NULL` filtering.
`not_null_fields`	`NotRequired[str \| set[str] \| list[str]]`	Field or fields that support `IS NOT NULL` filtering.
`boolean_fields`	`NotRequired[str \| set[str] \| list[str]]`	Field or fields that support boolean filtering.
`choice_fields`	`NotRequired[ChoiceField \| set[ChoiceField] \| list[str \| ChoiceField]]`	Field or fields that support choices filtering.

DependencyDefaults ¶

Default values for dependency generation.