README

Production query health monitoring for Laravel. Catch slow queries, N+1 bugs, and missing indexes — with AI-powered fix suggestions and ready-to-run migrations.

Features

• Slow Query Detection — track queries exceeding your threshold (default 500ms)
• N+1 Detection — spot repeated query patterns within a single request
• Missing Index Detection — identify unindexed columns in slow queries
• AI-Powered Analysis — diagnosis and migration code via Claude or OpenAI (optional, BYO key)
• Zero Production Overhead — configurable sampling, ignore lists, buffered processing
• Privacy First — only normalized SQL templates leave your server, never values

Installation

composer require queryguard/laravel
php artisan migrate

Publish config (optional):

php artisan vendor:publish --provider="QueryGuard\QueryGuardServiceProvider" --tag="config"

Configuration

// config/queryguard.php
return [
    'enabled'               => env('QUERYGUARD_ENABLED', true),
    'sample_rate'           => env('QUERYGUARD_SAMPLE_RATE', 1.0),
    'slow_threshold_ms'     => 500,
    'n_plus_one_threshold'  => 10,
    'ignore' => [
        'tables' => ['telescope_*', 'pulse_*', 'jobs', 'sessions', 'cache'],
        'paths'  => ['horizon*', 'telescope*'],
    ],
    'storage' => [
        'retention_days' => 14,
    ],
    'explain' => [
        'enabled'        => true,
        'on_demand_only' => true,
    ],
    'ai' => [
        'provider' => env('QUERYGUARD_AI', null),  // 'anthropic' | 'openai' | null
        'api_key'  => env('QUERYGUARD_AI_KEY'),
        'model'    => env('QUERYGUARD_AI_MODEL', 'claude-sonnet-4-6'),
    ],
];

Usage

Report all issues

php artisan queryguard:report
php artisan queryguard:report --type=slow
php artisan queryguard:report --type=n_plus_one
php artisan queryguard:report --type=missing_index

AI analysis of a specific query

php artisan queryguard:analyze ab12cd34ef56

Requires QUERYGUARD_AI_KEY in .env. Returns diagnosis, root cause, suggested migration and Eloquent pattern.

Generate and apply a fix

php artisan queryguard:fix ab12cd34ef56

Generates a migration file. You review and run it yourself — QueryGuard never auto-applies migrations.

Signal a deploy (Cloud, Phase 3)

php artisan queryguard:deploy --sha=abc123 --branch=main

How It Works

Fingerprinting

Every SQL query is normalized into a template — all literals replaced with ?, IN lists collapsed:

Raw:      SELECT * FROM orders WHERE user_id = 42 AND status IN (1, 2, 3)
Template: SELECT * FROM orders WHERE user_id = ? AND status IN (?)
Hash:     ab12cd34ef56...

Identical templates across requests share one fingerprint, enabling accurate aggregation and N+1 detection.

Privacy guarantee

The Fingerprinter strips all literals before any data is persisted or transmitted. A CI test asserts this invariant — it fails if any raw number or string value leaks into a template.

Detectors

Requirements

• PHP 8.2+
• Laravel 10, 11, or 12
• MySQL 5.7+ or PostgreSQL 12+ or SQLite (testing)

Testing

composer test

Roadmap

• v0.1 — Slow / N+1 / missing index detection, AI fix suggestions, migration generator
• v0.2 — Cloud transport (batched metrics ingestion)
• Cloud — Deploy-linked regression detection, Filament dashboard, Stripe billing

License

MIT