Download the PHP package ahed92wakim/laravel-db-transaction-retry without Composer

Resilient database transactions for Laravel applications that need to gracefully handle deadlocks, serialization failures, and any other transient database errors you configure. This helper wraps DB::transaction() with targeted retries, retry event persistence, and exponential backoff so you can keep your business logic simple while surviving temporary contention.

Highlights

• Retries known transient failures out of the box (SQLSTATE 40001, MySQL driver errors 1213 and 1205), and lets you add extra SQLSTATE codes, driver error codes, or exception classes through configuration.
• Exponential backoff with jitter between attempts to reduce stampedes under load.
• Retry events persisted to transaction_retry_events with request metadata, SQL, bindings, connection information, and stack traces.
• Captures exception classes and codes, making it easy to see exactly what triggered the retry.
• Request-level query logging stored in db_request_logs, with each query stored in db_query_logs.
• Optional transaction labels for easier traceability across microservices and jobs.
• Laravel package auto-discovery; no manual service provider registration required.

Installation

The package ships with the DatabaseTransactionRetryServiceProvider, which Laravel auto-discovers. No additional setup is needed.

If you want the package to persist retry events, request logs, slow transaction logs, or query exceptions, publish the package assets and run the migrations before relying on the dashboard/telemetry features:

Usage

runWithRetry() returns the value produced by your callback, just like DB::transaction(). If every attempt fails, the last exception is re-thrown so your calling code can continue its normal error handling.

DB Macro Convenience

Prefer working through the database facade? Call the included transactionWithRetry macro and keep identical behaviour and parameters:

Need connection-specific logic? Because the macro is applied to Illuminate\Support\Facades\DB and to every resolved Illuminate\Database\Connection, you can call it on connection instances as well:

The macro is registered automatically when the service provider boots, and sets the tx.label container binding the same way as the helper.

Parameters

Call the helper anywhere you would normally open a transaction—controllers, jobs, console commands, or domain services.

Configuration

Publish the configuration file to tweak defaults globally:

You can also run php artisan db-transaction-retry:install to publish the config, migrations, auth provider stub, and dashboard in one step.

• Key options (config/database-transaction-retry.php):

• max_retries and retry_delay set the package-wide defaults when you omit parameters. Each respects environment variables (DB_TRANSACTION_RETRY_MAX_RETRIES, DB_TRANSACTION_RETRY_DELAY).
• state_path controls where the retry toggle marker file is stored (defaults to storage_path('database-transaction-retry/runtime')). Set DB_TRANSACTION_RETRY_STATE_PATH if your deployment requires a custom writable location.
• lock_wait_timeout_seconds lets you override innodb_lock_wait_timeout per attempt; set the matching environment variable (DB_TRANSACTION_RETRY_LOCK_WAIT_TIMEOUT) to control the session value or leave null to use the database default.
• logging.table lets you override the database table name (defaults to transaction_retry_events).
• logging.levels.success / logging.levels.failure / logging.levels.attempt let you tune the severity emitted for successful retries, per-attempt entries, and exhausted attempts (defaults: warning, warning, and error).
• retryable_exceptions.sql_states lists SQLSTATE codes that should trigger a retry (defaults to 40001).
• retryable_exceptions.driver_error_codes lists driver-specific error codes (defaults to 1213 deadlocks and 1205 lock wait timeouts). Including 1205 not only enables retries but also activates the optional session lock wait timeout override when configured.
• retryable_exceptions.classes lets you specify fully-qualified exception class names that should always be retried.
• request_logging.enabled enables or disables request logging (requests with at least one query).
• request_logging.log_table and request_logging.query_table let you override the request and query log tables (defaults: db_request_logs, db_query_logs).
• dashboard.path sets the UI path (defaults to /transaction-retry).
• dashboard.middleware lets you attach middleware to the dashboard UI route (for example web, auth, or can:viewTransactionRetryDashboard).
• api.prefix sets the JSON API prefix (defaults to /api/transaction-retry).
• api.middleware lets you attach middleware to the JSON API routes (for example web, auth, or a custom gate).

Database Migration

Retry events are stored in the database by default. Publish the migration and run it:

Or publish manually:

The migrations create the transaction_retry_events, db_transaction_logs, db_query_logs, db_request_logs, and db_exceptions tables by default.

Dashboard (Next.js UI)

The package ships a static Next.js dashboard that is published into your Laravel app's public/vendor/laravel-db-transaction-retry/{dashboard.path} directory. By default, it is available at:

• UI: /transaction-retry
• API: /api/transaction-retry/events

Route tables in the dashboard link to a per-route detail view. The request metrics endpoints (/metrics/requests, /metrics/requests-duration, and /requests) accept optional method, route_name, and url filters to scope data to a single route.

Securing the dashboard

By default the dashboard uses the AuthorizeTransactionRetryDashboard middleware, which only allows access in the local environment until you define your own authorization logic (mirroring Telescope). The install command publishes an app/Providers/TransactionRetryDashboardServiceProvider.php stub you can edit.

To customize access, define a gate and register the authorization callback in one of your application service providers:

Register the published service provider in bootstrap/providers.php (Laravel 11/12):

You can also swap the middleware stack for the dashboard and API routes in config/database-transaction-retry.php:

Define the viewTransactionRetryDashboard gate in your application (or swap in any other middleware).

Publish the dashboard assets:

The db-transaction-retry:install command publishes the dashboard too.

Rebuilding the UI (package contributors)

If you are working on the package itself and want to rebuild the dashboard:

This writes static assets to dashboard/out, which are published to the host app's public/vendor/laravel-db-transaction-retry/{dashboard.path} directory.

Uninstall

When you remove the package with Composer, the service provider listens for the composer_package.ahed92wakim/laravel-db-transaction-retry:pre_uninstall event and cleans up published assets (similar to Telescope). It also removes the published dashboard service provider from bootstrap/providers.php when available. It deletes:

• config/database-transaction-retry.php
• app/Providers/TransactionRetryDashboardServiceProvider.php
• Published migrations for the retry events, transaction logs, request logs, query logs, and exception tables
• The published dashboard assets under public/vendor/laravel-db-transaction-retry/{dashboard.path}

Database tables are not dropped automatically. If you want to remove them, drop the tables manually or run your own cleanup migration.

Partition Maintenance (MySQL)

The migration creates hourly partitions for MySQL. Keep partitions rolling by scheduling the command to run hourly:

Make sure your scheduler is running (for example, the standard schedule:run cron).

Retry Conditions

Retries are attempted when the caught exception matches one of the configured conditions:

• Illuminate\Database\QueryException for MySQL deadlocks (1213) when retry_on_deadlock is enabled (default).
• Illuminate\Database\QueryException for MySQL lock wait timeouts (1205) when retry_on_lock_wait_timeout is enabled.

Everything else (e.g., constraint violations, syntax errors, application exceptions) is surfaced immediately without logging or sleeping. If no attempt succeeds and all retries are exhausted, the last exception is re-thrown. In the rare case nothing is thrown but the loop exits, a RuntimeException is raised to signal exhaustion.

Lock Wait Timeout

When lock_wait_timeout_seconds is configured, the retrier issues SET SESSION innodb_lock_wait_timeout = {seconds} on the active connection before each attempt, but only when retry_on_lock_wait_timeout is enabled. This keeps the timeout predictable even after reconnects or pool reuse, and on drivers that do not support the statement the helper safely ignores the failure.

Retry Event Storage

Retry events are stored in the transaction_retry_events table. Each retryable exception attempt is persisted, plus a final success or failure entry once the retrier finishes:

• Success after retries → a row with retry_status=success.
• Failure after exhausting retries → a row with retry_status=failure.
• Intermediate retryable failures → rows with retry_status=attempt.

Each retry event stores:

• Attempt count, maximum retries, transaction label, and retry status (attempt/success/failure).
• A retry group ID to correlate attempts and the final outcome for a single transaction.
• Exception class, SQLSTATE, driver error code, connection name, SQL, bindings, resolved raw SQL, and PDO error info when available.
• A compacted stack trace and request URL, method, authorization header length, and authenticated user ID/type (UUID or integer) when the request helper is bound.

Runtime Toggle

Use the built-in Artisan commands to temporarily disable or re-enable retries without touching configuration files:

The commands write a small marker file inside the package (storage/runtime/retry-disabled.marker). As long as that file exists retries stay off; removing it or running db-transaction-retry:start brings them back. You can still set the DB_TRANSACTION_RETRY_ENABLED environment variable for a permanent default.

Heads up: The db-transaction-retry:start command only removes the disable marker—it does not override an explicit database-transaction-retry.enabled=false configuration (including the DB_TRANSACTION_RETRY_ENABLED=false environment variable). Update that setting to true if you want retries to remain enabled after the current process.

Helper Utilities

The package exposes dedicated support classes you can reuse in your own instrumentation:

• DatabaseTransactions\RetryHelper\Support\TransactionRetryLogWriter writes retry events to the retry events table.
• DatabaseTransactions\RetryHelper\Support\TraceFormatter converts debug backtraces into log-friendly arrays.
• DatabaseTransactions\RetryHelper\Support\BindingStringifier sanitises query bindings before logging.

For testing scenarios, the retrier looks for a namespaced DatabaseTransactions\RetryHelper\sleep() function before falling back to PHP's global sleep(), making it easy to assert backoff intervals without introducing delays.

Testing the Package

Run the test suite with:

Tests cover the retry flow, database event persistence, exponential backoff jitter, and non-retryable scenarios using database fakes.

Requirements

• PHP >= 8.2
• Laravel >= 11.0

Changelog

Notable changes are tracked in CHANGELOG.md.

Contributing

Bugs, ideas, and pull requests are welcome. Feel free to open an issue describing the problem or improvement before submitting a PR so we can collaborate on scope.

License

This package is open-sourced software released under the MIT License.