Connection, Explorer: transaction() supports retry on deadlock, added RetryableException

Added optional $attempts parameter. When greater than 1, any exception
implementing RetryableException on the outermost transaction triggers a
retry of the whole callback. The callback must be idempotent.

A new RetryableException marker interface is introduced; DeadlockException
and LockTimeoutException all implement it. Applications can mark their own
transient errors with the interface (e.g. optimistic lock conflicts)
to opt into automatic retries.

Nested transactions never retry on their own — the exception bubbles up
to the outermost transaction, which honors its own $attempts setting.

Author: dg

AGENTS.md

@@ -69,8 +69,7 @@ aren't up yet, not a broken test.
   (`?and`/`?set`/`?values`/`?order`/`?list`), so the same array expands differently
   after `WHERE` vs `SET` vs `INSERT`. See `docs/internals/sql-preprocessor.md`.
 - **Nested transactions use a depth counter, not savepoints** - only the outermost
-  `transaction()` issues a real BEGIN/COMMIT/ROLLBACK; there is no partial rollback,
-  and no retry mechanism (no `$attempts`, no `RetryableException`, no `onRetry`).
+  `transaction()` issues a real BEGIN/COMMIT/ROLLBACK; there is no partial rollback.
   There is no `TypeConverter` class either (DB->PHP conversion is
   `Helpers::normalizeRow`). Don't document designed-but-absent features as present.
 - **Array expansion is a mass-assignment surface.** Passing raw user input as the

docs/internals/connection-drivers.md

@@ -38,14 +38,15 @@ interval).
                  ├── ConnectionException → ConnectionLostException
                  ├── ConstraintViolationException
                  │     ├── ForeignKey / NotNull / Unique / CheckConstraintViolation
-                 ├── DeadlockException
-                 └── LockTimeoutException
+                 ├── DeadlockException      (Retryable)
+                 └── LockTimeoutException   (Retryable)
 ```
 
 Note `Deadlock`/`LockTimeout` extend `DriverException` **directly**, not the
-constraint hierarchy. There is **no** `RetryableException` marker and `transaction()`
-performs no retries — retrying on deadlock/lock-timeout/connection-lost is the
-caller's job. The mapping is **per driver** in
+constraint hierarchy, and both implement the `RetryableException` marker (used by
+`transaction()` retries). `ConnectionLostException` deliberately does not — a
+connection lost during `COMMIT` has an unknown outcome, so an automatic retry could
+apply the transaction twice. The mapping is **per driver** in
 `convertException`: MySQL keys on the numeric error code, PgSql on the SQLSTATE; an
 unrecognized error falls back to a bare `DriverException::from()`. `DriverException::from`
 parses `errorInfo`, or the `SQLSTATE[..] [..] ..` pattern from the message when

docs/internals/readme.md

@@ -12,4 +12,4 @@ worlds — the low-level core and the Explorer (ActiveRow) layer — so split by
   `Driver` dialect abstraction, and exception mapping.
 - **[results-and-types.md](results-and-types.md)** — `ResultSet` and the DB→PHP
   value normalization.
-- **[transactions.md](transactions.md)** — `transaction()` and depth-counter nesting.
+- **[transactions.md](transactions.md)** — `transaction()`, nesting, and retries.

docs/internals/transactions.md

@@ -4,26 +4,25 @@ Nesting is **counter-based only** — there are **no savepoints**.
 
 ## `transaction()`
 
-`transaction(callable $callback): mixed` runs the callback between `BEGIN` and
-`COMMIT`/`ROLLBACK`. Nesting is tracked purely by `$transactionDepth`:
+`transaction(callable $callback, int $attempts = 1)` runs a phase machine
+(`begin`/`body`/`commit`) inside a retry loop. Nesting is tracked purely by
+`$transactionDepth`:
 
 - a real `BEGIN` is issued only when `transactionDepth === 0`; a nested call merely
   increments the counter and **emits no SQL**;
 - `COMMIT` likewise only at depth 0; on an exception, `ROLLBACK` only when it unwinds
-  back to depth 0, then the exception is rethrown. Any failure of the rollback itself
-  (e.g. when the server already rolled back after a deadlock, or an `onQuery` handler
-  throws) is swallowed so it cannot mask the original exception.
+  back to depth 0 (wrapped in try/catch, since the server may have rolled back
+  already);
+- a **retry** happens only at the outermost level, when `$attempt < $attempts` and the
+  exception implements `RetryableException` (deadlock / lock timeout; a lost
+  connection is deliberately not retryable — the outcome of an in-flight `COMMIT`
+  is unknown) — firing `onRetry` between attempts.
 
 **The consequence to internalize:** a nested `transaction()` gives **no partial
 rollback**. Only the outermost transaction issues real `BEGIN`/`COMMIT`/`ROLLBACK`, so
 an inner failure tears down the *entire* outer transaction. The idea of savepoints is
 **not implemented** — there is no `SAVEPOINT`/`RELEASE` anywhere in the code.
 
-**No retries either (so don't document them as present):** there is no `$attempts`
-parameter, no retry loop, no `RetryableException` marker, no `onRetry` event.
-`DeadlockException`, `LockTimeoutException` and `ConnectionLostException` exist, but
-nothing in `transaction()` catches and retries them — retrying is the caller's job.
-
 ## Manual control is fenced off inside a callback
 
 `beginTransaction()`/`commit()`/`rollBack()` each **throw** if called while

src/Database/Connection.php

@@ -25,6 +25,9 @@ class Connection
 
 	/** @var array<callable(static, ResultSet|DriverException): void>  Occurs after query is executed */
 	public array $onQuery = [];
+
+	/** @var array<callable(static, int, RetryableException): void>  Occurs before a transaction() retry */
+	public array $onRetry = [];
 	private Driver $driver;
 	private SqlPreprocessor $preprocessor;
 	private ?PDO $pdo = null;
@@ -235,36 +238,60 @@ public function isInTransaction(): bool
 
 	/**
 	 * Executes callback inside a transaction. Supports nesting.
+	 * When $attempts > 1, a RetryableException raised during begin, commit
+	 * or inside the callback on the outermost transaction triggers a retry
+	 * of the whole callback. Callbacks must be idempotent. The $onRetry
+	 * event fires before each retry and is the place to apply backoff.
 	 * @param  callable(static): mixed  $callback
 	 */
-	public function transaction(callable $callback): mixed
+	public function transaction(callable $callback, int $attempts = 1): mixed
 	{
-		if ($this->transactionDepth === 0) {
-			$this->beginTransaction();
+		if ($attempts < 1) {
+			throw new Nette\InvalidArgumentException('Number of attempts must be at least 1.');
 		}
 
-		$this->transactionDepth++;
-		try {
-			$res = $callback($this);
-		} catch (\Throwable $e) {
-			$this->transactionDepth--;
-			if ($this->transactionDepth === 0) {
-				try {
-					$this->rollBack();
-				} catch (\Throwable) {
-					// e.g. after a deadlock the server has already rolled back; the original exception matters more
+		for ($attempt = 1; ; $attempt++) {
+			$phase = 'begin';
+			try {
+				if ($this->transactionDepth === 0) {
+					$this->beginTransaction();
 				}
-			}
 
-			throw $e;
-		}
+				$this->transactionDepth++;
+				$phase = 'body';
+				$res = $callback($this);
+				$this->transactionDepth--;
+				$phase = 'commit';
+				if ($this->transactionDepth === 0) {
+					$this->commit();
+				}
 
-		$this->transactionDepth--;
-		if ($this->transactionDepth === 0) {
-			$this->commit();
-		}
+				return $res;
+			} catch (\Throwable $e) {
+				if ($phase === 'body') {
+					$this->transactionDepth--;
+				}
+
+				if ($this->transactionDepth === 0 && $phase !== 'begin') {
+					try {
+						$this->rollBack();
+					} catch (\Throwable) {
+						// server may have already rolled back (deadlock) or the
+						// connection may be gone; the original $e is what matters
+					}
+				}
 
-		return $res;
+				if ($this->transactionDepth === 0
+					&& $attempt < $attempts
+					&& $e instanceof RetryableException
+				) {
+					Arrays::invoke($this->onRetry, $this, $attempt, $e);
+					continue;
+				}
+
+				throw $e;
+			}
+		}
 	}
 
 

src/Database/Explorer.php

@@ -58,12 +58,16 @@ public function isInTransaction(): bool
 
 
 	/**
-	 * Executes callback inside a transaction.
+	 * Executes callback inside a transaction. Supports nesting.
+	 * When $attempts > 1, a RetryableException raised during begin, commit
+	 * or inside the callback on the outermost transaction triggers a retry
+	 * of the whole callback. Callbacks must be idempotent. Subscribe to
+	 * Connection::$onRetry to plug in backoff between attempts.
 	 * @param  callable(static): mixed  $callback
 	 */
-	public function transaction(callable $callback): mixed
+	public function transaction(callable $callback, int $attempts = 1): mixed
 	{
-		return $this->connection->transaction(fn() => $callback($this));
+		return $this->connection->transaction(fn() => $callback($this), $attempts);
 	}
 
 

src/Database/exceptions.php

@@ -8,6 +8,17 @@
 namespace Nette\Database;
 
 
+/**
+ * Marks transient exceptions that are safe to retry because the server
+ * guarantees the transaction was rolled back, such as deadlocks or lock
+ * timeouts. Connection::transaction() retries the callback automatically
+ * when $attempts > 1.
+ */
+interface RetryableException
+{
+}
+
+
 /**
  * Failed to connect to the database server.
  */
@@ -70,7 +81,7 @@ class CheckConstraintViolationException extends ConstraintViolationException
  * Deadlock or serialization failure detected by the server; the transaction
  * was rolled back and can be retried.
  */
-class DeadlockException extends DriverException
+class DeadlockException extends DriverException implements RetryableException
 {
 }
 
@@ -79,6 +90,6 @@ class DeadlockException extends DriverException
  * A lock wait exceeded the configured timeout. The statement was aborted,
  * typically leaving the surrounding transaction alive.
  */
-class LockTimeoutException extends DriverException
+class LockTimeoutException extends DriverException implements RetryableException
 {
 }