Starlette Extension¶

from sqlspec.extensions.starlette import (
    SQLSpecAsyncService,
    SQLSpecAutocommitMiddleware,
    SQLSpecConfigState,
    SQLSpecManualMiddleware,
    SQLSpecPlugin,
    SQLSpecSyncService,
    get_connection_from_request,
    get_or_create_session,
)

Starlette lifespan management, autocommit and manual transaction ASGI middlewares, and request.state session extraction helpers. See the Starlette Integration Guide for usage examples.

Plugin & State¶

SQLSpecPlugin ¶

SQLSpec integration for Starlette applications.

Provides middleware-based session management, automatic transaction handling, and connection pooling lifecycle management.

init_app ¶

init_app(app)

Initialize Starlette application with SQLSpec.

Validates configuration, wraps lifespan, and adds middleware.

Parameters:

Name	Type	Description	Default
`app`	`Starlette`	Starlette application instance.	required

lifespan ¶

lifespan(app)

Manage connection pool lifecycle.

Parameters:

Name	Type	Description	Default
`app`	`Starlette`	Starlette application instance.	required

Yields:

Type	Description
`AsyncGenerator[None, None]`	None

get_session ¶

get_session(request, key=None)

Get or create database session for request.

Sessions are cached per request to ensure consistency.

Parameters:

Name	Type	Description	Default
`request`	`Request`	Starlette request instance.	required
`key`	`str \| None`	Optional session key to retrieve specific database session.	`None`

Returns:

Type	Description
`Any`	Database session (driver instance).

get_connection ¶

get_connection(request, key=None)

Get database connection from request state.

Parameters:

Name	Type	Description	Default
`request`	`Request`	Starlette request instance.	required
`key`	`str \| None`	Optional session key to retrieve specific database connection.	`None`

Returns:

Type	Description
`Any`	Database connection object.

SQLSpecConfigState ¶

Internal state for each database configuration.

Tracks all configuration parameters needed for middleware and session management.

config ¶

config

connection_key ¶

connection_key

pool_key ¶

pool_key

session_key ¶

session_key

commit_mode ¶

commit_mode

extra_commit_statuses ¶

extra_commit_statuses

extra_rollback_statuses ¶

extra_rollback_statuses

disable_di ¶

disable_di

enable_correlation_middleware ¶

enable_correlation_middleware = False

correlation_header ¶

correlation_header = 'x-request-id'

correlation_headers ¶

correlation_headers = None

auto_trace_headers ¶

auto_trace_headers = True

enable_sqlcommenter_middleware ¶

enable_sqlcommenter_middleware = True

sqlcommenter_framework ¶

sqlcommenter_framework = 'starlette'

should_commit ¶

should_commit(status_code)

Return whether a response status should trigger a commit.

should_rollback ¶

should_rollback(status_code)

Return whether a response status should trigger a rollback.

ASGI Transaction Middlewares¶

SQLSpecAutocommitMiddleware ¶

Bases: BaseHTTPMiddleware

Middleware for autocommit transaction mode.

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

config_state ¶

config_state = config_state

dispatch ¶

dispatch(request, call_next)

Process request with autocommit transaction mode.

Parameters:

Name	Type	Description	Default
`request`	`Request`	Incoming HTTP request.	required
`call_next`	`Any`	Next middleware or route handler.	required

Returns:

Type	Description
`Any`	HTTP response.

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.

config_state ¶

config_state = config_state

dispatch ¶

dispatch(request, call_next)

Process request with manual transaction mode.

Parameters:

Name	Type	Description	Default
`request`	`Request`	Incoming HTTP request.	required
`call_next`	`Any`	Next middleware or route handler.	required

Returns:

Type	Description
`Any`	HTTP response.

Request Session Helpers¶

get_or_create_session ¶

get_or_create_session(request, config_state)

Get or create database session for request.

Sessions are cached per request to ensure the same session instance is returned for multiple calls within the same request.

Parameters:

Name	Type	Description	Default
`request`	`Request`	Starlette request instance.	required
`config_state`	`SQLSpecConfigState`	Configuration state for the database.	required

Returns:

Type	Description
`Any`	Database session (driver instance).

get_connection_from_request ¶

get_connection_from_request(request, config_state)

Get database connection from request state.

Parameters:

Name	Type	Description	Default
`request`	`Request`	Starlette request instance.	required
`config_state`	`SQLSpecConfigState`	Configuration state for the database.	required

Returns:

Type	Description
`Any`	Database connection object.