Repository navigation
Releases
Release v3.0.0
v3.0.0
Changelog
Target 3.0.0: the connection is repaired (rolled back, closed only when that fails) after any failure, nested calls
and leftover transactions are no longer retried, retry() clears the entity manager before a replay, backoff is
jittered, DBAL 4 / ORM 3 are required. See UPGRADING.
Fixed
- Nested deadlocks on MySQL / MariaDB no longer surface as 1305 or poison the worker's connection. A deadlock
(1213) inside a nested transaction drops every savepoint; the ORM'sROLLBACK TO SAVEPOINTthen fails with 1305,
and 2.x's blindEntityManager::rollback()before the retry failed with 1305 again and escaped. The connection
stayed at nesting level 2, so the next request ran inside a ghost savepoint (its writes committed immediately).
After any failure the service now rolls back the levels the operation left open and closes the connection only
when that rollback fails (Connection::close()resets the nesting level). Ordinary failures keep session state
(variables,GET_LOCK, advisory locks). Covered by real MySQL 8.4 / MariaDB 11.4 tests. - Inside a caller's transaction a transient failure is no longer retried. The old rollback undid the caller's own
transaction and replayed only the inner operation in auto-commit (PostgreSQL), or failed with 1305 (MySQL). retry()clears an open entity manager before replaying: a raw DBAL failure left the failed attempt's entities
scheduled, and the replay inserted them twice (QA-DDRB-M2).rollback_on_deadlock: falsenever replays on a connection the failure left in a transaction (QA-DDRB-M3).- A 1305 lost savepoint is transient only through the deadlock in its chain: after an implicit commit (DDL inside the
transaction) it was retried and the committed work replayed (QA-DDRB-M1). - Connections with auto-commit disabled are retried at their implicit transaction level (QA-DDRB-L1).
Added
- Detection of transient failures: DBAL
RetryableException, MySQL / MariaDB1213,1205, MariaDB1020,
SQLSTATE40001/40P01/55P03(Failure\TransientFailureClassifier,Failure\TransientFailureKind).
Profile optionretry_lock_wait_timeout(defaultfalse) and time budgetmax_total_ms(default none). - Exponential backoff with full jitter: profile options
backoff_base_ms(default 100),backoff_max_ms(default
2000) andjitter(full|none).sleep_msstays as an alias ofbackoff_base_ms. - Worker guard (opt-in,
worker_guard.enabled): onkernel.request(main request, priority 2048) and
kernel.terminate(priority -2048) a connection left in a transaction is rolled back (one level) or closed
(deeper, or a failed rollback); closed entity managers are reset; open ones are cleared on terminate
(clear_managers). Withmessenger(default on) the same runs after every Messenger message: on a failed message
the connections are repaired at priority 512, beforeSendFailedMessageForRetryListenerwrites the retry envelope,
and managers are cleared at -2048. Only connections and managers the container already initialised are touched.
Onewarningper repair, without SQL. - HTTP mapping (opt-in,
http_mapping.enabled): akernel.exceptionlistener (priority -64) maps transient
failures (andNowo\TransactionContract\TransientStorageFailure) to 503 withRetry-After
(retry_after_seconds, or the exception's hint), andconflict_exceptions(defaultOptimisticLockException,
UniqueConstraintViolationException, not when they wrap a driver error such as "Commit failed") to 409. Scoped by
paths(segment boundaries) /routesprefixes or global;format: exceptionkeeps the host's own rendering,
format: problem_jsonanswers RFC 9457 directly; the client never sees SQL. nowo-tech/transaction-contractadapter:Transaction\DeadlockRetryTransactionRunnerimplements
TransactionRunnerInterface(service idnowo_doctrine_deadlock_retry.transaction_runner):wrapInTransaction()
throughretry(), transient failures rethrown asTransientStorageFailurewithretry_after_seconds; option
transaction_runner.profile. The interface is aliased to it only when nothing defines it (compiler pass, priority
10, so it wins over bundles' one-attempt defaults that follow the recipe; a host's own alias always wins). A
TransientStorageFailurefrom a nested runner is classified by the storage error it carries. New requirement
nowo-tech/transaction-contract ^1.0.Connection\ConnectionRepairer, a public service for bundles that clean up after a failed unit of work.- Optional PSR-3 logger on
DeadlockRetryService: retries atinfo, repairs atnotice, never SQL.
Changed
- Requires
doctrine/dbal ^4.0anddoctrine/orm ^3.0(DBAL 3 / ORM 2 were never tested). - When the service gives up on a transient failure that only Doctrine wrapped, it rethrows the transient exception
itself (theDeadlockException, not the ORM's 1305DriverException). retry()always makes at least one attempt (a negativemax_retrieson a hand-builtRetryProfileused to throw).- The internal "Deadlock retry loop ended without result"
RuntimeExceptionis gone.
Documentation
- USAGE: "High-load readiness" (what goes wrong, worker guard, HTTP mapping, standard Symfony and DDD host examples,
migration guide for bundles with their own reset helpers); "Behaviour on transient failures" replaces "Behaviour on
deadlock". CONFIGURATION: new profile,worker_guardandhttp_mappingoptions.
Documentation
- USAGE: "Using it from a DDD / hexagonal application" with a standard Symfony host section and a DDD / hexagonal
host section (ownTransactionRunnerport, adapter onDeadlockRetryInterface, events after commit), and a
statement that the bundle never flushes or commits on its own (REQ-ARCH-001).
Tests
- Real-database suite (
tests/Database,make test-db, CI job "Real databases"): two sessions cause a real deadlock
in a nested flush on MySQL 8.4 and MariaDB 11.4 (clean retry, nesting level 0, next request commits), a real lock
wait timeout (retried; exhausted → 503 +Retry-After), the worker guard repairing a poisoned connection and
clearing pending changes, a PostgreSQL 16 serialization failure (40001) and lock timeout (55P03), a MariaDB 11.8
snapshot conflict (1020), the Messenger repair before the retry envelope, themax_total_msbound (budget plus
one attempt), and the QA audit regressions (implicit commit not retried, dirty manager cleared, no
replay on a leftover transaction, auto-commit off retried, session locks kept after a domain failure). - DDD host case: plain-PHP aggregate, host
TransactionRunnerport and an adapter on the container's
DeadlockRetryInterfacealias; a deadlock closes the manager, the unit of work is replayed on the reset manager and
the domain event is published once, after commit.
What's Changed
- docs(arch): DDD / hexagonal host section and DDD host test (REQ-ARCH-001) by @HecFranco in #68
- feat!: load readiness: connection repair, jittered backoff, worker guard and HTTP mapping by @HecFranco in #69
Full Changelog: v2.4.0...v3.0.0
Release v2.4.0
v2.4.0
Changelog
Added
Contract\DeadlockRetryInterface(flush(),retry(),getProfileNames(),getDefaultProfileName()), implemented byDeadlockRetryServiceand aliased in the container (REQ-ARCH-001 rule 1). It carries no Doctrine type;getEntityManager()stays on the concrete service.
What's Changed
- feat(arch): DeadlockRetryInterface contract (REQ-ARCH-001 r1) by @HecFranco in #67
Full Changelog: v2.3.0...v2.4.0
Release v2.3.0
v2.3.0
Changelog
Changed
- Demo uses the UiKit base style (REQ-DEMO-014)
Tests
- Kept-alive container test (1,200 calls, two tenants, memory bound) and refreshed
docs/FRANKENPHP-WORKER-AUDIT.md(REQ-RUNTIME-002).
What's Changed
- chore(deps): bump the phpstan group across 1 directory with 2 updates by @dependabot[bot] in #57
- chore(deps): Symfony security release 2026-11-04 by @HecFranco in #58
- chore(deps): bump doctrine/orm from 3.7.5 to 3.7.6 by @dependabot[bot] in #59
- chore(deps): Dependabot batch 2026-11-09 by @HecFranco in #62
- ci: run the PR title check on pull_request by @HecFranco in #63
- ci: run the igor worker-state audit by @HecFranco in #64
- test: kept-alive worker test and refreshed worker audit (REQ-RUNTIME-002) by @HecFranco in #65
- chore(demo): UiKit base style (REQ-DEMO-014) by @HecFranco in #66
Full Changelog: v2.2.2...v2.3.0
Release v2.2.2
v2.2.2
Changelog
DoctrineDeadlockRetry: only driver-level deadlocks (SQLSTATE 40001 / MySQL 1213) are retried. See UPGRADING.
Fixed
- Deadlock detection is limited to driver errors. Code
1213matched on any exception in the chain, so an
application exception using that code replayed the operation. OnlyDeadlockException, DBAL driver exceptions and
PDOException(SQLSTATE40001or MySQL1213) are retried now.
Documentation
- USAGE: call
retry()/flush()outside your own transactions; a deadlock rollback undoes the outer transaction.
What's Changed
- fix: retry only on driver-level deadlocks by @HecFranco in #54
Full Changelog: v2.2.1...v2.2.2
Release v2.2.1
v2.2.1
Changelog
Wave-2 REQ compliance: demo DebugBundle and update-bundle in demo release-check, fixed igor target. See UPGRADING.
Changed
- Makefile
igortarget fixed (it called an undefined$(COMPOSE)and failed inrelease-check; REQ-CS-008 / REQ-MAKE-002). - Demo:
symfony/debug-bundleinstalled and registered for dev/test (REQ-DEMO-001);make -C demo release-checkrunsupdate-bundlein every demo before the tests (newupdate-bundle-all, REQ-DEMO-007). .scripts/check-no-cursor-coauthor.shaccepts git worktrees (REQ-GIT-001); Rector capped at 2 parallel workers.- Dependencies refreshed (Composer and pnpm/npm lock files of the bundle and its demos, campaign 2026-10-19).
.php-cs-fixer.dist.php:new ParallelConfig(2)(REQ-CS-001).- Documentation: wave-1 REQ compliance — README documentation list order (PSR under Additional documentation) and canonical FrankenPHP claim line, CONTRIBUTING Cursor Agent settings and post-release-commit trailer check, canonical bug-report template, doc TOCs, demo
DATABASE_URLcomment.
What's Changed
- chore(deps): bump nowo-tech/phpstan-frankenphp from 1.2.3 to 1.3.0 by @dependabot[bot] in #53
Full Changelog: v2.2.0...v2.2.1
Release v2.2.0
Release v2.2.0: deadlock rethrown on closed manager without registry; entity_manager option; Symfony floors aligned.
Changelog
Added
entity_manageroption (defaultnull= default entity manager): name of the Doctrine entity manager the service flushes and resets, for multi-EM apps. Wiresdoctrine.orm.<name>_entity_managerand passes the name toManagerRegistry.
Fixed
retry()without aManagerRegistrykept retrying after a deadlock closed the entity manager, so the next attempt failed with "EntityManager is closed" and the original deadlock was hidden. The originalDeadlockExceptionis now rethrown when the closed manager cannot be reset.
Changed
- Symfony constraints normalised to
^6.4 || ^7.4 || ^8.0(7.0–7.3 were allowed but never tested: the7.0CI cell resolved to 7.4 and is dropped). README / INSTALLATION / badge and the CI header comment now match the matrix (6.4, 7.4, 8.0, 8.1).
Full Changelog: v2.1.3...v2.2.0
Release v2.1.3
Release v2.1.3: dependency refresh and repository maintenance.
Changelog
Changed
- Development:
composer.jsonpinsconfig.platform.phpto 8.2.0 so the committed lock stays installable on the minimum PHP; CI overrides the platform per matrix cell.
Dependencies
doctrine/orm3.7.4 → 3.7.5 (development lock; #52).
What's Changed
- chore(deps): bump doctrine/orm from 3.7.4 to 3.7.5 by @dependabot[bot] in #52
Full Changelog: v2.1.2...v2.1.3
Release v2.1.2
v2.1.2
Changelog
Dependencies
- Dependabot:
doctrine/dbal4.5.0,doctrine/orm3.7.3, devigor-php/igor-php0.10,nowo-tech/phpstan-frankenphp1.2.1,phpstan/phpstan-phpunit. - Lock refresh:
doctrine/orm3.7.4; dev PHPStan 2.3.1 (+ phpunit/symfony extensions 2.1), PHPUnit 10.5.66, Rector 2.7.0. - Demo (Symfony 8):
doctrine/orm3.7.4,doctrine/dbal4.5.0, Twig 3.30.0, HotReloadBundle 1.5.5, TwigInspectorBundle 1.1.7.
What's Changed
- chore(deps): bump doctrine/dbal from 4.4.4 to 4.5.0 by @dependabot[bot] in #46
- chore(deps): bump nowo-tech/phpstan-frankenphp from 1.1.3 to 1.2.0 by @dependabot[bot] in #47
- chore(deps): bump phpstan/phpstan-phpunit from 2.0.18 to 2.0.21 in the phpstan group by @dependabot[bot] in #48
- chore(deps): bump igor-php/igor-php from 0.9.7 to 0.10.0 by @dependabot[bot] in #49
- chore(deps): bump doctrine/orm from 3.7.2 to 3.7.3 by @dependabot[bot] in #50
- chore(deps): bump nowo-tech/phpstan-frankenphp from 1.2.0 to 1.2.1 by @dependabot[bot] in #51
Full Changelog: v2.1.1...v2.1.2
Release v2.1.1
v2.1.1
Changelog
Added
- REQ-CS-008:
igor-php/igor-php(require-dev only), rootigor.json, Composer/Makefileigortarget, andrelease-checkwiring for FrankenPHP worker-state audit.
Changed
- Worker safety (Igor): justified
// @igor-ignoreannotations and/orResetInterface/ request-scoped fixes somake igorpasses on packagesrc/.
Full Changelog: v2.1.0...v2.1.1
Release v2.1.0
Release v2.1.0
Changelog
Fixed
- FrankenPHP worker mode / long-running processes: a failed flush (deadlock or other error) no longer leaves the entity manager closed for later attempts and requests.
DeadlockRetryServiceresets a closed manager throughDoctrine\Persistence\ManagerRegistry(wired todoctrinewhen available) before retrying or rethrowing. Seedocs/FRANKENPHP-WORKER-AUDIT.md. flush()rethrows the original deadlock when the manager was closed by it, instead of failing on the retry withEntityManagerClosed(the unit of work cannot be replayed on a new manager).
Added
DeadlockRetryService::getEntityManager(): returns the current (open) entity manager, for use insideretry()callables.- Optional constructor arguments
?ManagerRegistry $managerRegistry = nulland?string $entityManagerName = null.
Changed
- QA: PHPStan FrankenPHP rulesets upgraded to
ruleset-classic.neon+ruleset-worker-strict.neon(worker-strict includes worker).
Documentation
- FrankenPHP worker audit (
docs/FRANKENPHP-WORKER-AUDIT.md), USAGE / UPGRADING for closed-manager recovery, Spec Kit baseline updated for FR-SVC-003/004 and FR-DI-001.
What's Changed
- chore(deps): bump friendsofphp/php-cs-fixer from 3.95.22 to 3.95.23 by @dependabot[bot] in #38
- chore(deps): bump rector/rector from 2.6.3 to 2.6.4 by @dependabot[bot] in #37
- fix(demo): pdo_mysql and MySQL retry for demo-smoke by @HecFranco in #39
- chore(deps): bump phpstan/phpstan from 2.2.10 to 2.2.13 in the phpstan group by @dependabot[bot] in #40
- chore(deps): bump rector/rector from 2.6.4 to 2.6.6 by @dependabot[bot] in #41
- chore(deps): bump friendsofphp/php-cs-fixer from 3.95.23 to 3.95.24 by @dependabot[bot] in #42
- chore(deps): bump phpstan/phpstan from 2.2.13 to 2.2.14 in the phpstan group by @dependabot[bot] in #43
- chore(deps): bump rector/rector from 2.6.6 to 2.6.7 by @dependabot[bot] in #44
- chore(deps): bump doctrine/orm from 3.7.0 to 3.7.1 by @dependabot[bot] in #45
Full Changelog: v2.0.9...v2.1.0