perf: create a deck in one INSERT ... ON CONFLICT DO UPDATE RETURNING

The no-op update on idempotency_key returns the existing row on a replay, and a concurrent request with the same key waits on the row lock instead of failing on the unique constraint.

Author: lesnik512

AGENTS.md

@@ -74,7 +74,7 @@ class ListDecksUseCase:
 - Every query runs inside `async with self.transaction:`. A query before the block leaves the session in a failed transaction on a lost connection, and the retry then fails with `PendingRollbackError`.
 - Commit before leaving the block, reads included, and before any early return. Otherwise `__aexit__` rolls back, which expires the loaded rows.
 - A retry runs the whole use case again. If the connection drops during `COMMIT`, the write may already have landed. A write that creates rows needs something that makes the second run harmless:
-  - `CreateDeckUseCase` takes a client-generated `idempotency_key` (`schemas.DeckCreate`, unique on `decks`). It looks the key up inside the transaction and returns the existing deck when it finds one, so a retry, or a client resending the request, gets the first deck back. Two concurrent requests with one key can still both miss the lookup; the second then fails on the unique constraint as a duplicate-key error.
+  - `CreateDeckUseCase` takes a client-generated `idempotency_key` (`schemas.DeckCreate`, unique on `decks`). `DecksRepository.get_or_create` sends one `INSERT ... ON CONFLICT (idempotency_key) DO UPDATE SET idempotency_key = EXCLUDED.idempotency_key RETURNING *`. On a conflict the no-op update leaves the row as it was and `RETURNING` hands it back (`DO NOTHING` would return no row), so a retry or a client resend gets the first deck. A concurrent request with the same key waits on the row lock and then gets the same deck. advanced-alchemy's own `upsert` and `get_or_upsert` do a SELECT followed by an INSERT, so they cost two round trips and lose that race.
   - `CreateCardsUseCase` relies on the `(deck_id, front)` unique constraint. A replay is rejected as a duplicate-key error rather than creating the cards twice.
   - Updates (`UpdateDeckUseCase`, `UpdateCardsUseCase`) write the same values again, so a replay is harmless.
 

app/repositories.py

@@ -3,12 +3,12 @@
 from advanced_alchemy.repository import SQLAlchemyAsyncRepository
 from advanced_alchemy.service import SQLAlchemyAsyncRepositoryService
 from sqlalchemy import orm
+from sqlalchemy.dialects import postgresql
 
 from app import models, schemas
 
 
 if TYPE_CHECKING:
-    import uuid
     from collections.abc import Sequence
 
 
@@ -18,8 +18,13 @@ class BaseRepository(SQLAlchemyAsyncRepository[models.Deck]):
 
     repository_type = BaseRepository
 
-    async def fetch_by_idempotency_key(self, idempotency_key: uuid.UUID) -> models.Deck | None:
-        return await self.get_one_or_none(idempotency_key=idempotency_key)
+    async def get_or_create(self, data: schemas.DeckCreate) -> models.Deck:
+        statement = postgresql.insert(models.Deck).values(**data.model_dump())
+        statement = statement.on_conflict_do_update(
+            index_elements=[models.Deck.idempotency_key],
+            set_={"idempotency_key": statement.excluded.idempotency_key},
+        )
+        return (await self.repository.session.scalars(statement.returning(models.Deck))).one()
 
     async def fetch_with_cards(self, deck_id: int) -> models.Deck:
         return await self.get_one(

app/use_cases/create_deck.py

@@ -1,4 +1,5 @@
 import dataclasses
+import typing
 
 from db_retry import Transaction, postgres_retry
 
@@ -14,8 +15,6 @@ class CreateDeckUseCase:
     @postgres_retry
     async def __call__(self, *, data: schemas.DeckCreate) -> models.Deck:
         async with self.transaction:
-            deck = await self.decks_repository.fetch_by_idempotency_key(data.idempotency_key)
-            if deck is None:
-                deck = await self.decks_repository.create(data.model_dump())
+            deck: typing.Final = await self.decks_repository.get_or_create(data)
             await self.transaction.commit()
         return deck