Skip to content

Commit e0536c6

Browse files
authored
Feature/update readme.md (#6)
* gitflow-feature-stash: update-readme.md * Extends CI to develop and main branches Updates the CI workflow to trigger on push and pull request events for both the `develop` and `main` branches, ensuring comprehensive testing and validation for all relevant code changes.
1 parent 8bfb2d6 commit e0536c6

File tree

1 file changed

+17
-9
lines changed

1 file changed

+17
-9
lines changed

README.md

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,17 @@
11
# Laravel MySQL Deadlock Retry
22

3-
![CI](https://github.com/Ahed92Wakim/laravel-mysql-deadlock-retry/actions/workflows/ci.yml/badge.svg?event=pull_request)
4-
![PHP](https://img.shields.io/badge/php-8.2-blue)
5-
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
3+
[![Tests](https://github.com/Ahed92Wakim/laravel-mysql-deadlock-retry/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Ahed92Wakim/laravel-mysql-deadlock-retry/actions/workflows/ci.yml)
4+
[![Packagist Version](https://img.shields.io/packagist/v/ahed92wakim/laravel-mysql-deadlock-retry.svg)](https://packagist.org/packages/ahed92wakim/laravel-mysql-deadlock-retry)
5+
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
6+
[![Laravel](https://img.shields.io/badge/Laravel-%5E11-red.svg)](#)
7+
[![PHP](https://img.shields.io/badge/PHP-%5E8.2-blue.svg)](#)
8+
[![Code Style](https://img.shields.io/badge/style-PHP%20CS%20Fixer-informational.svg)](#)
9+
610

711
Resilient database transactions for Laravel applications that need to gracefully handle MySQL deadlocks and serialization failures. This helper wraps `DB::transaction()` with targeted retries, structured logging, and exponential backoff so you can keep your business logic simple while surviving transient contention.
812

913
## Highlights
14+
1015
- Retries only known transient failure scenarios (MySQL driver error `1213` and SQLSTATE `40001`), leaving all other exceptions untouched.
1116
- Exponential backoff with jitter between attempts to reduce stampedes under load.
1217
- Structured logs with request metadata, SQL, bindings, connection information, and stack traces written to dated files under `storage/logs/{Y-m-d}`.
@@ -45,18 +50,19 @@ $order = Retry::transactionWithRetry(
4550

4651
### Parameters
4752

48-
| Parameter | Default | Description |
49-
| --- | --- | --- |
50-
| `maxRetries` | `3` | Total number of attempts (initial try + retries). |
51-
| `retryDelay` | `2` | Base delay (seconds). Actual wait uses exponential backoff with ±25% jitter. |
52-
| `logFileName` | `database/mysql-deadlocks` | Written to `storage/logs/{Y-m-d}/{logFileName}.log`. Can point to subdirectories. |
53-
| `trxLabel` | `''` | Optional label injected into log titles and stored in the service container as `tx.label` for downstream consumers. |
53+
| Parameter | Default | Description |
54+
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
55+
| `maxRetries` | `3` | Total number of attempts (initial try + retries). |
56+
| `retryDelay` | `2` | Base delay (seconds). Actual wait uses exponential backoff with ±25% jitter. |
57+
| `logFileName` | `database/mysql-deadlocks` | Written to `storage/logs/{Y-m-d}/{logFileName}.log`. Can point to subdirectories. |
58+
| `trxLabel` | `''` | Optional label injected into log titles and stored in the service container as `tx.label` for downstream consumers. |
5459

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

5762
## Retry Conditions
5863

5964
Retries are attempted only when the caught exception is an `Illuminate\Database\QueryException` that matches one of:
65+
6066
- SQLSTATE `40001` (serialization failure).
6167
- MySQL driver error `1213` (deadlock), whether reported via SQLSTATE or the driver error code.
6268

@@ -67,10 +73,12 @@ If no attempt succeeds and all retries are exhausted, the last `QueryException`
6773
## Logging Behaviour
6874

6975
Logs are written using a dedicated single-file channel per day:
76+
7077
- Success after retries → a warning entry titled `"[trxLabel] [MYSQL DEADLOCK RETRY - SUCCESS] After (Attempts: x/y) - Warning"`.
7178
- Failure after exhausting retries → an error entry titled `"[trxLabel] [MYSQL DEADLOCK RETRY - FAILED] After (Attempts: x/y) - Error"`.
7279

7380
Each log entry includes:
81+
7482
- Attempt count, maximum retries, and transaction label.
7583
- Connection name, SQL, resolved raw SQL (when bindings are available), and PDO error info.
7684
- A compacted stack trace and sanitized bindings.

0 commit comments

Comments
 (0)