Search by

nowo-tech / doctrine-deadlock-retry-bundle

HecFranco

Symfony bundle that retries Doctrine flush and custom operations on DBAL deadlock exceptions with configurable profiles.

Package info

github.com/nowo-tech/DoctrineDeadlockRetryBundle

Documentation

Type:symfony-bundle

pkg:composer/nowo-tech/doctrine-deadlock-retry-bundle

Fund package maintenance!

HecFranco

Statistics

Installs: 20

Dependents: 0

Suggesters: 1

Stars: 0

Open Issues: 2

v3.0.0 2026-11-15 02:47 UTC

README

CI Packagist Version Packagist Downloads License PHP Symfony GitHub stars Coverage

⭐ Found this useful? Install from Packagist and give it a star on GitHub.

Symfony bundle that retries EntityManager::flush() and custom operations on transient Doctrine DBAL failures (deadlocks, lock wait timeouts, serialization failures), repairs the connection after a failure, and optionally guards long-running workers and maps exhausted retries to 503 + Retry-After.

FrankenPHP Friendly Worker Mode

This bundle is FrankenPHP worker mode friendly.

This includes running when the kernel is not reset between requests (see worker audit).

Features

  • DeadlockRetryService: flush(?string $profile), retry(callable $operation, ?string $profile), and getEntityManager().
  • Named profiles: max_retries, exponential backoff with full jitter (backoff_base_ms, alias sleep_ms; backoff_max_ms; jitter), retry_lock_wait_timeout, a max_total_ms budget and rollback_on_deadlock per use case. Requires DBAL 4 / ORM 3.
  • Default profile: used when no profile name is passed.
  • Detects transient failures in the exception chain: RetryableException, MySQL / MariaDB 1213, 1205 and 1020, SQLSTATE 40001 / 40P01 / 55P03 (the ORM's 1305 after a nested deadlock counts through the deadlock it carries).
  • After a failure, rolls back what the operation left open and closes the connection only when that rollback fails (DBAL 4 nested deadlocks), so no worker keeps a poisoned nesting level; retry() clears the entity manager before a replay.
  • Opt-in worker guard (kernel.request / kernel.terminate) and HTTP mapping (503 + Retry-After, 409 for conflicts). See high-load readiness.
  • Resets a closed EntityManager through ManagerRegistry so long-running workers do not keep serving a closed manager.

Version policy

The Composer package is nowo-tech/doctrine-deadlock-retry-bundle. Source and issues: nowo-tech/DoctrineDeadlockRetryBundle.

We follow Semantic Versioning. See Changelog. Security support is described in the Security policy.

Quick example

use Nowo\DoctrineDeadlockRetryBundle\Service\DeadlockRetryService;

public function __construct(
    private readonly DeadlockRetryService $deadlockRetry,
) {
}

public function save(Order $order): void
{
    $this->deadlockRetry->retry(function () use ($order): void {
        $em = $this->deadlockRetry->getEntityManager();
        $em->persist($order);
        $em->flush();
    });
}

Requirements

  • PHP >= 8.2, < 8.6 (Symfony 8.x requires PHP 8.4+)
  • Symfony 6.4 | 7.4 | 8.0 | 8.1 (minimum tested minors: 6.4, 7.4, 8.0, 8.1)
  • Doctrine ORM and DoctrineBundle

Documentation

Additional documentation

Tests and coverage

  • Tests: PHPUnit (PHP)
  • PHP: 100%

License

MIT. See LICENSE.