Skip to content

Sanic Extension

from sqlspec.extensions.sanic import (
    SanicConfigState,
    SQLSpecPlugin,
    get_connection_from_request,
    get_or_create_db_session,
    set_request_tenant,
    tenant_bypass,
)

Sanic server listener and request/response middleware extension for pool lifecycle management, deferred tenant leases, and request.ctx session injection (SQLSpecSyncService and SQLSpecAsyncService are documented in Service Layer). See the Sanic Integration Guide for usage examples.

Plugin & Configuration State

SQLSpecPlugin

SQLSpec integration for Sanic applications.

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

sqlspec

sqlspec

Return the underlying SQLSpec registry.

config

config

Return the registered database configurations.

init_app

init_app(app)

Initialize Sanic application with SQLSpec.

Parameters:

Name Type Description Default
app Sanic[Any, Any]

Sanic application instance.

required

get_config

get_config(name=None)

Return a registered database configuration by identifier, or the sole configuration when omitted.

set_request_tenant

set_request_tenant(request, tenant_id, *, variables=None, key=None)

Store an authorized tenant receipt on a Sanic request.ctx.

get_session

get_session(request, key=None)

Get or create database session for request.

A synchronous configuration checks out the request connection on this call. An asynchronous configuration whose connection is not open yet returns a session that opens it on the first awaited call, so await session.select(...), async for row in session.select_stream(...), and async with session.transaction(): work unchanged.

Parameters:

Name Type Description Default
request Any

Sanic request instance.

required
key Any

Optional session key, bind key, config type, or config instance.

None

Returns:

Type Description
Any

Database session driver instance.

get_session_async

get_session_async(request, key=None)

Get or create database session asynchronously, acquiring deferred tenant leases on demand.

get_connection

get_connection(request, key=None)

Get database connection from request context, checking it out on first access.

Parameters:

Name Type Description Default
request Any

Sanic request instance.

required
key Any

Optional session key, bind key, config type, or config instance.

None

Returns:

Type Description
Any

Database connection object.

Raises:

Type Description
ImproperConfigurationError

The configuration is asynchronous and its connection is not open yet; use await plugin.get_connection_async(request).

get_connection_async

get_connection_async(request, key=None)

Get the request connection asynchronously, checking it out on first access.

get_db_replica_session

get_db_replica_session(request, key=None)

Return the request's lazy replica session.

get_db_replica_session_async

get_db_replica_session_async(request, key=None)

Open and return the request's lazy replica session.

get_replica_connection

get_replica_connection(request, key=None)

Return the request's lazy replica connection.

get_replica_connection_async

get_replica_connection_async(request, key=None)

Open and return the request's lazy replica connection.

get_db_routing_session

get_db_routing_session(request, key=None)

Return the request's lazy routing session.

get_db_routing_session_async

get_db_routing_session_async(request, key=None)

Open and return the request's lazy routing session.

SanicConfigState

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.

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

tenant_extractor

tenant_extractor = None

tenant_receipt_keys

tenant_receipt_keys = field(default=(), init=False, repr=False, compare=False)

enable_correlation_middleware

enable_correlation_middleware = True

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 = 'sanic'

replica_session_key

replica_session_key = 'db_replica_session'

replica_connection_key

replica_connection_key = 'db_replica_connection'

replica_pool_key

replica_pool_key = 'db_replica_pool'

routing_session_key

routing_session_key = None

default_routing_mode

default_routing_mode = 'auto'

enable_routing_middleware

enable_routing_middleware = True

routing_header

routing_header = None
primary_pin_cookie = None

primary_pin_secret

primary_pin_secret = None

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.

Request Context Helpers

get_or_create_db_session

get_or_create_db_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:

Name Type Description Default
request Any

Sanic request instance.

required
config_state SanicConfigState

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 context.

Parameters:

Name Type Description Default
request Any

Sanic request instance.

required
config_state SanicConfigState

Configuration state for the database.

required

Returns:

Type Description
Any

Database connection object.

Raises:

Type Description
ImproperConfigurationError

If SQLSpec request middleware has not stored a connection.

set_request_tenant

set_request_tenant(request, tenant_id, *, variables=None, key=None)

Store an authorized tenant receipt on a Sanic request.ctx.

Parameters:

Name Type Description Default
request Any

Sanic request instance (or request.ctx directly).

required
tenant_id str | UUID | TenantContextPayload

Verified tenant identifier or immutable payload.

required
variables Mapping[str, str] | None

Extra session variables merged into the stored payload.

None
key str | None

Optional configuration session_key, connection_key, or bind_key scoping the receipt to one database configuration.

None

Returns:

Type Description
TenantContextPayload

The immutable TenantContextPayload stored on request.ctx.

tenant_bypass

tenant_bypass(handler)

Mark a route handler as an explicit tenant bypass.

Framework plugins resolve a bypass payload for marked routes, so public routes such as login or health checks can use tenant-enabled sessions without a tenant.

Parameters:

Name Type Description Default
handler Any

Route function or handler object.

required

Returns:

Type Description
Any

The same handler.