laravel-query-autopsy maintained by marc14444
Description
Lightweight dev-only Laravel bridge capturing sanitized Eloquent and DB query traces into .query-autopsy/traces.jsonl for QueryAutopsy N+1 and EXPLAIN diagnostics.
Last update
2026/11/20 13:42
(dev-main)
License
Downloads
0
Tags
performance - sql - mysql - sqlite - postgresql - laravel - eloquent - explain - n-plus-one - query-autopsy
marc14444/laravel-query-autopsy
Lightweight --dev Laravel bridge that captures Eloquent & Query Builder queries into .query-autopsy/traces.jsonl so @query-autopsy/cli, @query-autopsy/mcp, and the QueryAutopsy VS Code / Open VSX extension can diagnose N+1 bursts and run EXPLAIN plans — without rewriting SQL parsing or diagnostic rules in PHP.
Installation (--dev only)
composer require --dev marc14444/laravel-query-autopsy
Laravel package auto-discovery registers QueryAutopsy\Laravel\QueryAutopsyServiceProvider automatically.
Optional config publish:
php artisan vendor:publish --tag=query-autopsy-config
Security & Zero-Production-Overhead Guarantees
- Zero impact in
APP_ENV=production: Unless explicitly unlocked,QueryAutopsyServiceProviderdoes not attachDB::listen()or register trace buffers when$app->environment('production'). - PII binding redaction by default: Query bindings are stripped (
bindings: []) and inline'...'string literals are replaced with'[REDACTED]'before writing.query-autopsy/traces.jsonl(QUERY_AUTOPSY_REDACT_BINDINGS=truedefault). - Safe log hygiene:
- Creates
.query-autopsy/.gitignore(*.jsonl/*.ndjson) automatically to prevent accidental trace commits. - Refuses to write through symlinks (
is_link()guard). - Auto-rotates
traces.jsonlbeyond5 MiB(QUERY_AUTOPSY_MAX_TRACE_BYTES) and caps per-request buffers.
- Creates
- Zero shell injection & secret leakage in Artisan:
php artisan query:autopsyinvokes@query-autopsy/cliwith raw argument arrays (proc_open(array $argv)— never shell concatenation) and passes any--uristrictly viaQUERY_AUTOPSY_URIenvironment variable rather than CLI arguments.
Usage
- Run your local app or PHPUnit / Pest feature tests (
APP_ENV=localorAPP_ENV=testing). Queries are automatically emitted to.query-autopsy/traces.jsonl. - Analyze N+1 bursts & slow queries from Laravel Artisan:
# Offline N+1 burst & latency report
php artisan query:autopsy trace
# Run read-only EXPLAIN on top offenders against your local PostgreSQL/MySQL/SQLite DB
php artisan query:autopsy trace --explain-top=3 --uri="postgresql://postgres:secret@127.0.0.1:5432/app_dev" --fail-on=warning
# Static PHP SQL safety & CI check across app/
php artisan query:autopsy check --dir=app --format=sarif
Or analyze the exact same .query-autopsy/traces.jsonl directly from AI coding agents via @query-autopsy/mcp (autopsy_analyze_traces).