Difflock: Lint delle Migrazioni Laravel e Diff dello Schema

Difflock è un pacchetto Laravel di Rati Rukhadze per esaminare le migrazioni rispetto al database che andranno a modificare. Legge il sorgente delle migrazioni senza caricarlo né eseguirlo, poi usa lo schema live e i metadati sulle dimensioni delle tabelle per segnalare le modifiche che meritano un'attenzione maggiore prima del deploy.

Ecco cosa include Difflock:

• Linting delle migrazioni per operazioni distruttive, modifiche alle colonne, indici, chiavi esterne e nomi di colonne sensibili
• Baseline dello schema registrate in JSON, che ti permettono di confrontare un database con uno snapshot committato o con un'altra connessione
• Una guardia per le migrazioni che esegue i controlli prima di passare il controllo al comando migrate di Laravel
• Controlli in CI con exit code per migrazioni rischiose, schema drift e errori di configurazione
• Strumenti MCP per verificare una tabella, un file di migrazione o il sorgente di una migrazione presente nel contesto di un agente

Esaminare le Migrazioni in Sospeso

difflock:lint analizza per impostazione predefinita le migrazioni in sospeso. Una migrazione come questa può sembrare del tutto ordinaria in una pull request:

Schema::table('orders', function (Blueprint $table) {
$table->string('channel');
$table->foreignId('customer_id')->constrained()->cascadeOnDelete();
$table->string('card_number', 32)->nullable();
$table->index('status');
});

Schema::table('customers', function (Blueprint $table) {
$table->dropColumn('legacy_token');
$table->renameColumn('name', 'full_name');
});

Su un database popolato, Difflock può segnalare la colonna channel non nullable, la dropColumn() distruttiva e la rinomina. Segnala inoltre che cascadeOnDelete() elimina le righe figlie all'interno del database, bypassando gli eventi del model, gli observer e i soft delete.

Il pacchetto dispone di regole per le modifiche che i controlli statici su un database di test vuoto non riescono a intercettare. change-column confronta una chiamata ->change() con la definizione live della colonna. unindexed-foreign-key verifica se il motore del database aggiunge l'indice necessario a una chiave esterna. redundant-index segnala il caso certo di prefisso iniziale, ad esempio l'aggiunta di un indice su (status) quando (status, created_at) esiste già.

Usa -v per espandere i risultati oppure --rule= per concentrarti su una singola regola:

php artisan difflock:lint
php artisan difflock:lint -v
php artisan difflock:lint --rule=drop-column

Quando un'applicazione non ha migrazioni in sospeso, il comando analizza invece tutti i file di migrazione anziché produrre un report vuoto. I progetti esistenti possono accettare il proprio backlog attuale con php artisan difflock:lint --all --accept, e poi usare il file database/difflock/accepted.json risultante come baseline per le nuove segnalazioni.

Registrare lo Schema Drift

Difflock registra uno schema osservato anziché ricostruire uno schema atteso a partire dai file di migrazione. In questo modo evita di dover interpretare migrazioni che contengono condizionali, cicli o SQL raw.

php artisan difflock:diff --save

Questo comando scrive database/difflock/schema.json, che puoi committare. In seguito, php artisan difflock:diff confronta la connessione corrente con quel file. Puoi anche confrontare due connessioni configurate:

php artisan difflock:diff --from=staging --to=production

La baseline contiene la struttura dello schema, incluse tabelle, colonne, indici, default e chiavi esterne. Non include le righe delle tabelle né le credenziali. snapshot.defaults, snapshot.comments e ignore.tables ti permettono di limitare ciò che viene registrato. Per un altro modo di intercettare i problemi del database in PostgreSQL, vedi il linting dello schema di Vacuum.

CI e Protezione delle Migrazioni

Installare Difflock non modifica php artisan migrate. Il pacchetto protegge le migrazioni solo quando usi il suo comando dedicato:

php artisan difflock:migrate

Analizza prima le migrazioni in sospeso. Quando le segnalazioni raggiungono il livello di blocco configurato, si ferma prima che Laravel scriva sul database. --allow-risky bypassa deliberatamente la guardia di Difflock, mentre --force di Laravel resta il flag separato per la conferma in produzione.

Per la CI, esegui insieme il controllo dello drift e il lint delle migrazioni:

- run: php artisan difflock:check --ci

Il comando termina con 0 quando il controllo passa, con 1 in caso di drift o di segnalazioni alla soglia configurata, e con 2 quando il controllo non può essere eseguito. Può comunque analizzare le regole basate solo sul sorgente anche senza una connessione al database, ma segnala che i dati delle tabelle non erano disponibili.

Supporto MCP

php artisan difflock:mcp avvia un server MCP standalone su stdio. I suoi quattro strumenti forniscono contesto sulle tabelle, linting delle migrazioni, controlli dello schema drift e documentazione delle regole.

Lo strumento per le migrazioni accetta sia un percorso di file sia il testo del sorgente. Un agente di coding AI può verificare una migrazione prima di scrivere il file, usando lo schema attuale del database e le statistiche delle tabelle. Il pacchetto include anche difflock:explain, che crea un briefing in Markdown per una migrazione senza chiamare un modello linguistico né alcuna API esterna.

Installazione

Difflock 1.0.0 richiede PHP 8.3 e supporta Laravel 12 e 13. Funziona con MySQL, MariaDB, PostgreSQL e SQLite.

composer require heyosseus/difflock --dev
php artisan vendor:publish --tag=difflock-config
php artisan difflock:doctor

difflock:doctor riporta la connessione, le tabelle disponibili, le migrazioni in sospeso, le regole registrate e se il ruolo del database configurato può scrivere. Un ruolo di sola lettura è una scelta sensata quando vuoi che Difflock ispezioni una connessione di produzione.

Difflock è disponibile su GitHub.