Skip to content

Commit e2cc25e

Browse files
authored
feat: route GET/HEAD requests to an optional read replica (#46)
1 parent 93b9158 commit e2cc25e

7 files changed

Lines changed: 148 additions & 15 deletions

File tree

‎AGENTS.md‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -21,25 +21,27 @@ Python is 3.14, dependencies managed by `uv`. The API is exposed on `:8000`.
2121
**Request flow**: `app/__main__.py` → `granian` → `app.application:build_app` (factory) → `LitestarBootstrapper` from `lite-bootstrap` wraps a `litestar.Litestar` with OpenTelemetry (asyncpg + SQLAlchemy instrumentors), Sentry, CORS, Swagger, etc., based on `Settings.api_bootstrapper_config`.
2222

2323
**Dependency injection** (`app/ioc.py`): `modern_di.Container` is created in `build_app` with the `Dependencies` group and attached via `modern_di_litestar.ModernDIPlugin`. Route handlers receive repositories as parameters; `application.py` declares them with `modern_di_litestar.FromDI(...)` so Litestar resolves them per-request. Provider scopes:
24-
- `database_engine` — application-scoped factory, finalizer disposes the engine
25-
- `session` — request-scoped, finalizer closes the session
24+
- `database_engine` — application-scoped primary engine, finalizer disposes the engine
25+
- `database_replica_engine` — application-scoped replica engine built from `DB_REPLICA_DSN`, or `None` when it is unset
26+
- `dynamic_engine` — request-scoped; `choose_sa_engine` returns the replica for `GET`/`HEAD` requests when one is configured, the primary otherwise (including when there is no request). GET handlers must not write, and a read right after a write may see replica lag
27+
- `session` — request-scoped, bound to `dynamic_engine`, finalizer closes the session
2628
- `*_repository` — request-scoped, depend on `session`, configured with `auto_commit=True` (advanced-alchemy commits on success / rolls back on exception)
2729

2830
**Persistence**: Models inherit `advanced_alchemy.base.BigIntAuditBase` (gives `id: BigInt`, `created_at`, `updated_at`). Metadata is shared with `orm.DeclarativeBase.metadata` in `app/models.py` so Alembic autogen sees everything. Repositories are `SQLAlchemyAsyncRepositoryService[Model]` with a nested `BaseRepository(SQLAlchemyAsyncRepository[Model])`. Custom `CustomAsyncSession` in `app/resources/db.py` overrides `close()` so test transactions are not actually closed when the session is bound to an `AsyncConnection` — this is what makes the per-test rollback fixture work.
2931

30-
**Test isolation** (`tests/conftest.py`): `db_session` fixture opens a connection, starts a transaction, starts a SAVEPOINT, then **overrides** `Dependencies.database_engine` in the DI container to return that connection. All requests in the test reuse this connection; the outer transaction is rolled back in teardown, so DB state is clean between tests with no truncation needed. `app` and `client` fixtures build the real app and run it through `httpx.ASGITransport` + `asgi_lifespan.LifespanManager`. Polyfactory `SQLAlchemyFactory` is wired up via `set_async_session_in_base_sqlalchemy_factory`.
32+
**Test isolation** (`tests/conftest.py`): `db_session` fixture opens a connection, starts a transaction, starts a SAVEPOINT, then **overrides** `Dependencies.dynamic_engine` in the DI container to return that connection. All requests in the test reuse this connection; the outer transaction is rolled back in teardown, so DB state is clean between tests with no truncation needed. `app` and `client` fixtures build the real app and run it through `httpx.ASGITransport` + `asgi_lifespan.LifespanManager`. Polyfactory `SQLAlchemyFactory` is wired up via `set_async_session_in_base_sqlalchemy_factory`.
3133

3234
**Migrations**: `migrations/env.py` reads `app.models.METADATA` and rewrites the DSN driver from `postgresql+asyncpg` → `postgresql` (Alembic uses sync psycopg2). Always run autogen against an upgraded DB — `just migration` enforces this.
3335

34-
**Settings** (`app/settings.py`): `pydantic_settings.BaseSettings` reads from env vars (see `docker-compose.yml` for `SERVICE_DEBUG`, `SERVICE_ENVIRONMENT`, `DB_DSN`). `api_bootstrapper_config` builds the `LitestarConfig` consumed by `lite-bootstrap`.
36+
**Settings** (`app/settings.py`): `pydantic_settings.BaseSettings` reads from env vars (see `docker-compose.yml` for `SERVICE_DEBUG`, `SERVICE_ENVIRONMENT`, `DB_DSN`; `DB_REPLICA_DSN` is optional). `api_bootstrapper_config` builds the `LitestarConfig` consumed by `lite-bootstrap`.
3537

3638
## Conventions
3739

3840
- Routes live in `app/api/`, one module per resource (`decks.py`, `cards.py`), each exposing its own `ROUTER` (`litestar.Router`, prefix `/api`). `application.build_app` registers them all via `route_handlers=[decks.ROUTER, cards.ROUTER]`. Add a new resource by creating `app/api/<name>.py`, defining handlers + a `ROUTER`, and adding it to that list.
3941
- Pydantic schemas in `app/schemas.py` use `from_attributes=True` (via `Base`) so they validate directly from ORM instances (`schemas.X.model_validate(orm_instance)`). Collection responses go through `Collection[T].from_models(...)` (e.g. `schemas.Decks`, `schemas.Cards`).
4042
- Deck responses are deliberately two-shaped: `list_decks`/`create_deck`/`update_deck` return the light `schemas.Deck` (no `cards`), while `get_deck` returns `schemas.DeckWithCards`. The split mirrors loading — lists use `noload` (no cards query), detail uses `selectinload` via `fetch_with_cards` — so the type states exactly what each endpoint loads.
4143
- Domain exceptions: register handlers in `application.build_app`'s `exception_handlers` dict (see `DuplicateKeyError` → `exceptions.duplicate_key_error_handler`). For per-handler 404s the code raises `litestar.exceptions.HTTPException` directly.
42-
- `ruff` is configured with `select = ["ALL"]` and a line length of 120 — expect strict lint. Type-check with `ty`; suppressions already exist for `invalid-argument-type` around `LifespanManager` / `ASGITransport` / DTO list construction.
44+
- `ruff` is configured with `select = ["ALL"]` and a line length of 120 — expect strict lint. `app/resources/` is exempt from the `TC` rules because modern-di resolves DI creator annotations at runtime. Type-check with `ty`; suppressions already exist for `invalid-argument-type` around `LifespanManager` / `ASGITransport` / DTO list construction.
4345

4446
## Agent skills
4547

‎app/ioc.py‎

Lines changed: 25 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,37 @@
11
from modern_di import Group, Scope, providers
22

33
from app.repositories import CardsRepository, DecksRepository
4-
from app.resources.db import close_sa_engine, close_session, create_sa_engine, create_session
4+
from app.resources.db import (
5+
choose_sa_engine,
6+
close_sa_engine,
7+
close_session,
8+
create_primary_sa_engine,
9+
create_replica_sa_engine,
10+
create_session,
11+
)
512

613

714
class Dependencies(Group):
815
database_engine = providers.Factory(
9-
creator=create_sa_engine, cache=providers.CacheSettings(finalizer=close_sa_engine)
16+
creator=create_primary_sa_engine,
17+
cache=providers.CacheSettings(finalizer=close_sa_engine),
18+
bound_type=None,
19+
)
20+
database_replica_engine = providers.Factory(
21+
creator=create_replica_sa_engine,
22+
cache=providers.CacheSettings(finalizer=close_sa_engine),
23+
bound_type=None,
24+
)
25+
dynamic_engine = providers.Factory(
26+
scope=Scope.REQUEST,
27+
creator=choose_sa_engine,
28+
kwargs={"primary_engine": database_engine, "replica_engine": database_replica_engine},
1029
)
1130
session = providers.Factory(
12-
scope=Scope.REQUEST, creator=create_session, cache=providers.CacheSettings(finalizer=close_session)
31+
scope=Scope.REQUEST,
32+
creator=create_session,
33+
cache=providers.CacheSettings(finalizer=close_session),
34+
kwargs={"engine": dynamic_engine},
1335
)
1436

1537
decks_repository = providers.Factory(

‎app/resources/db.py‎

Lines changed: 29 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
import logging
33
import typing
44

5+
import litestar
6+
from sqlalchemy.engine.url import URL, make_url
57
from sqlalchemy.ext import asyncio as sa
68

79
from app.settings import settings
@@ -10,9 +12,12 @@
1012
logger = logging.getLogger(__name__)
1113

1214

13-
def create_sa_engine() -> sa.AsyncEngine:
15+
REPLICA_METHODS: typing.Final = frozenset({"GET", "HEAD"})
16+
17+
18+
def create_sa_engine(url: URL) -> sa.AsyncEngine:
1419
return sa.create_async_engine(
15-
url=settings.db_dsn_parsed,
20+
url=url,
1621
echo=settings.service_debug,
1722
echo_pool=settings.service_debug,
1823
pool_size=settings.db_pool_size,
@@ -21,8 +26,28 @@ def create_sa_engine() -> sa.AsyncEngine:
2126
)
2227

2328

24-
async def close_sa_engine(engine: sa.AsyncEngine) -> None:
25-
await engine.dispose()
29+
def create_primary_sa_engine() -> sa.AsyncEngine:
30+
return create_sa_engine(settings.db_dsn_parsed)
31+
32+
33+
def create_replica_sa_engine() -> sa.AsyncEngine | None:
34+
return create_sa_engine(make_url(settings.db_replica_dsn)) if settings.db_replica_dsn else None
35+
36+
37+
async def close_sa_engine(engine: sa.AsyncEngine | None) -> None:
38+
if engine:
39+
await engine.dispose()
40+
41+
42+
def choose_sa_engine(
43+
*,
44+
primary_engine: sa.AsyncEngine,
45+
replica_engine: sa.AsyncEngine | None,
46+
request: litestar.Request[typing.Any, typing.Any, typing.Any] | None = None,
47+
) -> sa.AsyncEngine:
48+
if replica_engine and request and request.method in REPLICA_METHODS:
49+
return replica_engine
50+
return primary_engine
2651

2752

2853
def create_session(engine: sa.AsyncEngine) -> sa.AsyncSession:

‎app/settings.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ class Settings(pydantic_settings.BaseSettings):
1111
log_level: str = "info"
1212

1313
db_dsn: str = "postgresql+asyncpg://postgres:password@db/postgres"
14+
db_replica_dsn: str = ""
1415
db_pool_size: int = 5
1516
db_max_overflow: int = 0
1617
db_pool_pre_ping: bool = True

‎pyproject.toml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,9 @@ isort.lines-after-imports = 2
6767
isort.no-lines-before = ["standard-library", "local-folder"]
6868

6969
[tool.ruff.lint.extend-per-file-ignores]
70+
"app/resources/*.py" = [
71+
"TC", # modern-di reads DI creator annotations at runtime
72+
]
7073
"tests/*.py" = [
7174
"S101", # allow asserts
7275
]

‎tests/conftest.py‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
from app import ioc
1111
from app.application import build_app
12-
from app.resources.db import create_sa_engine
12+
from app.resources.db import create_primary_sa_engine
1313

1414

1515
if typing.TYPE_CHECKING:
@@ -44,10 +44,10 @@ async def di_container(app: litestar.Litestar) -> typing.AsyncIterator[modern_di
4444

4545
@pytest.fixture
4646
async def db_session(di_container: modern_di.Container) -> typing.AsyncIterator[AsyncSession]:
47-
engine = create_sa_engine()
47+
engine = create_primary_sa_engine()
4848
connection = await engine.connect()
4949
transaction = await connection.begin()
50-
di_container.override(ioc.Dependencies.database_engine, connection)
50+
di_container.override(ioc.Dependencies.dynamic_engine, connection)
5151

5252
try:
5353
yield AsyncSession(

‎tests/test_db_routing.py‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
import typing
2+
3+
import litestar
4+
import pytest
5+
from litestar.enums import HttpMethod
6+
from litestar.testing import RequestFactory
7+
from modern_di import Scope
8+
9+
from app import ioc
10+
from app.resources.db import create_replica_sa_engine, create_sa_engine
11+
from app.settings import settings
12+
13+
14+
if typing.TYPE_CHECKING:
15+
import modern_di
16+
from sqlalchemy.ext.asyncio import AsyncEngine
17+
18+
19+
@pytest.fixture
20+
async def primary_engine(di_container: modern_di.Container) -> typing.AsyncIterator[AsyncEngine]:
21+
engine = create_sa_engine(settings.db_dsn_parsed)
22+
di_container.override(ioc.Dependencies.database_engine, engine)
23+
yield engine
24+
await engine.dispose()
25+
26+
27+
@pytest.fixture
28+
async def replica_engine(di_container: modern_di.Container) -> typing.AsyncIterator[AsyncEngine]:
29+
engine = create_sa_engine(settings.db_dsn_parsed)
30+
di_container.override(ioc.Dependencies.database_replica_engine, engine)
31+
yield engine
32+
await engine.dispose()
33+
34+
35+
def build_request(method: HttpMethod) -> litestar.Request[typing.Any, typing.Any, typing.Any]:
36+
request = RequestFactory().get("/")
37+
request.scope["method"] = method
38+
return request
39+
40+
41+
def resolve_engine(di_container: modern_di.Container, method: HttpMethod | None) -> AsyncEngine:
42+
context = {litestar.Request: build_request(method)} if method else None
43+
with di_container.build_child_container(scope=Scope.REQUEST, context=context) as request_container:
44+
return request_container.resolve_provider(ioc.Dependencies.dynamic_engine)
45+
46+
47+
@pytest.mark.parametrize("method", [HttpMethod.GET, HttpMethod.HEAD])
48+
def test_safe_methods_use_replica(
49+
di_container: modern_di.Container, primary_engine: AsyncEngine, replica_engine: AsyncEngine, method: HttpMethod
50+
) -> None:
51+
engine = resolve_engine(di_container, method)
52+
assert engine is replica_engine
53+
assert engine is not primary_engine
54+
55+
56+
@pytest.mark.parametrize("method", [HttpMethod.POST, HttpMethod.PUT, HttpMethod.PATCH, HttpMethod.DELETE])
57+
def test_write_methods_use_primary(
58+
di_container: modern_di.Container, primary_engine: AsyncEngine, replica_engine: AsyncEngine, method: HttpMethod
59+
) -> None:
60+
engine = resolve_engine(di_container, method)
61+
assert engine is primary_engine
62+
assert engine is not replica_engine
63+
64+
65+
@pytest.mark.usefixtures("replica_engine")
66+
def test_no_request_uses_primary(di_container: modern_di.Container, primary_engine: AsyncEngine) -> None:
67+
assert resolve_engine(di_container, None) is primary_engine
68+
69+
70+
def test_no_replica_configured_uses_primary(di_container: modern_di.Container, primary_engine: AsyncEngine) -> None:
71+
assert di_container.resolve_provider(ioc.Dependencies.database_replica_engine) is None
72+
assert resolve_engine(di_container, HttpMethod.GET) is primary_engine
73+
74+
75+
async def test_replica_engine_built_from_replica_dsn(monkeypatch: pytest.MonkeyPatch) -> None:
76+
monkeypatch.setattr(settings, "db_replica_dsn", "postgresql+asyncpg://postgres:password@replica/postgres")
77+
engine = create_replica_sa_engine()
78+
assert engine
79+
assert engine.url.host == "replica"
80+
await engine.dispose()

0 commit comments

Comments
 (0)