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.
init_app
¶
Initialize Sanic application with SQLSpec.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
app
|
Sanic[Any, Any]
|
Sanic application instance. |
required |
get_config
¶
Return a registered database configuration by identifier, or the sole configuration when omitted.
set_request_tenant
¶
Store an authorized tenant receipt on a Sanic request.ctx.
get_session
¶
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 or create database session asynchronously, acquiring deferred tenant leases on demand.
get_connection
¶
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 |
get_connection_async
¶
Get the request connection asynchronously, checking it out on first access.
get_db_replica_session
¶
Return the request's lazy replica session.
get_db_replica_session_async
¶
Open and return the request's lazy replica session.
get_replica_connection
¶
Return the request's lazy replica connection.
get_replica_connection_async
¶
Open and return the request's lazy replica connection.
get_db_routing_session
¶
Return the request's lazy routing session.
get_db_routing_session_async
¶
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.
Request Context Helpers¶
get_or_create_db_session
¶
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 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
¶
Store an authorized tenant receipt on a Sanic request.ctx.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
Any
|
Sanic request instance (or |
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 |
None
|
Returns:
| Type | Description |
|---|---|
TenantContextPayload
|
The immutable |
tenant_bypass
¶
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. |