Stage 4 · L20

Keep SQL queries subordinate to one atomic business operation

Core · original Session 4

An atomic operation either commits all of its intended stored changes or leaves none. This is broader than running several valid SQL statements. A service defines which changes belong together and opens one transaction around them. Queries may flush but must not commit independently.

Read the stage-02 customer/rental transfer again, then compare the stage-04 create/patch/delete services. The parent flush obtains a key but does not make the row visible to an observer. A child constraint failure raises out of the context and rolls back the parent too. A service that caught the child error and returned success could accidentally commit only the parent.

Atomicity does not automatically protect a business read-then-write race. Two transactions can both read old capacity and then each insert a rental. Stage 05 coordinates that decision through an equipment row lock shared by every reservation path. Transaction scope and concurrency policy must be chosen together.

Output validation is inside the write context. A public response that cannot be constructed should fail before commit. The transaction's successful exit finishes the write; only then does the service return its DTO. A fresh observer session is essential evidence, because the same session's identity map can display an object that was never made durable.

SQL and ORM expressions describe the same stored selection when their predicates match. query_examples.py compares a parameterized SELECT by name with select(Equipment).where(Equipment.name == name). Both reject an injection-shaped literal as a nonmatching name, because it is data rather than concatenated SQL. A stored state update plus an AuditEvent must also commit together; stage09 implements and deliberately fails that second write to prove this early atomicity principle.

SQL: SELECT id FROM equipment WHERE name = :name
ORM: select(Equipment.id).where(Equipment.name == name)

One business transaction → intended writes and valid public output
                         ↙                       ↘
                 exception: rollback       success: commit

Both compare the submitted value as data and return no matching row; neither concatenates it into executable SQL. One outer operation owns all intended changes. A child exception must escape that context so the parent rolls back too. Public output must validate before successful exit. This answer uses transactions taught in L15; it does not implement later rental locking.

python run_checks.py --stage 04 --role starter --prepare
python run_checks.py --stage 04 --role starter
python run_checks.py --stage 04 --role starter --transfer

python run_checks.py --stage 04 --role solution --transfer

def patch_equipment(session, identifier, payload):
    changes = payload.model_dump(exclude_unset=True)
    if not changes:
        raise DomainError(422, "empty_patch", "Supply at least one changed field")
    if any(value is None for value in changes.values()):
        raise DomainError(422, "null_patch", "These catalogue fields cannot be null")
    with session.begin():
        row = equipment_by_id(session, identifier)
        if row is None:
            raise DomainError(404, "equipment_missing", "Equipment not found")
        for key, value in changes.items():
            setattr(row, key, value)
        session.flush()
        output = EquipmentOut.model_validate(row)
    return output