Simon Willison ha pubblicato un tool web che esegue le tue query SQL su un database SQLite nel browser e ti spiega, riga per riga, cosa sta facendo il motore sotto il cofano. Prende l’output di EXPLAIN QUERY PLAN e del bytecode di basso livello di EXPLAIN, e lo annota con descrizioni in inglese semplice.

Perché ti riguarda. Capire cosa fa il query planner è la differenza fra una query che risponde in 50 millisecondi e una che scansiona tutta la tabella. Finora le opzioni erano due: imparare a leggere l’output di EXPLAIN a occhio (difficile, pochi lo fanno davvero), oppure incollare la query in una chat con un LLM ogni volta (funziona, ma non costruisce comprensione duratura). Questo tool sta nel mezzo: ti mostra il piano reale con annotazioni, così impari vedendo, non chiedendo.

L’ha costruito con Claude Fable, lo stesso strumento con cui ha recentemente riscritto sqlite-utils, dopo aver letto un post di Julia Evans che diceva di voler imparare a leggere i query plan di SQLite.

Un limite dichiarato: Willison scrive lui stesso di non sapere abbastanza sui query plan di SQLite per verificare i risultati. Le spiegazioni vanno prese come aiuto per imparare, non come verità definitiva.

Se vuoi provarci, il tool è pubblico e non richiede installazione: apri la pagina, scrivi una query, leggi le annotazioni.

Nel dettaglio

SQLite, come ogni database, ha un query planner: quando gli dai una query, decide come eseguirla. Può usare un indice, fare una scansione completa della tabella, unire tabelle in un certo ordine. La stessa query scritta in due modi diversi può girare in millisecondi o in minuti, a seconda delle scelte del planner.

Il comando EXPLAIN QUERY PLAN ti fa vedere queste scelte. L’output è compatto: poche righe che dicono, per esempio, SEARCH TABLE orders USING INDEX idx_customer oppure SCAN TABLE orders. La differenza fra SEARCH e SCAN è enorme: la prima usa un indice e tocca poche righe, la seconda legge tutta la tabella.

C’è anche un livello più profondo, EXPLAIN, che mostra il bytecode che la macchina virtuale di SQLite esegue davvero: una sequenza di istruzioni come OpenRead, Column, Next, Close. È l’assembly di SQLite, e leggerlo richiede familiarità con l’architettura interna del database.

Il tool di Willison prende entrambi gli output e li annota. Per ogni riga di EXPLAIN QUERY PLAN aggiunge una frase che spiega cosa significa. Per ogni istruzione del bytecode dice cosa fa e perché è lì. Il risultato è una spiegazione leggibile di qualcosa che normalmente solo un DBA esperto saprebbe interpretare.

Tecnicamente, il tool gira interamente nel browser. SQLite è compilato in WebAssembly e Python gira tramite Pyodide, sempre in WebAssembly. Nessun server, nessuna API key, nessun dato che lascia il tuo computer.

Il pattern di costruzione è interessante quanto il risultato. Willison ha usato Claude Fable per farsi scrivere il tool dopo aver letto il post di Julia Evans. È lo stesso approccio del recente sqlite-utils 4.0: un’idea chiara, un agente che la realizza, un controllo umano alla fine. Il fatto che Willison ammetta di non poter verificare le spiegazioni è significativo: il tool è utile per esplorare, ma non è un oracolo.

Questo si collega a un tema che attraversa il discorso sull’AI che potenzia le persone. Il tool non sostituisce la tua comprensione di SQL: la accelera. Invece di leggere una documentazione astratta su cosa fa Next nel bytecode di SQLite, vedi l’istruzione applicata alla tua query, con una spiegazione contestualizzata. Impari dal caso reale, non dalla teoria.

Il limite, dichiarato onestamente, è che le annotazioni potrebbero contenere errori. Se stai ottimizzando una query in produzione, questo tool è un punto di partenza per capire cosa succede, non la risposta definitiva. Per quella serve ancora qualcuno che sa leggere un piano di esecuzione a mano e può confermare o smentire quello che il tool dice.