nowo-tech / doctrine-deadlock-retry-bundle
Symfony bundle that retries Doctrine flush and custom operations on DBAL deadlock exceptions with configurable profiles.
Package info
github.com/nowo-tech/DoctrineDeadlockRetryBundle
Type:symfony-bundle
pkg:composer/nowo-tech/doctrine-deadlock-retry-bundle
Fund package maintenance!
Requires
- php: >=8.2 <8.6
- doctrine/dbal: ^4.0
- doctrine/doctrine-bundle: ^2.8 || ^3.0
- doctrine/orm: ^3.0
- nowo-tech/transaction-contract: ^1.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- symfony/config: ^6.4 || ^7.4 || ^8.0
- symfony/dependency-injection: ^6.4 || ^7.4 || ^8.0
- symfony/event-dispatcher: ^6.4 || ^7.4 || ^8.0
- symfony/http-foundation: ^6.4 || ^7.4 || ^8.0
- symfony/http-kernel: ^6.4 || ^7.4 || ^8.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.0
- igor-php/igor-php: ^0.10.0
- nowo-tech/phpstan-frankenphp: ^1.0
- phpstan/extension-installer: ^1.4
- phpstan/phpstan: ^2.0
- phpstan/phpstan-phpunit: ^2.0
- phpstan/phpstan-symfony: ^2.0
- phpunit/phpunit: ^10.0
- rector/rector: ^2.0
- symfony/cache: ^6.4 || ^7.4 || ^8.0
- symfony/messenger: ^6.4 || ^7.4 || ^8.0
- symfony/yaml: ^6.4 || ^7.4 || ^8.0
Suggests
- symfony/flex: For automatic recipe installation
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v3.0.0
- v2.4.0
- v2.3.0
- v2.2.2
- v2.2.1
- v2.2.0
- v2.1.3
- v2.1.2
- v2.1.1
- v2.1.0
- v2.0.9
- v2.0.8
- v2.0.7
- v2.0.6
- v2.0.5
- v2.0.4
- v2.0.3
- v2.0.2
- v2.0.1
- v2.0.0
- v1.0.1
- v1.0.0
- dev-chore/req-sweep-2026-11-16
- dev-feat/load-readiness
- dev-feat/arch-001-ports
- dev-feat/arch-001-d
- dev-chore/demo-uikit
- dev-test/worker-kept-alive
- dev-chore/symfony-security-2026-11-04
This package is auto-updated.
Last update: 2026-11-16 08:16:11 UTC
README
⭐ 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.
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), andgetEntityManager(). - Named profiles:
max_retries, exponential backoff with full jitter (backoff_base_ms, aliassleep_ms;backoff_max_ms;jitter),retry_lock_wait_timeout, amax_total_msbudget androllback_on_deadlockper 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
ManagerRegistryso 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
- Installation
- Configuration
- Usage — standard Symfony host and DDD / hexagonal host
- Contributing
- Code of Conduct
- Changelog
- Upgrading
- Release
- Security
- Engram
- Spec-driven development
- GitHub Spec Kit
Additional documentation
- PSR evaluation (REQ-CS-007)
- Demo (Symfony 7 & 8) — run
make -C demo up-symfony8from the bundle root. - Demo with FrankenPHP —
FRANKENPHP_MODE(classic|worker, default worker);make demo-smoke(REQ-TEST-011). - FrankenPHP worker audit — scenario B (
reset_kernel=false) compatibility. - GitHub Actions CI requirements
Tests and coverage
- Tests: PHPUnit (PHP)
- PHP: 100%
License
MIT. See LICENSE.
