Units of Work and db()¶

A unit is one Unit of Work: one transaction on one database. It commits when its body succeeds and rolls back on any exception, HTTPException included. Your code never commits: it reads and writes through db(), the session of the running unit, and the framework decides commit or rollback at the unit's end. Everything the unit queued (events, audit rows, post-commit callbacks) commits with it or not at all.

What you get by default, and what you declare¶

Using db()¶

from sandloom.sdk import db


async def create(body: NoteIn, *, author_id: UUID) -> Note:
    note = Note(author_id=author_id, **body.model_dump())   # tenant_id from the bound tenant
    db().add(note)
    await db().flush()   # materialise ids and constraints; never commit()
    return note

• Never call commit() or rollback() on a session in module code (SANDLOOM-C006). Use flush() to get ids and constraint errors early.
• db() is synchronous. Outside any unit it raises UnitOfWorkRequiredError (SANDLOOM-R002).
• In a request the first db() creates the request unit lazily: no connection is checked out until the first statement. A read route that never calls db() uses no connection. Routes may still take the session as a parameter (DbSession, advanced, from sandloom.sdk.web); the unit is then opened eagerly, and on a write route the durable idempotency claim runs before the handler.
• In a contract method db() is the provider unit's session, on the contract pool with its tenant hook (Contracts).
• In a consumer db() is the delivery's unit; a delivery that raises rolls back and is redelivered (Events).
• In a task or script open a unit with open_uow(); inside the block db() returns its session (Background tasks).

open_uow(database=None) opens a unit on the module's primary database, or on a named one. It replaces today's ad-hoc sessions and is the only way to open a unit outside a request, a consumer or a contract.

Ownership: one task per unit¶

A unit belongs to one asyncio task. In a request the owner is the handler task, the task that runs the dependencies and the endpoint.

• db() from another task is refused with ConcurrentSessionUseError (SANDLOOM-R013). Child tasks (asyncio.create_task, asyncio.gather) inherit the context, so the common mistake is caught at the child's first db(). A child that calls db() before the parent did creates nothing: the parent's later db() creates the request unit and owns it.
• A child task that needs the database opens its own unit:

from sandloom.sdk.data import open_uow  # sandloom: advanced child task needs its own unit


async def refresh_one(item_id: UUID) -> None:
    async with open_uow():
        item = await db().get(Item, item_id)   # db() is this unit's session
        ...

await asyncio.gather(*(refresh_one(i) for i in ids))

Write admission still applies: the first unit of the request that writes becomes its writer, so a child may be the only writer under a read-only parent, and is refused when another unit already wrote (Write admission). - Passing a session object to another task is unsupported. The framework detects it on a best-effort basis (session methods, the cursor), but some forms cannot be detected: in-place mutation of a mutable column value (for example obj.data["k"] = v on a JSON column without MutableDict), attribute assignment on a loaded instance, and direct use of the session's internals. Do not rely on detection; open a unit per task. - After a unit ends its session is closed and marked. Any later use of a captured reference raises SANDLOOM-R002 instead of silently starting a new transaction.

Commit, rollback, cancellation¶

• The commit runs, in order: before_commit checks, the commit-time session re-check when it is armed (Route policy), COMMIT, outbox dispatch, on_commit callbacks.
• The request unit commits before the response is sent: a client never acts on a 200 whose write is not yet visible.
• Cancellation is an exception: the unit rolls back. Cancellation during COMMIT is an ambiguous commit, resolved by the dedupe records of the effect model (ADR-0005).
• Savepoints. db().begin_nested() uses the same session. A rolled-back savepoint discards the effects registered inside it (events, audit rows, callbacks). After a call that may roll back a savepoint, read entity.id before the call: a rollback expires ORM instances on async sessions.

Events and audit go through the unit¶

await E(...).publish() writes the event to the outbox_messages table in the same transaction. After the commit a dispatcher pushes it to the bus; the relay retries any dispatch that failed. So an event is published if and only if the change that produced it commits.

1. The endpoint's unit inserts the business rows and the outbox row, in one transaction, and commits.
2. The outbox relay picks up the committed row and dispatches its envelope to the event bus.

3. The bus acknowledges it. Without an acknowledgement, the relay retries.

4. The publish preflights the channel, the schema and the payload size inside the transaction, so an event the bus would reject is never committed.

5. Outside a unit, publishing raises UnitOfWorkRequiredError. A deliberately lossy publish passes required=False to the L2 publish_event and needs a marker on the call: # sandloom: best-effort <reason> (SANDLOOM-C007).
6. record_audit follows the same rule (Audit).
7. The relay. A failed dispatch is retried with exponential backoff (OUTBOX_RELAY_BACKOFF_BASE_SECONDS, default 2, doubled per attempt, capped at OUTBOX_RELAY_BACKOFF_MAX_SECONDS, default 300). When the broker itself is down the relay opens a circuit and cools down (OUTBOX_RELAY_CIRCUIT_BASE_SECONDS / _MAX_SECONDS, defaults 1 / 30). A row that exhausts OUTBOX_RELAY_MAX_ATTEMPTS (default 10) is dead-lettered (dead_at set, outbox_dead_total incremented); return it with sandloom outbox list-dead and sandloom outbox requeue. The envelope id is unchanged, so consumers that already applied it dedupe it. OUTBOX_RELAY_ENABLED=auto runs the relay in production processes only (one elected worker per container under gunicorn); turning it off in a production app process needs the accepted risk relay_disabled.

Effects that wait for the commit, checks that run before it¶

• await on_commit(callback) (sync or async, no arguments) runs right after the unit commits. It never runs after a rollback, nor when it was registered inside a savepoint that rolled back. Outside any unit it runs at once. A failing callback is logged and never fails the committed request. Use it for effects outside the database: a cache write, a notification. Revoking a user's tokens has its own helper, revoke_user_tokens_on_commit (sandloom.sdk.security).
• await before_commit(callback) (sandloom.sdk.effects) runs after the handler, right before COMMIT; raising rolls the unit back. Use it to re-validate an input owned by another service. It narrows a race window to "check, then COMMIT"; it does not close it.

One database per invariant¶

Each database has its own unit and transaction; there is no distributed transaction. One business invariant belongs in one database. A route writes to one database, its write store; a second writing unit in the same request is refused at its first write (Write admission). When two databases must stay consistent, use events or a saga, never a shared transaction.

A write that must survive the request's rollback (rare) needs its own transaction opened after the request, never nested inside it. A route whose job is a sequence of short units around an external call (billing checkout) uses the operation-intent mode (Lifecycle).

What breaks it¶

Design rationale¶

• ADR-0005: the effect model
• ADR-0010: Public API 1.0, "Transaction and replay lifecycle"