Reserve Django inventory safely under concurrent requests

• Validate quantity before acquiring the database lock.
• Open transaction.atomic() and read the row with select_for_update().
• Check and update stock while holding the same transaction.
• Do not call remote services inside the lock.
• Use TransactionTestCase or an equivalent real-transaction test.

1. Reject invalid quantity outside the transaction.
2. Lock the product row by primary key.
3. Check available stock after the lock is acquired.
4. Decrement and save only the stock field.
5. Commit before starting non-database follow-up work.

from django.db import transaction

class InsufficientStock(Exception):
    pass

def reserve(product_id: int, quantity: int) -> int:
    if quantity <= 0:
        raise ValueError("quantity must be positive")

    with transaction.atomic():
        product = (
            Product.objects
            .select_for_update()
            .get(pk=product_id)
        )
        if product.stock < quantity:
            raise InsufficientStock(product.stock)
        product.stock -= quantity
        product.save(update_fields=["stock"])
        return product.stock

The indexed row lookup is O(log n); competing reservations for one product serialize for the duration of the short transaction.

• A missing product follows the service's not-found policy.
• Lock waits need a timeout or operational policy under heavy contention.
• A reservation spanning several products needs a consistent lock order.
• SQLite does not reproduce PostgreSQL row-lock behavior.

• Start two real transactions against stock five and reserve three from each.
• Assert exactly one succeeds and final stock is two.
• Force an exception after decrement and verify rollback.
• Reserve different products concurrently and verify they do not block one another unnecessarily.

• Reading stock before entering the locked transaction leaves a race.
• A Python lock works only inside one process.
• Holding the transaction across email or HTTP calls increases contention.
• A normal Django TestCase can hide transaction boundaries behind its wrapper.