Adds lock wait timeout retry and configuration

Adds the ability to retry transactions that fail due to lock wait timeouts.

Introduces a configuration option to set the session-level lock wait timeout before each transaction attempt. This helps to prevent indefinite waiting and ensures a predictable timeout, even after reconnections or pool reuse.

Updates the documentation to reflect the new functionality and configuration options.

Author: Ahed92Wakim

.gitignore

@@ -4,3 +4,5 @@ vendor/
 .idea/
 .vscode/
 .DS_Store
+
+.php-cs-fixer.cache

.php-cs-fixer.cache

@@ -1 +1 @@
-{"php":"8.2.29","version":"3.89.0:v3.89.0#4dd6768cb7558440d27d18f54909eee417317ce9","indent":"    ","lineEnding":"\n","rules":{"binary_operator_spaces":{"default":"align_single_space_minimal"},"blank_line_after_opening_tag":true,"blank_line_between_import_groups":true,"blank_lines_before_namespace":true,"braces_position":{"allow_single_line_empty_anonymous_classes":true},"class_definition":{"inline_constructor_arguments":false,"space_before_parenthesis":true},"compact_nullable_type_declaration":true,"declare_equal_normalize":true,"lowercase_cast":true,"lowercase_static_reference":true,"modifier_keywords":true,"new_with_parentheses":{"anonymous_class":true},"no_blank_lines_after_class_opening":true,"no_extra_blank_lines":true,"no_leading_import_slash":true,"no_whitespace_in_blank_line":true,"ordered_class_elements":{"order":["use_trait"]},"ordered_imports":{"sort_algorithm":"alpha"},"return_type_declaration":true,"short_scalar_cast":true,"single_import_per_statement":{"group_to_single_imports":false},"single_space_around_construct":{"constructs_followed_by_a_single_space":["abstract","as","case","catch","class","const_import","do","else","elseif","final","finally","for","foreach","function","function_import","if","insteadof","interface","namespace","new","private","protected","public","static","switch","trait","try","use","use_lambda","while"],"constructs_preceded_by_a_single_space":["as","else","elseif","use_lambda"]},"single_trait_insert_per_statement":true,"ternary_operator_spaces":true,"unary_operator_spaces":{"only_dec_inc":true},"blank_line_after_namespace":true,"constant_case":true,"control_structure_braces":true,"control_structure_continuation_position":true,"elseif":true,"function_declaration":{"closure_fn_spacing":"one"},"indentation_type":true,"line_ending":true,"lowercase_keywords":true,"method_argument_space":{"after_heredoc":false,"attribute_placement":"ignore","on_multiline":"ensure_fully_multiline"},"no_break_comment":true,"no_closing_tag":true,"no_multiple_statements_per_line":true,"no_space_around_double_colon":true,"no_spaces_after_function_name":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":{"elements":["property"]},"single_line_after_imports":true,"spaces_inside_parentheses":true,"statement_indentation":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"encoding":true,"full_opening_tag":true,"array_syntax":{"syntax":"short"},"single_quote":true,"no_unused_imports":true,"no_superfluous_phpdoc_tags":true,"phpdoc_trim":true,"phpdoc_align":{"align":"left"},"blank_line_before_statement":{"statements":["return"]},"simplified_null_return":true,"void_return":true},"hashes":{"tests\/bootstrap.php":"4ae74313e457f6662f4831ee2140eb34","src\/Providers\/DatabaseTransactionRetryServiceProvider.php":"1071a19b80835472e035374cc17b7056","src\/Services\/TransactionRetrier.php":"01b810fda87e28b849389c952b6141e9","src\/Support\/BindingStringifier.php":"bbead2bae37761124652320cd28db412","src\/Support\/TransactionRetryLogWriter.php":"149e31651f0e22a15a7df90c9edb5baa","src\/Support\/TraceFormatter.php":"e640e32b17149f1cfec9a1d990f04c84","tests\/TestCase.php":"a45ed4c82e3b3f4ad47544b81fda41f5","tests\/Unit\/ExampleTest.php":"3bbd4ea8029698f723c35a66d8592087","tests\/Unit\/DBTransactionRetryHelperTest.php":"7202d36b32e4d5c70cc19d83392cdda1","tests\/Feature\/ExampleTest.php":"a1e5352ea369ad36f88f4f566c340371","tests\/Pest.php":"44a41307b2bca2c9b747aa2f40c5262b"}}
+{"php":"8.2.29","version":"3.89.0:v3.89.0#4dd6768cb7558440d27d18f54909eee417317ce9","indent":"    ","lineEnding":"\n","rules":{"binary_operator_spaces":{"default":"align_single_space_minimal"},"blank_line_after_opening_tag":true,"blank_line_between_import_groups":true,"blank_lines_before_namespace":true,"braces_position":{"allow_single_line_empty_anonymous_classes":true},"class_definition":{"inline_constructor_arguments":false,"space_before_parenthesis":true},"compact_nullable_type_declaration":true,"declare_equal_normalize":true,"lowercase_cast":true,"lowercase_static_reference":true,"modifier_keywords":true,"new_with_parentheses":{"anonymous_class":true},"no_blank_lines_after_class_opening":true,"no_extra_blank_lines":true,"no_leading_import_slash":true,"no_whitespace_in_blank_line":true,"ordered_class_elements":{"order":["use_trait"]},"ordered_imports":{"sort_algorithm":"alpha"},"return_type_declaration":true,"short_scalar_cast":true,"single_import_per_statement":{"group_to_single_imports":false},"single_space_around_construct":{"constructs_followed_by_a_single_space":["abstract","as","case","catch","class","const_import","do","else","elseif","final","finally","for","foreach","function","function_import","if","insteadof","interface","namespace","new","private","protected","public","static","switch","trait","try","use","use_lambda","while"],"constructs_preceded_by_a_single_space":["as","else","elseif","use_lambda"]},"single_trait_insert_per_statement":true,"ternary_operator_spaces":true,"unary_operator_spaces":{"only_dec_inc":true},"blank_line_after_namespace":true,"constant_case":true,"control_structure_braces":true,"control_structure_continuation_position":true,"elseif":true,"function_declaration":{"closure_fn_spacing":"one"},"indentation_type":true,"line_ending":true,"lowercase_keywords":true,"method_argument_space":{"after_heredoc":false,"attribute_placement":"ignore","on_multiline":"ensure_fully_multiline"},"no_break_comment":true,"no_closing_tag":true,"no_multiple_statements_per_line":true,"no_space_around_double_colon":true,"no_spaces_after_function_name":true,"no_trailing_whitespace":true,"no_trailing_whitespace_in_comment":true,"single_blank_line_at_eof":true,"single_class_element_per_statement":{"elements":["property"]},"single_line_after_imports":true,"spaces_inside_parentheses":true,"statement_indentation":true,"switch_case_semicolon_to_colon":true,"switch_case_space":true,"encoding":true,"full_opening_tag":true,"array_syntax":{"syntax":"short"},"single_quote":true,"no_unused_imports":true,"no_superfluous_phpdoc_tags":true,"phpdoc_trim":true,"phpdoc_align":{"align":"left"},"blank_line_before_statement":{"statements":["return"]},"simplified_null_return":true,"void_return":true},"hashes":{"tests\/bootstrap.php":"4ae74313e457f6662f4831ee2140eb34","src\/Providers\/DatabaseTransactionRetryServiceProvider.php":"1071a19b80835472e035374cc17b7056","src\/Services\/TransactionRetrier.php":"7d99d773c44861e3f12524a5119f5240","src\/Support\/BindingStringifier.php":"bbead2bae37761124652320cd28db412","src\/Support\/TransactionRetryLogWriter.php":"149e31651f0e22a15a7df90c9edb5baa","src\/Support\/TraceFormatter.php":"e640e32b17149f1cfec9a1d990f04c84","tests\/TestCase.php":"a45ed4c82e3b3f4ad47544b81fda41f5","tests\/Unit\/ExampleTest.php":"3bbd4ea8029698f723c35a66d8592087","tests\/Unit\/DBTransactionRetryHelperTest.php":"07bb6b8e6c8b3ce61a7e67f128f12f4a","tests\/Feature\/ExampleTest.php":"a1e5352ea369ad36f88f4f566c340371","tests\/Pest.php":"44a41307b2bca2c9b747aa2f40c5262b"}}

README.md

@@ -22,7 +22,7 @@ Resilient database transactions for Laravel applications that need to gracefully
 
 ## Highlights
 
-- Retries known transient failures out of the box (SQLSTATE `40001`, MySQL driver error `1213`), and lets you add extra SQLSTATE codes, driver error codes, or exception classes through configuration.
+- 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.
 - Structured logs with request metadata, SQL, bindings, connection information, and stack traces written to dated files under `storage/logs/{Y-m-d}`.
 - Log titles include the exception class and codes, making it easy to see exactly what triggered the retry.
@@ -77,29 +77,33 @@ Publish the configuration file to tweak defaults globally:
 php artisan vendor:publish --tag=database-transaction-retry-config
 ```
 
-Key options (`config/database-transaction-retry.php`):
+- Key options (`config/database-transaction-retry.php`):
 
 - `max_retries`, `retry_delay`, and `log_file_name` set the package-wide defaults when you omit parameters. Each respects environment variables (`DB_TRANSACTION_RETRY_MAX_RETRIES`, `DB_TRANSACTION_RETRY_DELAY`, `DB_TRANSACTION_RETRY_LOG_FILE`).
+- `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.channel` points at any existing Laravel log channel so you can reuse stacks or third-party drivers.
-- `logging.config` provides a full configuration array for `Log::build()` when you want a dedicated writer.
 - `logging.levels.success` / `logging.levels.failure` let you tune the severity emitted for successful retries and exhausted attempts (defaults: `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`).
+- `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.
 
 ## Retry Conditions
 
 Retries are attempted when the caught exception matches one of the configured conditions:
 
 - `Illuminate\Database\QueryException` with a SQLSTATE listed in `retryable_exceptions.sql_states`.
-- `Illuminate\Database\QueryException` with a driver error code listed in `retryable_exceptions.driver_error_codes`.
+- `Illuminate\Database\QueryException` with a driver error code listed in `retryable_exceptions.driver_error_codes` (defaults include `1213` deadlocks and `1205` lock wait timeouts).
 - Any exception instance whose class appears in `retryable_exceptions.classes`.
 
 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 the retry rules include the lock-wait timeout driver code (`1205`). 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.
+
 ## Logging Behaviour
 
-By default, logs are written using a dedicated single-file channel per day. Override `logging.channel` or `logging.config` to integrate with your own logging stack:
+By default, logs are written using a dedicated single-file channel per day. Override `logging.channel` to integrate with your own logging stack:
 
 - Success after retries → a warning entry titled `"[trxLabel] [DATABASE TRANSACTION RETRY - SUCCESS] ExceptionClass (Codes) After (Attempts: x/y) - Warning"`.
 - Failure after exhausting retries → an error entry titled `"[trxLabel] [DATABASE TRANSACTION RETRY - FAILED] ExceptionClass (Codes) After (Attempts: x/y) - Error"`.

config/database-transaction-retry.php

@@ -16,6 +16,21 @@
 
     'retry_delay' => (int) env('DB_TRANSACTION_RETRY_DELAY', 2),
 
+    /*
+    |--------------------------------------------------------------------------
+    | Lock Wait Timeout
+    |--------------------------------------------------------------------------
+    |
+    | Optionally override the session-level lock wait timeout before executing
+    | the transaction. When set to a positive integer the helper issues:
+    | "SET SESSION innodb_lock_wait_timeout = {seconds}" on the active
+    | connection prior to each attempt. Set to null to leave the database
+    | default untouched.
+    |
+    */
+
+    'lock_wait_timeout_seconds' => env('DB_TRANSACTION_RETRY_LOCK_WAIT_TIMEOUT', 50),
+
     'log_file_name' => env('DB_TRANSACTION_RETRY_LOG_FILE', 'database/transaction-retries'),
 
     /*
@@ -34,8 +49,6 @@
     'logging' => [
         'channel' => env('DB_TRANSACTION_RETRY_LOG_CHANNEL'),
 
-        'config' => null,
-
         'levels' => [
             'success' => env('DB_TRANSACTION_RETRY_LOG_SUCCESS_LEVEL', 'warning'),
             'failure' => env('DB_TRANSACTION_RETRY_LOG_FAILURE_LEVEL', 'error'),
@@ -60,6 +73,7 @@
 
         'driver_error_codes' => [
             1213, // MySQL deadlock
+            //1205, // MySQL lock wait timeout
         ],
 
         'classes' => [],

src/Services/TransactionRetrier.php

@@ -50,6 +50,8 @@ public static function runWithRetry(
             $shouldRetryError = false;
 
             try {
+                static::applyLockWaitTimeout($config);
+
                 // Expose the transaction label if the app wants to read it during the callback.
                 $trxLabel === '' || app()->instance('tx.label', $trxLabel);
 
@@ -296,4 +298,46 @@ protected static function normalizeLogLevel(?string $level, string $fallback): s
 
         return $candidate !== '' ? $candidate : $fallback;
     }
+
+    protected static function applyLockWaitTimeout(array $config): void
+    {
+        $seconds = $config['lock_wait_timeout_seconds'] ?? null;
+
+        if (! static::isLockWaitRetryEnabled($config)) {
+            return;
+        }
+
+        if (is_null($seconds)) {
+            return;
+        }
+
+        if (is_string($seconds) && $seconds === '') {
+            return;
+        }
+
+        $seconds = (int) $seconds;
+
+        if ($seconds < 1) {
+            return;
+        }
+
+        try {
+            DB::statement('SET SESSION innodb_lock_wait_timeout = ?', [$seconds]);
+        } catch (Throwable) {
+            // Silently ignore when the underlying driver does not support this option.
+        }
+    }
+
+    protected static function isLockWaitRetryEnabled(array $config): bool
+    {
+        $retryable = is_array($config['retryable_exceptions'] ?? null)
+            ? $config['retryable_exceptions']
+            : [];
+
+        $driverCodes = is_array($retryable['driver_error_codes'] ?? null)
+            ? array_map(static fn ($code) => (int) $code, $retryable['driver_error_codes'])
+            : [];
+
+        return in_array(1205, $driverCodes, true);
+    }
 }

tests/Unit/DBTransactionRetryHelperTest.php

@@ -110,6 +110,74 @@ function sleep(int $seconds): void
     expect(SleepSpy::$delays)->toBe([]);
 });
 
+test('retries on lock wait timeout and applies configured session timeout', function (): void {
+    Container::getInstance()->make('config')->set(
+        'database-transaction-retry.lock_wait_timeout_seconds',
+        7
+    );
+
+    Container::getInstance()->make('config')->set(
+        'database-transaction-retry.retryable_exceptions.driver_error_codes',
+        [1205]
+    );
+
+    $attempts = 0;
+
+    $result = TransactionRetrier::runWithRetry(function () use (&$attempts) {
+        $attempts++;
+
+        if ($attempts === 1) {
+            throw makeQueryException(1205, 'HY000');
+        }
+
+        return 'done';
+    }, maxRetries: 3, retryDelay: 1, trxLabel: 'lock-wait');
+
+    expect($result)->toBe('done');
+    expect($this->database->transactionCalls)->toBe(2);
+    expect(SleepSpy::$delays)->toHaveCount(1);
+    expect($this->database->statementCalls)->toHaveCount(2);
+
+    [$statement, $bindings] = $this->database->statementCalls[0];
+    expect($statement)->toBe('SET SESSION innodb_lock_wait_timeout = ?');
+    expect($bindings)->toBe([7]);
+
+    $record = $this->logManager->records[0];
+    expect($record['context']['driverCode'])->toBe(1205);
+    expect($record['context']['sqlState'])->toBe('HY000');
+    expect($record['message'])->toContain('Driver 1205');
+    expect($record['message'])->toContain('SQLSTATE HY000');
+});
+
+test('does not change session timeout when lock wait retry disabled', function (): void {
+    Container::getInstance()->make('config')->set(
+        'database-transaction-retry.lock_wait_timeout_seconds',
+        9
+    );
+
+    Container::getInstance()->make('config')->set(
+        'database-transaction-retry.retryable_exceptions.driver_error_codes',
+        [1213]
+    );
+
+    Container::getInstance()->make('config')->set(
+        'database-transaction-retry.retryable_exceptions.sql_states',
+        []
+    );
+
+    try {
+        TransactionRetrier::runWithRetry(function (): void {
+            throw makeQueryException(1205, 'HY000');
+        }, maxRetries: 2, retryDelay: 1);
+
+        $this->fail('Expected QueryException was not thrown.');
+    } catch (QueryException $th) {
+        expect($th->errorInfo[1])->toBe(1205);
+    }
+
+    expect($this->database->statementCalls)->toBe([]);
+});
+
 test('retries when driver code is configured', function (): void {
     Container::getInstance()->make('config')->set(
         'database-transaction-retry.retryable_exceptions.driver_error_codes',
@@ -167,10 +235,18 @@ function sleep(int $seconds): void
     expect(array_key_exists('sqlState', $record['context']))->toBeFalse();
 });
 
-function makeQueryException(int $driverCode, int $sqlState = 40001): QueryException
+function makeQueryException(int $driverCode, string|int $sqlState = 40001): QueryException
 {
-    $sqlStateString = str_pad((string) $sqlState, 5, '0', STR_PAD_LEFT);
-    $pdo            = new \PDOException('SQLSTATE[' . $sqlStateString . ']: Driver error', $sqlState);
+    $sqlStateString = strtoupper((string) $sqlState);
+
+    if (strlen($sqlStateString) < 5) {
+        $sqlStateString = str_pad($sqlStateString, 5, '0', STR_PAD_LEFT);
+    }
+
+    $pdo = new \PDOException(
+        'SQLSTATE[' . $sqlStateString . ']: Driver error',
+        is_numeric($sqlState) ? (int) $sqlState : 0
+    );
     $pdo->errorInfo = [$sqlStateString, $driverCode, 'Driver error'];
 
     return new QueryException(
@@ -188,6 +264,8 @@ final class CustomRetryException extends \RuntimeException
 final class FakeDatabaseManager
 {
     public int $transactionCalls = 0;
+    /** @var list<array{0:string,1:array}> */
+    public array $statementCalls = [];
     private FakeConnection $connection;
 
     public function __construct(?FakeConnection $connection = null)
@@ -206,11 +284,25 @@ public function connection(?string $name = null): FakeConnection
     {
         return $this->connection;
     }
+
+    public function statement(string $query, array $bindings = []): bool
+    {
+        $this->statementCalls[] = [$query, $bindings];
+
+        return $this->connection()->statement($query, $bindings);
+    }
+
+    public function getConnection(): FakeConnection
+    {
+        return $this->connection;
+    }
 }
 
 final class FakeConnection
 {
     private FakeQueryGrammar $grammar;
+    /** @var list<array{0:string,1:array}> */
+    public array $statements = [];
 
     public function __construct(?FakeQueryGrammar $grammar = null)
     {
@@ -221,6 +313,13 @@ public function getQueryGrammar(): FakeQueryGrammar
     {
         return $this->grammar;
     }
+
+    public function statement(string $query, array $bindings = []): bool
+    {
+        $this->statements[] = [$query, $bindings];
+
+        return true;
+    }
 }
 
 final class FakeQueryGrammar