Pass CommandInterface to retry handler (fixes #1155, #1130)

src/Command/AbstractCommand.php

@@ -472,6 +472,30 @@ public function setSql(string $sql): static
         return $this;
     }
 
+    /**
+     * Sets a closure (anonymous function) which called when a database exception is thrown when executing the command.
+     *
+     * The signature of the closure should be:
+     *
+     * ```php
+     * use Yiisoft\Db\Exception\Exception;
+     * use Yiisoft\Db\Command\CommandInterface;
+     *
+     * function (Exception $e, int $attempt, CommandInterface $command): bool
+     * {
+     *     // return true or false (whether to retry the command or throw $e)
+     * }
+     * ```
+     *
+     * The closure will receive an {@see Exception} converted from the thrown database exception,
+     * the current attempt to execute the command (starting from `0`), and the {@see CommandInterface}
+     * instance to allow access to connection and parameters.
+     *
+     * If the closure returns `true`, the command will be retried. If the closure returns `false`,
+     * the {@see Exception} will be thrown.
+     *
+     * @param Closure|null $handler A PHP callback to handle database exceptions.
+     */
     public function setRetryHandler(?Closure $handler): static
     {
         $this->retryHandler = $handler;

src/Command/CommandInterface.php

@@ -776,18 +776,20 @@ public function setRawSql(string $sql): static;
      *
      * ```php
      * use Yiisoft\Db\Exception\Exception;
+     * use Yiisoft\Db\Command\CommandInterface;
      *
-     * function (Exception $e, int $attempt): bool
+     * function (Exception $e, int $attempt, CommandInterface $command): bool
      * {
      *     // return true or false (whether to retry the command or throw $e)
      * }
      * ```
      *
-     * The closure will receive an {@see Exception} converted from the thrown database exception and the current attempt
-     * to execute the command, starting from `1`.
+     * The closure will receive an {@see Exception} converted from the thrown database exception,
+     * the current attempt to execute the command (starting from `0`), and the {@see CommandInterface}
+     * instance to allow access to connection and parameters for reconnection logic.
      *
-     * If the closure returns `true`, the command will be retried. If the closure returns `false`, the {@see Exception}
-     * will be thrown.
+     * If the closure returns `true`, the command will be retried. If the closure returns `false`,
+     * the {@see Exception} will be thrown.
      *
      * @param Closure|null $handler A PHP callback to handle database exceptions.
      */

src/Driver/Pdo/AbstractPdoCommand.php

@@ -207,7 +207,8 @@ protected function internalExecute(): void
                 $rawSql ??= $this->getRawSql();
                 $e = (new ConvertException($e, $rawSql))->run();
 
-                if ($this->retryHandler === null || !($this->retryHandler)($e, $attempt)) {
+                // ✨ Pass $this (CommandInterface) to retry handler
+                if ($this->retryHandler === null || !($this->retryHandler)($e, $attempt, $this)) {
                     throw $e;
                 }
             }