Download the PHP package bensedev/laravel-inflight-query-lock without Composer

Laravel Inflight Query Lock

Deduplicate concurrent identical queries using distributed locks and async execution. When multiple requests trigger the same slow query simultaneously, only one executes while others wait for the cached result.

Origin Story

This package was born out of necessity during numerous migration projects where we encountered heavy database queries that couldn't be easily optimized through traditional means like pagination or query simplification. Time and resource constraints forced creative solutions, and this approach proved effective in production environments. Rather than keeping this solution to ourselves, we're sharing it with the community in hopes it helps others facing similar challenges.

The Problem

Imagine 100 concurrent requests all hitting an analytics dashboard that runs the same expensive query:

Result: 100 identical queries hammer your database, causing:

• High database load
• Slow response times
• Potential timeouts
• Resource exhaustion

The Solution

With Inflight Query Lock:

Result:

• 1st request acquires lock and dispatches async job
• Job executes query and caches result
• Remaining 99 requests wait and receive the same cached result
• Only 1 database query executed

Features

• 🔒 Distributed locking - Prevents duplicate query execution across multiple servers
• ⚡ Async execution - Query runs in background job, freeing up web workers
• 🎯 Automatic deduplication - Identical queries are coalesced using unique hashes
• 💾 Redis-backed - Uses Redis for both caching and locking
• 🔄 Eloquent & Query Builder - Works with both Eloquent models and raw queries
• 📊 Optional logging - Track cache hits, misses, and query execution

Requirements

• PHP 8.4+
• Laravel 12.0+
• Redis (for distributed locking and caching)

Installation

Install via Composer:

Publish the configuration file:

Configuration

Configure in config/inflight-query-lock.php:

Environment Variables

Add to your .env:

Usage

With Eloquent Models

Add the trait to your model:

Use the inflight() method in queries:

Use Cases

1. Analytics Dashboards

2. Report Generation

3. Public API Endpoints

4. Admin Panels

How It Works

1. Query Hash Generation: Creates unique hash from SQL + bindings + connection
2. Cache Check: Looks for existing cached result
3. Lock Acquisition: Attempts to acquire distributed lock
4. Async Execution: If lock acquired, dispatches job to execute query
5. Polling: Requests poll cache until result is available
6. Result Distribution: All requests receive the same cached result

Sequence Diagram

Best Practices

1. Choose Appropriate TTL

2. Use Dedicated Queue

3. Enable Logging During Development

Monitor logs for:

• Cache hits/misses
• Lock acquisition
• Query execution timing

4. Monitor Queue Workers

Ensure queue workers are running:

Use Horizon for monitoring:

Performance Considerations

When to Use

✅ Good candidates:

• Slow queries (> 500ms)
• High concurrency endpoints
• Analytics/reporting queries
• Public APIs with traffic spikes

❌ Avoid for:

• Simple queries (< 100ms)
• Real-time data requirements
• Low-traffic endpoints
• Write operations

Overhead

• Overhead per request: ~1-2ms (cache check + lock attempt)
• First request: Query execution time + job dispatch (~10-50ms)
• Subsequent requests: Poll interval × iterations (~100ms average)

Testing

Run PHPStan:

Format code:

Troubleshooting

Queries not being cached

1. Check Redis connection
2. Verify queue workers are running
3. Enable logging to debug
4. Check cache_store configuration

Timeout errors

Increase lock timeout:

High poll overhead

Adjust poll interval:

Changelog

Please see CHANGELOG for recent changes.

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

Security

If you discover any security issues, please report them via the GitHub issue tracker with the "security" label.

Credits

• bensedev
• All Contributors

License

The MIT License (MIT). Please see License File for more information.