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

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.