add a full example for lock_rows

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
 ----------

docs/src/piccolo/query_types/objects.rst

@@ -378,7 +378,7 @@ limit
 See :ref:`limit`.
 
 lock_rows
-~~~~~~~~
+~~~~~~~~~
 
 See :ref:`lock_rows`.
 

docs/src/piccolo/query_types/select.rst

@@ -381,7 +381,7 @@ See :ref:`limit`.
 
 
 lock_rows
-~~~~~~~~
+~~~~~~~~~
 
 See :ref:`lock_rows`.