Weave Code
Doctrine Retry Bundle Laravel Package
keboola/doctrine-retry-bundle
A Symfony bundle that adds configurable retry logic to Doctrine DBAL connections, helping applications recover from transient database failures and improve resilience with minimal configuration.
[READ-ONLY] Doctrine Retry bundle
Frequently asked questions about Doctrine Retry Bundle
- Does keboola/doctrine-retry-bundle work with Laravel?
- Not as a bundle. The package is a Symfony bundle whose main value is a container compiler pass that rewrites DoctrineBundle's setMiddlewares() call at compile time, and Laravel has no bundle kernel, compiler passes, or DoctrineBundle. A Laravel application only touches Doctrine DBAL if it has opted in through a community ORM bridge, so installing this package changes nothing by default. What does carry over is the small framework-agnostic runtime core: the DBAL driver middleware and the retry driver wrapper, which you can register by hand.
- How do I install keboola/doctrine-retry-bundle with Composer?
- The package installs with composer require keboola/doctrine-retry-bundle, but version 1.2.0 declares strict platform requirements and Composer will hard-fail before any code runs if they are not met. You need PHP 8.4 or newer, doctrine/dbal 4.2 or newer, doctrine/doctrine-bundle 3.0 or newer, and Symfony 7.4 or 8.0. Most Laravel estates on PHP 8.2 or 8.3 with DBAL 3.x will not be able to install it at all.
- Which PHP and Doctrine DBAL versions does version 1.2.0 require?
- Release 1.2.0 requires PHP ^8.4, doctrine/dbal ^4.2, doctrine/doctrine-bundle ^3.0, and Symfony ^7.4|^8.0. The maintainers state explicitly that consumers still on Symfony 6.4 with doctrine-bundle 2.x cannot take this release, because it is a breaking platform bump. Treat it as a platform-upgrade dependency rather than a drop-in retry utility.
- What kinds of database failures does the retry middleware actually handle?
- Only connection establishment is retried. The middleware wraps the driver and overrides connect(), routing it through a keboola/retry RetryProxy so that a dropped or refused connection is re-attempted according to your policy. Queries, transactions, deadlocks raised mid-statement, and lock timeouts during execution are deliberately not replayed, since replaying a statement after a mid-transaction failure is unsafe. Teams expecting a blanket query retry will be surprised by this narrow guarantee.
- How do I configure retry attempts without the Symfony YAML configuration?
- The bundle's YAML configuration feeds a driverOptions entry such as x_connect_retries, which is only read by the Symfony compiler pass. Outside Symfony nothing consumes that key, so you must construct the retry policy and middleware yourself and pass the attempt and delay values directly. In practice you own a small custom convention plus a service provider that registers the middleware.
- Can I use the DBAL retry middleware in Laravel without the Symfony bundle?
- Yes, the runtime classes are plain DBAL API. You register the middleware against Doctrine\DBAL\Configuration::setMiddlewares() through your own service provider. The critical detail is ordering: the retry middleware must be prepended so it is outermost and can observe failures from every other middleware. Any port of that ordering logic inherits the same fragility the original compiler pass has against DoctrineBundle internals.
- How do I test that retry behavior actually works in my application?
- The upstream repository relies on a Toxiproxy integration test to prove the middleware is wired in, which is a good pattern to copy. In a Laravel test suite you can simulate a refused or dropped connection with a proxy that severs the socket on the first attempt and then allows the second through. Assert on connect attempts rather than on query results, because the retry only covers connect().
- Is it safe to retry failed transactions or deadlocks with this package?
- No, and the package does not try. Deadlocks and lock timeouts surface while a statement or transaction is executing, and automatically replaying them risks duplicating partial work. Retry semantics for transactions must be decided per unit of work, typically by re-running the whole closure. Because only connect() is wrapped, this bundle will not reduce failed transactions in high-concurrency workloads the way the marketing copy implies.
- What are the Laravel alternatives to this bundle for database retry logic?
- Laravel already ships transaction-level retries through DB::transaction($callback, $attempts), which re-runs the closure when a deadlock is detected. For connection resilience you can tune the connection options and reconnect handling in config/database.php rather than adopting a middleware. If you genuinely need a DBAL driver middleware later, copying the two small classes from this package is usually cheaper than pulling in the Symfony dependency tree.
- Is this package a safe production choice for a Laravel application?
- It is honest but delicate. The Symfony integration works by removing and re-adding an existing setMiddlewares() call, so if DoctrineBundle changes how it registers middlewares the retry behavior is silently dropped with no error. Combined with the PHP 8.4 and doctrine-bundle 3.x floor, adoption in a Laravel codebase means owning a fork of the middleware plus your own registration and configuration layer. That is viable for a team that wants it, but it is not a low-risk drop-in.
Weaver
How can I help you explore Laravel packages today?