Sanic

Sanic extension providing app/request context integration, request-scoped session management, transaction handling, correlation IDs, SQLCommenter, and connection pool lifecycle management.

Configuration

Use sqlspec.config.SanicConfig in extension_config["sanic"]. These settings apply across adapters; no adapter-specific subtype is needed.

class sqlspec.config.SanicConfig

Bases: TypedDict

Configuration options for Sanic SQLSpec extension.

All fields are optional with sensible defaults. Use in extension_config["sanic"].

connection_key: NotRequired[str]

'db_connection'

Type:

Key for storing connection in request.ctx. Default

pool_key: NotRequired[str]

'db_pool'

Type:

Key for storing connection pool in app.ctx. Default

session_key: NotRequired[str]

'db_session'

Type:

Key for storing session in request.ctx. Default

commit_mode: NotRequired[Literal['manual', 'autocommit', 'autocommit_include_redirect']]

'manual'

• manual: No automatic commit/rollback

• autocommit: Commit on 2xx, rollback otherwise

• autocommit_include_redirect: Commit on 2xx-3xx, rollback otherwise

Type:

Transaction commit mode. Default

extra_commit_statuses: NotRequired[set[int]]

Type:

Additional HTTP status codes that trigger commit. Default

extra_rollback_statuses: NotRequired[set[int]]

Type:

Additional HTTP status codes that trigger rollback. Default

disable_di: NotRequired[bool]

False. When True, the Sanic extension will not register request middleware for managing database connections and sessions. Users are responsible for managing the database lifecycle manually via their own DI solution.

Type:

Disable built-in dependency injection. Default

enable_correlation_middleware: NotRequired[bool]

False.

Type:

Enable request correlation ID middleware. Default

correlation_header: NotRequired[str]

X-Request-ID.

Type:

HTTP header to read the request correlation ID from when middleware is enabled. Default

correlation_headers: NotRequired[tuple[str, ...] | list[str]]

Additional HTTP headers to read as correlation ID fallbacks.

auto_trace_headers: NotRequired[bool]

True.

Type:

Read standard trace context headers as correlation ID fallbacks. Default

enable_sqlcommenter_middleware: NotRequired[bool]

True. When the driver's StatementConfig has enable_sqlcommenter=True, the middleware is registered automatically. Set to False to explicitly disable middleware registration.

Type:

Control automatic SQLCommenter middleware registration. Default

sqlcommenter_framework: NotRequired[str]

'sanic'.

Type:

Framework name for SQLCommenter attributes. Default

Plugin

class sqlspec.extensions.sanic.SQLSpecPlugin

Bases: object

SQLSpec integration for Sanic applications.

Provides Sanic-native configuration parsing and request helper methods. Runtime listener and middleware behavior is registered by init_app.

__init__(sqlspec, app=None)

Initialize SQLSpec Sanic extension.

Parameters:

• sqlspec -- Pre-configured SQLSpec instance with registered configs.

• app -- Optional Sanic application to initialize immediately.

init_app(app)

Initialize Sanic application with SQLSpec.

Parameters:

app (Any'))) -- Sanic application instance.

Return type:

None

get_session(request, key=None)

Get or create database session for request.

Parameters:

• request (Any) -- Sanic request instance.

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

Return type:

Any

Returns:

Database session driver instance.

get_connection(request, key=None)

Get database connection from request context.

Parameters:

• request (Any) -- Sanic request instance.

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

Return type:

Any

Returns:

Database connection object.

State

class sqlspec.extensions.sanic.SanicConfigState

Bases: object

Internal state for a Sanic database configuration.

Tracks the keys and behavior needed to bind one SQLSpec config into a Sanic app and its request context.

__post_init__()

Validate transaction status overrides.

Return type:

None

should_commit(status_code)

Return whether a response status should trigger a commit.

Return type:

bool

should_rollback(status_code)

Return whether a response status should trigger a rollback.

Return type:

bool

__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, enable_sqlcommenter_middleware=True, sqlcommenter_framework='sanic')

Helpers

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

Get database connection from request context.

Parameters:

• request (Any) -- Sanic request instance.

• config_state (SanicConfigState) -- Configuration state for the database.

Return type:

Any

Returns:

Database connection object.

Raises:

ImproperConfigurationError -- If SQLSpec request middleware has not stored a connection.

sqlspec.extensions.sanic.get_or_create_session(request, config_state)

Get or create database session for request.

Sessions are cached per request to return the same session instance across multiple calls in one request.

Parameters:

• request (Any) -- Sanic request instance.

• config_state (SanicConfigState) -- Configuration state for the database.

Return type:

Any

Returns:

Database session driver instance.