Starlette

Starlette extension providing middleware-based session management, automatic transaction handling, and connection pooling lifecycle management.

Plugin

class sqlspec.extensions.starlette.SQLSpecPlugin

Bases: object

SQLSpec integration for Starlette applications.

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

Example

from starlette.applications import Starlette from sqlspec import SQLSpec from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.extensions.starlette import SQLSpecPlugin

sqlspec = SQLSpec() sqlspec.add_config(AsyncpgConfig(

bind_key=”default”, connection_config={“dsn”: “postgresql://localhost/mydb”}, extension_config={

“starlette”: {

“commit_mode”: “autocommit”, “session_key”: “db”

}

}

))

app = Starlette() db_ext = SQLSpecPlugin(sqlspec, app)

@app.route(“/users”) async def list_users(request):

db = db_ext.get_session(request) result = await db.execute(“SELECT * FROM users”) return JSONResponse({“users”: result.all()})

__init__(sqlspec, app=None)

Initialize SQLSpec Starlette extension.

Parameters:

• sqlspec (SQLSpec) – Pre-configured SQLSpec instance with registered configs.

• app (Starlette | None) – Optional Starlette application to initialize immediately.

init_app(app)

Initialize Starlette application with SQLSpec.

Validates configuration, wraps lifespan, and adds middleware.

Parameters:

app (Starlette) – Starlette application instance.

Return type:

None

lifespan(app)

Manage connection pool lifecycle.

Parameters:

app (Starlette) – Starlette application instance.

Yields:

None

Return type:

AsyncGenerator[None, None]

get_session(request, key=None)

Get or create database session for request.

Sessions are cached per request to ensure consistency.

Parameters:

• request (Request) – Starlette request instance.

• key (str | None) – Optional session key to retrieve specific database session.

Return type:

Any

Returns:

Database session (driver instance).

get_connection(request, key=None)

Get database connection from request state.

Parameters:

• request (Request) – Starlette request instance.

• key (str | None) – Optional session key to retrieve specific database connection.

Return type:

Any

Returns:

Database connection object.

Middleware

class sqlspec.extensions.starlette.SQLSpecAutocommitMiddleware

Bases: BaseHTTPMiddleware

Middleware for autocommit transaction mode.

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

__init__(app, config_state, include_redirect=False)

Initialize middleware.

Parameters:

• app (Any) – Starlette application instance.

• config_state (SQLSpecConfigState) – Configuration state for this database.

• include_redirect (bool) – If True, commit on 3xx status codes as well.

async dispatch(request, call_next)

Process request with autocommit transaction mode.

Parameters:

• request (Request) – Incoming HTTP request.

• call_next (Any) – Next middleware or route handler.

Return type:

Any

Returns:

HTTP response.

class sqlspec.extensions.starlette.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.

__init__(app, config_state)

Initialize middleware.

Parameters:

• app (Any) – Starlette application instance.

• config_state (SQLSpecConfigState) – Configuration state for this database.

async dispatch(request, call_next)

Process request with manual transaction mode.

Parameters:

• request (Request) – Incoming HTTP request.

• call_next (Any) – Next middleware or route handler.

Return type:

Any

Returns:

HTTP response.

class sqlspec.extensions.starlette.middleware.CorrelationMiddleware

Bases: BaseHTTPMiddleware

Middleware for correlation ID extraction and propagation.

Extracts correlation IDs from request headers (or generates new ones) and propagates them through the request lifecycle via CorrelationContext.

The middleware: 1. Extracts correlation ID from configurable headers 2. Sets it in the CorrelationContext for async/sync access 3. Stores it in request.state.correlation_id 4. Adds X-Correlation-ID header to the response 5. Cleans up the context on request completion

Example

```python from starlette.applications import Starlette from sqlspec.extensions.starlette.middleware import (

CorrelationMiddleware,

)

app = Starlette() app.add_middleware(

CorrelationMiddleware, primary_header=”x-request-id”, auto_trace_headers=True,

__init__(app, *, primary_header='x-request-id', additional_headers=None, auto_trace_headers=True, max_length=128)

Initialize correlation middleware.

Parameters:

• app (Any) – Starlette application instance.

• primary_header (str) – The primary header to check first. Defaults to “x-request-id”.

• additional_headers (tuple[str, ...] | None) – Additional headers to check after the primary header.

• auto_trace_headers (bool) – If True, include standard trace context headers as fallbacks.

• max_length (int) – Maximum length for correlation IDs. Defaults to 128.

async dispatch(request, call_next)

Extract correlation ID and propagate through request lifecycle.

Parameters:

• request (Request) – Incoming HTTP request.

• call_next (Any) – Next middleware or route handler.

Return type:

Response

Returns:

HTTP response with X-Correlation-ID header.

State

class sqlspec.extensions.starlette.SQLSpecConfigState

Bases: object

Internal state for each database configuration.

Tracks all configuration parameters needed for middleware and session management.

__init__(config, connection_key, pool_key, session_key, commit_mode, extra_commit_statuses, extra_rollback_statuses, disable_di, enable_correlation_middleware=False, correlation_header='x-request-id', correlation_headers=None, auto_trace_headers=True)

Helpers

sqlspec.extensions.starlette.get_connection_from_request(request, config_state)

Get database connection from request state.

Parameters:

• request (Request) – Starlette request instance.

• config_state (SQLSpecConfigState) – Configuration state for the database.

Return type:

Any

Returns:

Database connection object.

sqlspec.extensions.starlette.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:

• request (Request) – Starlette request instance.

• config_state (SQLSpecConfigState) – Configuration state for the database.

Return type:

Any

Returns:

Database session (driver instance).