Protect capacity decisions in one transaction

In this lesson you will protect capacity decisions in one transaction. Work with the Equipment Rental API in the downloadable lab. The reference is a complete solution with separate lesson checks, so you can inspect the answer, make a deliberate local change and verify its behavior.

Two requests can both observe spare capacity and then overbook it. The safe decision must read current reservations and write the new rental within one serialized transaction. reserve first locks the equipment row with SELECT FOR UPDATE, computes active quantity, rejects an oversized request, and inserts the rental before commit. A second reservation for the same equipment waits, then sees the first committed rental.

The parent row is the coordination point. Every path that changes active capacity must use the same protocol, including check-in in the final feature. Locking only existing rental rows cannot protect the case where no rental exists yet. A Python lock in one worker is also insufficient when multiple processes handle requests. Use a consistent lock order to reduce deadlocks, and expect real systems to need timeout and retry policies around contention. This example uses PostgreSQL's default read-committed behavior and locks equipment before rental state. A capacity conflict is a deliberate 409 outcome, not an infrastructure failure. Returning success before the transaction commits would defeat the guarantee.

Worked source: equipment/services.py, reserve.

The lesson10 check starts two worker threads at a barrier. Each requests all two units of the same item. Exactly one must reserve and the other must receive capacity_unavailable. The database sum must stay at two. This checks the race using independent PostgreSQL sessions, not sequential mocked responses.

def reserve(session, equipment_id, owner_id, quantity):
    if quantity < 1:
        raise DomainError("invalid_quantity", "Request at least one unit.", 422)
    with session.begin():
        item = session.scalar(
            select(Equipment).where(Equipment.id == equipment_id).with_for_update()
        )
        if item is None:
            raise missing()
        used = session.scalar(
            select(func.coalesce(func.sum(Rental.quantity), 0)).where(
                Rental.equipment_id == equipment_id, Rental.status == "active"
            )
        )
        if used + quantity > item.quantity:
            raise DomainError(
                "capacity_unavailable", "Not enough equipment units are available."
            )
        rental = Rental(equipment_id=equipment_id, owner_id=owner_id, quantity=quantity)
        session.add(rental)
        session.flush()
        result = RentalOut.model_validate(rental)
    return result

python run_checks.py -k lesson10