From 9f70972887d9644c67aee8e39fde25e01afcaf9d Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Fri, 13 Aug 2021 11:26:57 +0200
Subject: [PATCH] Document correct db transaction handling

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 developer_manual/basics/storage/database.rst | 27 ++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/developer_manual/basics/storage/database.rst b/developer_manual/basics/storage/database.rst
index 2f0f68567..5b73e6a27 100644
--- a/developer_manual/basics/storage/database.rst
+++ b/developer_manual/basics/storage/database.rst
@@ -45,6 +45,33 @@ Inside your database layer class you can now start running queries like:
     }
 
 
+Transactions
+------------
+
+Database operations can be run in a transaction to commit or roll back a group of changes in an atomic fashion.
+
+.. code-block:: php
+
+    <?php
+
+    $this->db->startTransaction();
+
+    try {
+        // DB operations
+
+        $this->db->commit();
+    } catch (\Throwable $e) {
+        // Optional: handle the error
+
+        // Important: roll back (or commit) your changes when an error
+        //            happens, so this transaction ends
+        $this->db->rollBack();
+
+        throw $e;
+    }
+
+.. warning:: Omitting the error handling for transactions will lead to unexpected behavior as any database operations that come after your error will still run in your transaction and due to the lack of a commit PDO will automatically roll-back all changes at the end of the script.
+
 Mappers
 -------