Merge pull request #5949 from michaelrk02/develop

[docs] add DB nested transaction

Author: kenjis

user_guide_src/source/database/transactions.rst

@@ -97,3 +97,20 @@ If you would like to run transactions manually you can do so as follows:
 
 .. note:: Make sure to use ``$this->db->transBegin()`` when running manual
     transactions, **NOT** ``$this->db->transStart()``.
+
+Nested Transactions
+===================
+
+In CodeIgniter, transactions can be nested in a way such that only the
+outmost or top-level transaction commands are executed. You can include as
+many pairs of ``transStart()``/``transComplete()`` or ``transBegin()``/``transCommit()``/``transRollback()``
+as you want inside a transaction block and so on. CodeIgniter will keep
+track of the transaction "depth" and only take action at the outermost layer
+(zero depth).
+
+.. literalinclude:: transactions/007.php
+
+.. note:: In case the structure is far more complex, it's your responsibility
+    to ensure that the inner transactions can reach the outermost layer again
+    in order to be fully executed by the database, thus prevents unintended
+    commits/rollbacks.

user_guide_src/source/database/transactions/007.php

@@ -0,0 +1,9 @@
+<?php
+
+$this->db->transStart(); // actually starts a transaction
+$this->db->query('SOME QUERY 1 ...');
+$this->db->transStart(); // doesn't necessarily start another transaction
+$this->db->query('SOME QUERY 2 ...');
+$this->db->transComplete(); // doesn't necessarily end the transaction, but required to finish the inner transaction
+$this->db->query('SOME QUERY 3 ...');
+$this->db->transComplete(); // actually ends the transaction