Routing APIs¶
from sqlspec.config import ReplicaGroup
from sqlspec.core.routing import (
RandomSelector,
ReplicaHealthBreaker,
ReplicaSpec,
RoundRobinSelector,
)
from sqlspec.utils.routing import (
RoutingContext,
RoutingContextPayload,
RoutingEntry,
RoutingScope,
SQLSpecRoutingMiddleware,
sign_primary_pin,
verify_primary_pin,
)
Use Read Replicas for setup and Replica Operations for freshness and failure policy. Context scopes select intent; database roles and policies still govern access and write permission.
RoutingContext.replica() requires a reader and never falls back to the primary. Missing replica groups or exhausted readers raise ReplicaUnavailableError. Automatic read providers retain configured fallback. Outside an active transaction, an explicit replica scope can override a historical primary pin; normal automatic routing remains pinned. A conflicting replica choice during a primary transaction raises an error.
Routing Context and ASGI Middleware¶
RoutingEntry
¶
Immutable routing directive for a logical database bind.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mode
|
RoutingMode
|
Requested routing mode. |
'auto'
|
replica_group
|
str | None
|
Optional replica group name. |
None
|
causal_token
|
str | None
|
Adapter-specific causal consistency token. |
None
|
max_staleness_seconds
|
float | None
|
Maximum configured replica staleness. |
None
|
pinned_by_write
|
bool
|
Whether this directive follows a write. |
False
|
RoutingContextPayload
¶
Immutable snapshot of routing directives indexed by logical bind key.
RoutingScope
¶
Bind a routing snapshot for a synchronous or asynchronous block.
RoutingContext
¶
SQLSpecRoutingMiddleware
¶
Bind ASGI request routing from cookies, headers, then a custom extractor.
sign_primary_pin
¶
Create an expiring HMAC-SHA256 primary pin cookie value bound to bind_key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
secret
|
str | bytes
|
Shared HMAC secret key (non-empty |
required |
ttl_seconds
|
float
|
Positive finite lifetime in seconds before the pin expires. |
5.0
|
bind_key
|
str | None
|
Logical database bind key protected by this pin. |
None
|
causal_token
|
str | None
|
Optional adapter causal token (such as WAL LSN or GTID set). |
None
|
clock
|
Callable[[], float]
|
Wall-clock epoch provider in seconds. |
time
|
Returns:
| Type | Description |
|---|---|
str
|
Cookie-safe ASCII token verifiable with :func: |
verify_primary_pin
¶
Verify an HMAC-signed primary pin cookie value and check expiration and bind key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token
|
Any
|
Raw cookie value supplied by the client; a missing or non-string value is invalid. |
required |
secret
|
str | bytes
|
Shared HMAC secret key (non-empty |
required |
bind_key
|
str | None
|
Logical database bind key expected for this check. |
None
|
clock
|
Callable[[], float]
|
Wall-clock epoch provider in seconds. |
time
|
Returns:
| Type | Description |
|---|---|
tuple[bool, str | None]
|
Tuple |
Replica Specifications, Circuit Breakers, and Selectors¶
ReplicaSpec
¶
Weighted replica configuration with an optional declared staleness bound.
ReplicaHealthBreaker
¶
Passive circuit breaker reserving at most one expired-open probe.
RoundRobinSelector
¶
Smooth weighted round-robin using storage proportional to replica count.
RandomSelector
¶
Weighted random ordering without replacement.