diff --git a/docs/src/piccolo/query_clauses/lock_rows.rst b/docs/src/piccolo/query_clauses/lock_rows.rst index 54d435326..0a791f6e8 100644 --- a/docs/src/piccolo/query_clauses/lock_rows.rst +++ b/docs/src/piccolo/query_clauses/lock_rows.rst @@ -85,6 +85,41 @@ Using ``of``, you can specify which tables should be locked. await Band.select().where(Band.manager.name == 'Guido').lock_rows('UPDATE', of=(Band, )) +------------------------------------------------------------------------------- + +Full example +------------ + +If we have this table: + +.. code-block:: python + + class Concert(Table): + name = Varchar() + tickets_available = Integer() + +And we want to make sure that ``tickets_available`` never goes below 0, we can +do the following: + +.. code-block:: python + + async def book_tickets(ticket_count: int): + async with Concert._meta.db.transaction(): + concert = await Concert.objects().where( + Concert.name == "Awesome Concert" + ).first().lock_rows() + + if concert.tickets_available >= ticket_count: + await concert.update_self({ + Concert.tickets_available: Concert.tickets_available - ticket_count + }) + else: + raise ValueError("Not enough tickets are available!") + +This means that when multiple transactions are running at the same time, it +isn't possible to book more tickets than are available. + +------------------------------------------------------------------------------- Learn more ---------- diff --git a/docs/src/piccolo/query_types/objects.rst b/docs/src/piccolo/query_types/objects.rst index 892569a02..e4a2c126e 100644 --- a/docs/src/piccolo/query_types/objects.rst +++ b/docs/src/piccolo/query_types/objects.rst @@ -378,7 +378,7 @@ limit See :ref:`limit`. lock_rows -~~~~~~~~ +~~~~~~~~~ See :ref:`lock_rows`. diff --git a/docs/src/piccolo/query_types/select.rst b/docs/src/piccolo/query_types/select.rst index 4fff7eb6e..2025f35f4 100644 --- a/docs/src/piccolo/query_types/select.rst +++ b/docs/src/piccolo/query_types/select.rst @@ -381,7 +381,7 @@ See :ref:`limit`. lock_rows -~~~~~~~~ +~~~~~~~~~ See :ref:`lock_rows`.