dorm.contrib.lag_router

Lag-aware read replica router.

See Lag-aware read routing for recipes.

API

dorm.contrib.lag_router.LagAwareReadRouter

Database router that consults each replica's lag before routing a read.

Parameters:

Name	Type	Description	Default
primary	str	alias of the writeable primary.	'default'
replicas	list[str]	list of read-replica aliases.	required
max_lag_seconds	float	replicas with lag above this threshold are considered unhealthy and skipped. Default 2.0.	2.0
cache_seconds	float	how long to cache a replica's lag reading before re-checking. Default 5.0.	5.0
rng	Random | None	optional pre-seeded random.Random for deterministic shuffling in tests.	None

__init__(*, primary: str = 'default', replicas: list[str], max_lag_seconds: float = 2.0, cache_seconds: float = 5.0, failure_threshold: int = 3, cooldown_seconds: float = 30.0, rng: random.Random | None = None) -> None

failure_threshold consecutive probe failures opens a circuit-breaker for cooldown_seconds per replica. While the breaker is open, the router skips the alias outright (no probe) — saves the cost of re-discovering a dead replica every cache window. cooldown_seconds=0 disables the breaker.

db_for_read(model, **hints) -> str

Pick a healthy replica or fall back to primary.

snapshot() -> dict[str, dict[str, Any]]

Return a snapshot of every replica's last-known state.

Useful in a Prometheus exporter or a debug endpoint::

GET /debug/lag → {"replica_1": {"lag": 0.4, "healthy": true}, ...}

reset() -> None

Drop the lag cache. Forces a fresh probe on the next call.