Repository navigation
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