Weave Code
Laravel Query Detector Laravel Package
beyondcode/laravel-query-detector
Detect N+1 database queries in Laravel during development. Monitors queries in real time and alerts you when repeated queries indicate missing eager loading, helping you optimize performance and reduce unnecessary database calls.
Laravel N+1 Query Detector helps you spot and fix N+1 query issues during development by monitoring executed queries in real time. When repeated queries are detected, it alerts you so you can add eager loading and keep your application fast.
Install as a dev dependency and let it run quietly in the background while you build, surfacing performance problems early—before they hit production.
- Detects N+1 queries automatically as you browse your app
- Real-time notifications/alerts showing problematic queries
- Guides you toward adding eager loading for affected relations
- Lightweight, development-only workflow to prevent query bloat
Frequently asked questions about Laravel Query Detector
- How do I install BeyondCode’s Laravel Query Detector without affecting production?
- Install it as a dev dependency with `composer require beyondcode/laravel-query-detector --dev`. The package automatically disables in production when `APP_DEBUG=false`, ensuring zero runtime overhead. No manual configuration is needed for basic usage.
- Can this package detect N+1 queries in Laravel Lumen applications?
- Yes, the package explicitly supports Lumen. It integrates with Laravel’s query logging system, which Lumen also uses, so it works seamlessly in micro-frameworks without modifications.
- What output formats are available for N+1 query alerts?
- The package supports multiple outputs: console alerts, Laravel logs, Debugbar, Clockwork, JSON, and custom alert systems. You can configure a pipeline in `config/query-detector.php` to route alerts to your preferred channel, including third-party tools like Sentry or Datadog.
- How do I whitelist relations to avoid false positives for already optimized queries?
- Use the `except` configuration in `config/query-detector.php` to whitelist relations (e.g., `['User@posts']`). This prevents alerts for relations you’ve already eager-loaded or that are intentionally queried separately. Start with a conservative whitelist and refine it based on alerts.
- Does this package work with Laravel 11, or is it limited to older versions?
- The package supports Laravel 5.8 through 12.x, including Laravel 11. Check the [GitHub releases](https://github.com/beyondcode/laravel-query-detector/releases) for compatibility notes. If you’re using a newer version, monitor the package’s changelog for updates or open an issue for support.
- Will this package slow down my development environment significantly?
- The package adds minimal overhead (~1–5ms per request) during development due to query monitoring. Test it in staging with `APP_DEBUG=true` to validate performance. If needed, disable it entirely with `QUERY_DETECTOR_ENABLED=false` in your `.env` file.
- Can I integrate Query Detector alerts into my CI/CD pipeline to block N+1 queries?
- Yes, the package emits `QueryDetected` events that you can listen to in your CI/CD pipeline (e.g., GitHub Actions). Fail builds if queries exceed your threshold by adding a custom event listener or using the `Alert` output channel to trigger failures.
- How do I adjust the sensitivity of N+1 query detection?
- Set the `threshold` in `config/query-detector.php` (default: 1). Increase it (e.g., to 3) to reduce false positives for high-traffic endpoints. Lower values catch more N+1 issues but may generate noise. Balance sensitivity based on your application’s query patterns.
- Are there alternatives to this package for detecting N+1 queries in Laravel?
- Alternatives include Laravel Debugbar (for manual inspection), Clockwork (visual query profiling), and custom solutions using Eloquent’s query logging. However, this package is specialized for real-time N+1 detection with minimal setup, while alternatives often require manual analysis or lack automation.
- How do I test if the package is working correctly in my Laravel app?
- Trigger a known N+1 query (e.g., loop through models without eager loading) and check for alerts in your configured output (console, logs, or Debugbar). Run `php artisan query-detector:test` if available, or manually inspect queries using Tinker (`php artisan tinker` and simulate requests).
Weaver
How can I help you explore Laravel packages today?