[master] Savepoint Support for Database Transactions

src/Illuminate/Database/Concerns/ManagesTransactions.php

@@ -157,20 +157,6 @@ protected function createTransaction()
         }
     }
 
-    /**
-     * Create a save point within the database.
-     *
-     * @return void
-     *
-     * @throws \Throwable
-     */
-    protected function createSavepoint()
-    {
-        $this->getPdo()->exec(
-            $this->queryGrammar->compileSavepoint('trans'.($this->transactions + 1))
-        );
-    }
-
     /**
      * Handle an exception from a transaction beginning.
      *
@@ -216,6 +202,22 @@ public function commit()
         $this->fireConnectionEvent('committed');
     }
 
+    /**
+     * Create a save point within the database.
+     *
+     * @return void
+     *
+     * @throws \Throwable
+     */
+    protected function createSavepoint()
+    {
+        // we do not use ManagesSavepoint::savepoint() here because this is an internally created savepoint
+        // used as part of nested transaction emulation and therefore not stored in the savepoints array
+        $this->getPdo()->exec(
+            $this->queryGrammar->compileSavepoint('trans'.($this->transactions + 1))
+        );
+    }
+
     /**
      * Handle an exception encountered when committing a transaction.
      *
@@ -298,7 +300,9 @@ protected function performRollBack($toLevel)
             }
         } elseif ($this->queryGrammar->supportsSavepoints()) {
             $this->getPdo()->exec(
-                $this->queryGrammar->compileSavepointRollBack('trans'.($toLevel + 1))
+                // we do not use ManagesSavepoints::rollbackToSavepoint() here because this is an internally created
+                // savepoint used as part of nested transaction emulation and therefore not stored in the savepoints array
+                $this->queryGrammar->compileRollbackToSavepoint('trans'.($toLevel + 1))
             );
         }
     }

src/Illuminate/Database/Connection.php

@@ -30,6 +30,7 @@ class Connection implements ConnectionInterface
     use DetectsConcurrencyErrors,
         DetectsLostConnections,
         Concerns\ManagesTransactions,
+        Concerns\ManagesSavepoints,
         InteractsWithTime,
         Macroable;
 
@@ -228,6 +229,8 @@ public function __construct($pdo, $database = '', $tablePrefix = '', array $conf
         $this->useDefaultQueryGrammar();
 
         $this->useDefaultPostProcessor();
+
+        $this->initializeSavepointManagement();
     }
 
     /**
@@ -1458,6 +1461,8 @@ public function setEventDispatcher(Dispatcher $events)
     {
         $this->events = $events;
 
+        $this->initializeSavepointManagement();
+
         return $this;
     }
 

src/Illuminate/Database/ConnectionInterface.php

@@ -167,6 +167,54 @@ public function rollBack();
      */
     public function transactionLevel();
 
+    /**
+     * Create a savepoint within the current transaction. Optionally provide a callback
+     * to be executed following creation of the savepoint. If the callback fails, the transaction
+     * will be rolled back to the savepoint. The savepoint will be released after the callback
+     * has been executed.
+     */
+    public function savepoint(string $name, ?callable $callback = null): mixed;
+
+    /**
+     * Release a savepoint in the database.
+     */
+    public function releaseSavepoint(string $name, ?int $level = null): void;
+
+    /**
+     * Release all savepoints in the database.
+     */
+    public function purgeSavepoints(?int $level = null): void;
+
+    /**
+     * Rollback to a savepoint in the database.
+     */
+    public function rollbackToSavepoint(string $name): void;
+
+    /**
+     * Determine if a savepoint exists in the database.
+     */
+    public function hasSavepoint(string $name): bool;
+
+    /**
+     * Get the names of all savepoints in the database.
+     */
+    public function getSavepoints(): array;
+
+    /**
+     * Get the current savepoint name.
+     */
+    public function getCurrentSavepoint(): ?string;
+
+    /**
+     * Determine if the connection supports releasing savepoints.
+     */
+    public function supportsSavepoints(): bool;
+
+    /**
+     * Determine if the connection releases savepoints.
+     */
+    public function supportsSavepointRelease(): bool;
+
     /**
      * Execute the given callback in "dry run" mode.
      *

src/Illuminate/Database/Events/SavepointCreated.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Illuminate\Database\Events;
+
+use Illuminate\Database\Connection;
+
+class SavepointCreated extends ConnectionEvent
+{
+    public function __construct(
+        Connection $connection,
+        public string $savepoint
+    ) {
+        parent::__construct($connection);
+    }
+}

src/Illuminate/Database/Events/SavepointReleased.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Illuminate\Database\Events;
+
+use Illuminate\Database\Connection;
+
+class SavepointReleased extends ConnectionEvent
+{
+    public function __construct(
+        Connection $connection,
+        public string $savepoint
+    ) {
+        parent::__construct($connection);
+    }
+}

src/Illuminate/Database/Events/SavepointRolledBack.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace Illuminate\Database\Events;
+
+use Illuminate\Database\Connection;
+
+class SavepointRolledBack extends ConnectionEvent
+{
+    public function __construct(
+        Connection $connection,
+        public string $savepoint,
+        public array $releasedSavepoints = []
+    ) {
+        parent::__construct($connection);
+    }
+}

src/Illuminate/Database/Query/Grammars/Grammar.php

@@ -811,6 +811,46 @@ public function whereExpression(Builder $query, $where)
         return $where['column']->getValue($this);
     }
 
+    /**
+     * Determine if the connection supports savepoints.
+     */
+    public function supportsSavepoints(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine if the connection supports releasing savepoints.
+     */
+    public function supportsSavepointRelease(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Compile the SQL statement to define a savepoint.
+     */
+    public function compileSavepoint(string $name): string
+    {
+        return 'SAVEPOINT '.$this->wrapValue($name);
+    }
+
+    /**
+     * Compile the SQL statement to execute a savepoint rollback.
+     */
+    public function compileRollbackToSavepoint(string $name): string
+    {
+        return 'ROLLBACK TO SAVEPOINT '.$this->wrapValue($name);
+    }
+
+    /**
+     * Compile the SQL statement to execute a savepoint release.
+     */
+    public function compileReleaseSavepoint(string $name): string
+    {
+        return 'RELEASE SAVEPOINT '.$this->wrapValue($name);
+    }
+
     /**
      * Compile the "group by" portions of the query.
      *
@@ -1452,38 +1492,6 @@ public function compileThreadCount()
         return null;
     }
 
-    /**
-     * Determine if the grammar supports savepoints.
-     *
-     * @return bool
-     */
-    public function supportsSavepoints()
-    {
-        return true;
-    }
-
-    /**
-     * Compile the SQL statement to define a savepoint.
-     *
-     * @param  string  $name
-     * @return string
-     */
-    public function compileSavepoint($name)
-    {
-        return 'SAVEPOINT '.$name;
-    }
-
-    /**
-     * Compile the SQL statement to execute a savepoint rollback.
-     *
-     * @param  string  $name
-     * @return string
-     */
-    public function compileSavepointRollBack($name)
-    {
-        return 'ROLLBACK TO SAVEPOINT '.$name;
-    }
-
     /**
      * Wrap the given JSON selector for boolean values.
      *

src/Illuminate/Database/Query/Grammars/MariaDbGrammar.php

@@ -53,4 +53,44 @@ public function useLegacyGroupLimit(Builder $query)
     {
         return false;
     }
+
+    /**
+     * Determine if the connection supports savepoints.
+     */
+    public function supportsSavepoints(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine if the connection supports releasing savepoints.
+     */
+    public function supportsSavepointRelease(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Compile the SQL statement to define a savepoint.
+     */
+    public function compileSavepoint(string $name): string
+    {
+        return 'SAVEPOINT '.$this->wrapValue($name);
+    }
+
+    /**
+     * Compile the SQL statement to execute a savepoint rollback.
+     */
+    public function compileRollbackToSavepoint(string $name): string
+    {
+        return 'ROLLBACK TO SAVEPOINT '.$this->wrapValue($name);
+    }
+
+    /**
+     * Compile the SQL statement to execute a savepoint release.
+     */
+    public function compileReleaseSavepoint(string $name): string
+    {
+        return 'RELEASE SAVEPOINT '.$this->wrapValue($name);
+    }
 }

src/Illuminate/Database/Query/Grammars/MySqlGrammar.php

@@ -3,6 +3,7 @@
 namespace Illuminate\Database\Query\Grammars;
 
 use Illuminate\Database\Query\Builder;
+use Illuminate\Database\Query\Grammars\Grammar;
 use Illuminate\Database\Query\JoinLateralClause;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Str;
@@ -496,6 +497,46 @@ public function compileThreadCount()
         return 'select variable_value as `Value` from performance_schema.session_status where variable_name = \'threads_connected\'';
     }
 
+    /**
+     * Determine if the connection supports savepoints.
+     */
+    public function supportsSavepoints(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Determine if the connection supports releasing savepoints.
+     */
+    public function supportsSavepointRelease(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Compile the SQL statement to define a savepoint.
+     */
+    public function compileSavepoint(string $name): string
+    {
+        return 'SAVEPOINT '.$this->wrapValue($name);
+    }
+
+    /**
+     * Compile the SQL statement to execute a savepoint rollback.
+     */
+    public function compileRollbackToSavepoint(string $name): string
+    {
+        return 'ROLLBACK TO SAVEPOINT '.$this->wrapValue($name);
+    }
+
+    /**
+     * Compile the SQL statement to execute a savepoint release.
+     */
+    public function compileReleaseSavepoint(string $name): string
+    {
+        return 'RELEASE SAVEPOINT '.$this->wrapValue($name);
+    }
+
     /**
      * Wrap a single string in keyword identifiers.
      *