feat(database): add support for nested transactions using savepoints

system/Database/BaseConnection.php

@@ -33,6 +33,7 @@
  * @property-read string     $DBDriver
  * @property-read string     $DBPrefix
  * @property-read string     $DSN
+ * @property-read bool       $enableSavepoints
  * @property-read array|bool $encrypt
  * @property-read array      $failover
  * @property-read string     $hostname
@@ -364,6 +365,13 @@ abstract class BaseConnection implements ConnectionInterface
         'time'        => 'H:i:s',
     ];
 
+    /**
+     * Whether to use savepoints to fully support nesting transactions and partial rollbacks.
+     *
+     * @var bool
+     */
+    protected $enableSavepoints = false;
+
     /**
      * Saves our connection settings.
      */
@@ -777,6 +785,18 @@ public function transException(bool $transExcetion)
         return $this;
     }
 
+    /**
+     * If set to true, enables the use of nested transactions
+     * If set to false (default), only the outermost transaction
+     * actually gets started and ended or rolled back.
+     */
+    public function transSavepoints(bool $enable): self
+    {
+        $this->enableSavepoints = $enable;
+
+        return $this;
+    }
+
     /**
      * Complete Transaction
      */
@@ -790,13 +810,6 @@ public function transComplete(): bool
         if ($this->transStatus === false || $this->transFailure === true) {
             $this->transRollback();
 
-            // If we are NOT running in strict mode, we will reset
-            // the _trans_status flag so that subsequent groups of
-            // transactions will be permitted.
-            if ($this->transStrict === false) {
-                $this->transStatus = true;
-            }
-
             return false;
         }
 
@@ -820,8 +833,9 @@ public function transBegin(bool $testMode = false): bool
             return false;
         }
 
-        // When transactions are nested we only begin/commit/rollback the outermost ones
-        if ($this->transDepth > 0) {
+        // When transactions are nested and nested transactions are not enabled
+        // we only begin/commit/rollback the outermost ones
+        if (! $this->enableSavepoints && $this->transDepth > 0) {
             $this->transDepth++;
 
             return true;
@@ -836,51 +850,60 @@ public function transBegin(bool $testMode = false): bool
         // even if the queries produce a successful result.
         $this->transFailure = ($testMode === true);
 
-        if ($this->_transBegin()) {
-            $this->transDepth++;
+        $started = false;
 
-            return true;
+        try {
+            return $started = ($this->transDepth < 1 ? $this->_transBegin() : $this->_transBeginNested());
+        } finally {
+            if ($started) {
+                $this->transDepth++;
+            }
         }
-
-        return false;
     }
 
     /**
      * Commit Transaction
      */
     public function transCommit(): bool
     {
-        if (! $this->transEnabled || $this->transDepth === 0) {
-            return false;
-        }
-
-        // When transactions are nested we only begin/commit/rollback the outermost ones
-        if ($this->transDepth > 1 || $this->_transCommit()) {
-            $this->transDepth--;
-
-            return true;
-        }
-
-        return false;
+        return $this->_transEnd(true);
     }
 
     /**
      * Rollback Transaction
      */
     public function transRollback(): bool
     {
-        if (! $this->transEnabled || $this->transDepth === 0) {
-            return false;
-        }
+        return $this->_transEnd(false);
+    }
 
-        // When transactions are nested we only begin/commit/rollback the outermost ones
-        if ($this->transDepth > 1 || $this->_transRollback()) {
-            $this->transDepth--;
+    private function _transEnd(bool $commit = false): bool
+    {
+        $ended                = false;
+        $transEndMethod       = $commit ? '_transCommit' : '_transRollback';
+        $transEndNestedMethod = $transEndMethod . 'Nested';
 
-            return true;
+        try {
+            // if nested transactions are disabled and transactions are nested we only begin/commit/rollback the outermost ones
+            return $ended = match (true) {
+                ! $this->transEnabled                            => false,
+                $this->transDepth === 1                          => $this->{$transEndMethod}(),
+                $this->enableSavepoints && $this->transDepth > 1 => $this->{$transEndNestedMethod}(),
+                $this->transDepth > 1                            => true,
+                default                                          => false,
+            };
+        } finally {
+            if ($ended) {
+                $this->transDepth = max(0, $this->transDepth - 1);
+
+                // If we are NOT running in strict mode, we will reset
+                // the _trans_status flag so that subsequent groups of
+                // transactions will be permitted.
+                if ($this->transStrict === false) {
+                    $this->transStatus = true;
+                }
+            }
         }
-
-        return false;
     }
 
     /**
@@ -898,6 +921,21 @@ abstract protected function _transCommit(): bool;
      */
     abstract protected function _transRollback(): bool;
 
+    /**
+     * Begin Transaction
+     */
+    abstract protected function _transBeginNested(): bool;
+
+    /**
+     * Commit Transaction
+     */
+    abstract protected function _transCommitNested(): bool;
+
+    /**
+     * Rollback Transaction
+     */
+    abstract protected function _transRollbackNested(): bool;
+
     /**
      * Returns a non-shared new instance of the query builder for this connection.
      *
@@ -1720,7 +1758,7 @@ public function resetDataCache()
      */
     public function isWriteType($sql): bool
     {
-        return (bool) preg_match('/^\s*(WITH\s.+(\s|[)]))?"?(SET|INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|TRUNCATE|LOAD|COPY|ALTER|RENAME|GRANT|REVOKE|LOCK|UNLOCK|REINDEX|MERGE)\s(?!.*\sRETURNING\s)/is', $sql);
+        return (bool) preg_match('/^\s*(WITH\s.+(\s|[)]))?"?(SET|INSERT|UPDATE|DELETE|REPLACE|CREATE|DROP|TRUNCATE|LOAD|COPY|ALTER|RENAME|GRANT|REVOKE|LOCK|UNLOCK|REINDEX|MERGE|((RELEASE|ROLLBACK TO)?\s*SAVEPOINT))\s(?!.*\sRETURNING\s)/is', $sql);
     }
 
     /**

system/Database/MySQLi/Connection.php

@@ -15,6 +15,7 @@
 
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\SavepointsForNestedTransactions;
 use LogicException;
 use mysqli;
 use mysqli_result;
@@ -29,6 +30,10 @@
  */
 class Connection extends BaseConnection
 {
+    use SavepointsForNestedTransactions {
+        _savepointQueryDefault as _savePointQuery;
+    }
+
     /**
      * Database driver
      *

system/Database/OCI8/Connection.php

@@ -16,6 +16,7 @@
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Database\Query;
+use CodeIgniter\Database\SavepointsForNestedTransactions;
 use ErrorException;
 use stdClass;
 
@@ -26,6 +27,10 @@
  */
 class Connection extends BaseConnection
 {
+    use SavepointsForNestedTransactions {
+        _savepointQueryDefault as _savePointQuery;
+    }
+
     /**
      * Database driver
      *
@@ -113,6 +118,11 @@
         return false;
     }
 
+    public function initialize()
+    {
+        return parent::initialize(); // TODO: Change the autogenerated stub
+    }
+
     /**
      * Connect to the database.
      *

system/Database/Postgre/Connection.php

@@ -16,6 +16,7 @@
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
 use CodeIgniter\Database\RawSql;
+use CodeIgniter\Database\SavepointsForNestedTransactions;
 use ErrorException;
 use PgSql\Connection as PgSqlConnection;
 use PgSql\Result as PgSqlResult;
@@ -29,6 +30,10 @@
  */
 class Connection extends BaseConnection
 {
+    use SavepointsForNestedTransactions {
+        _savepointQueryDefault as _savepointQuery;
+    }
+
     /**
      * Database driver
      *

system/Database/SQLSRV/Connection.php

@@ -15,6 +15,7 @@
 
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\SavepointsForNestedTransactions;
 use stdClass;
 
 /**
@@ -24,6 +25,8 @@
  */
 class Connection extends BaseConnection
 {
+    use SavepointsForNestedTransactions;
+
     /**
      * Database driver
      *
@@ -564,4 +567,9 @@
 
         return parent::isWriteType($sql);
     }
+
+    protected function _savepointQuery($create, $commit): string
+    {
+        return $create ? 'SAVE' : ($commit ? 'COMMIT' : 'ROLLBACK') . ' TRANSACTION';
+    }
 }

system/Database/SQLite3/Connection.php

@@ -15,6 +15,7 @@
 
 use CodeIgniter\Database\BaseConnection;
 use CodeIgniter\Database\Exceptions\DatabaseException;
+use CodeIgniter\Database\SavepointsForNestedTransactions;
 use Exception;
 use SQLite3;
 use SQLite3Result;
@@ -27,6 +28,10 @@
  */
 class Connection extends BaseConnection
 {
+    use SavepointsForNestedTransactions {
+        _savepointQueryDefault as _savepointQuery;
+    }
+
     /**
      * Database driver
      *

system/Database/SavepointsForNestedTransactions.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of CodeIgniter 4 framework.
+ *
+ * (c) CodeIgniter Foundation <[email protected]>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ */
+
+namespace CodeIgniter\Database;
+
+trait SavepointsForNestedTransactions
+{
+    private function _savepointQueryDefault(bool $create, bool $commit): string
+    {
+        return ($create ? '' : ($commit ? 'RELEASE' : 'ROLLBACK TO') . ' ') . 'SAVEPOINT';
+    }
+
+    abstract private function _savepointQuery(bool $begin, bool $commit): string;
+
+    /**
+     * Generates the SQL for managing savepoints, which
+     * are used to support nested transactions with SQLite3
+     */
+    private function _savepoint(int $savepoint, bool $create, bool $commit): string
+    {
+        $savepointIdentifier = $this->escapeIdentifier('__ci4_savepoint_' . $savepoint . '__');
+
+        return $this->_savepointQuery($create, $commit);
+    }
+
+    /**
+     * Begin a Nested Transaction
+     */
+    protected function _transBeginNested(): bool
+    {
+        return false !== $this->execute($this->_savepoint($this->transDepth + 1, true));
+    }
+
+    /**
+     * Commit a Nested Transaction
+     */
+    protected function _transCommitNested(): bool
+    {
+        return false !== $this->execute($this->_savepoint($this->transDepth, false, true));
+    }
+
+    /**
+     * Rollback a Nested Transaction
+     */
+    protected function _transRollbackNested(): bool
+    {
+        return false !== $this->execute($this->_savepoint($this->transDepth, false, true));
+    }
+}

system/Test/Mock/MockConnection.php

@@ -250,4 +250,19 @@ protected function _transRollback(): bool
     {
         return true;
     }
+
+    protected function _transBeginNested(): bool
+    {
+        return true;
+    }
+
+    protected function _transCommitNested(): bool
+    {
+        return true;
+    }
+
+    protected function _transRollbackNested(): bool
+    {
+        return true;
+    }
 }