Monitoraggio PostgreSQL e Schema Linting per Laravel con Vacuum

Vacuum è un pacchetto di monitoraggio PostgreSQL per Laravel realizzato da Rati Rukhadze. Legge le statistiche che PostgreSQL conserva già in viste come pg_stat_user_tables, pg_stat_activity e pg_stat_statements, per poi elencare i problemi individuati insieme all'istruzione SQL in grado di risolverli.

Ecco le principali funzionalità offerte da questo pacchetto:

• 13 regole di advisor: wraparound, bloat, dead tuples, indici inutilizzati, statement lenti e altro ancora
• Health score: un punteggio su 100, calcolato in base ai risultati
• Supporto Blade e Filament: una dashboard su /vacuum, oppure un plugin per Filament 4 o 5
• Un comando vacuum:check: fa fallire una build in presenza di problemi critici
• Un comando vacuum:lint: segnala in CI problemi di schema come chiavi esterne senza indice
• History: trend e previsioni a partire da snapshot pianificati
• Lessons: 13 spiegazioni su PostgreSQL che utilizzano le tue stesse tabelle
• E molto altro...

La Dashboard e le Regole dell'Advisor

Ogni risultato ha una severità e un grado, che insieme determinano un health score su 100:

Puoi approfondire le regole nel readme del pacchetto. Il pacchetto mette a disposizione anche un endpoint /learn che ti spiega perché nel tuo database esistono determinati problemi, usando le tue stesse tabelle come esempi pratici, come nel caso delle N+1 queries.

Le stesse regole sono eseguibili anche da terminale:

php artisan vacuum:check
php artisan vacuum:check --fail-on=warning   # critical, warning, info, or never
php artisan vacuum:check --format=json       # score, grade, deductions, findings

Usando un job schedulato su staging, puoi sfruttare i comandi qui sopra per far fallire l'esecuzione quando il freeze age di una tabella supera la soglia critica. Ogni regola legge i propri limiti da config/vacuum.php, tra cui dead_tuple_ratio (0.20) e slow_query_milliseconds (500).

Installazione

Vacuum 1.2.0 richiede PostgreSQL 14 e Laravel 11+. L'estensione pg_stat_statements è opzionale. Senza di essa, la dashboard ti segnala che l'estensione non è presente.

composer require heyosseus/vacuum
php artisan vacuum:install

La dashboard si apre solo nell'ambiente local. Per accedervi in altri ambienti, puoi scrivere una callback usando il metodo Vacuum::auth():

use Heyosseus\Vacuum\Vacuum;

Vacuum::auth(fn (Request $request) => $request->user()?->isAdmin() === true);

Puoi saperne di più su questo pacchetto, consultare le istruzioni di installazione complete e vedere il codice sorgente su GitHub.