Formattatore SQL

Che cos'è un formattatore SQL

Un formattatore SQL riscrive spazi e maiuscole di una query perché se ne veda la struttura, senza cambiare quello che la query fa. Le parole chiave vanno a capo, le colonne di una SELECT si incolonnano, le condizioni annidate vengono rientrate alla profondità a cui stanno davvero. Cambia il testo, non il risultato.

È uno strumento di leggibilità, non di correttezza. Un formattatore impagina volentieri una query che restituisce le righe sbagliate, e impaginarla è spesso il modo in cui te ne accorgi: una condizione di JOIN nascosta in fondo a una riga di 400 caratteri diventa una clausola rientrata che si riesce a leggere.

Perché un formattatore e non un parser

Lo SQL non ha una sola grammatica. Il nucleo è standardizzato, e poi ogni database ci aggiunge il suo: Postgres ha gli array e gli operatori JSONB, MySQL i backtick, SQL Server le parentesi quadre e TOP, BigQuery funzioni di data proprie e una regola di quoting diversa. Un formattatore che analizza davvero deve scegliere un dialetto, e poi rovina tutti gli altri.

Per questo qui si lavora per parole chiave. Lo strumento sa quali parole aprono una clausola e dispone la query intorno a loro, e sa proteggere le parti in cui le parole chiave non sono parole chiave. Il risultato è indipendente dal dialetto: formatta una query Postgres, una MySQL e il corpo di una stored procedure senza che gli venga detto quale sia, al prezzo di non riformattare l’interno delle espressioni che non comprende. Per leggere una query arrivata su una riga sola, è lo scambio giusto.

Che cosa fa alla tua query

• Le clausole sulla propria riga SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT, la famiglia dei JOIN e ON. È la modifica che rende la query scorribile: la forma dell’istruzione si vede prima ancora di leggerne una parola.
• L’elenco delle colonne spezzato sulle virgole una colonna per riga, così aggiungerne o toglierne una è un diff di una riga invece che una riga cambiata da 300 caratteri.
• Sottoquery rientrate una query dentro parentesi sta un livello più in dentro, così l’annidamento si vede invece di doverlo dedurre.
• Parole chiave uniformate, identificatori intatti le maiuscole sulle parole chiave sono la convenzione comune e fanno risaltare la struttura rispetto ai nomi. I nomi di tabelle e colonne restano esattamente come li hai scritti, cosa che conta in qualunque database dove le maiuscole sono significative.
• Idempotenza formattare una query già formattata dà lo stesso risultato, quindi eseguirlo due volte è sicuro e un file formattato resta stabile nel controllo di versione.

Quello che di proposito non fa

Non valida. Una query con un errore nel nome di una colonna si formatta benissimo, perché solo il tuo database sa quali colonne esistono. Non ottimizza, non riscrive e non ti dice che una sottoquery andrebbe più veloce come join. E non esegue niente: non c’è una connessione, non ci sono credenziali e non c’è nessun posto in cui una query possa girare.

Lascia stare anche l’interno delle espressioni complesse. Un CASE lungo o una funzione finestra restano sulla loro riga invece di essere esplosi, perché spezzare correttamente un’espressione richiede la grammatica che questo strumento volutamente non ha, e una rottura sbagliata è peggio di nessuna rottura.

Formattare prima di una code review

La ragione pratica per formattare è il diff. Una query scritta su una riga lunga cambia come una riga lunga: chi recensisce vede che qualcosa è cambiato e deve leggere 300 caratteri per scoprire cosa. Formattata, la stessa modifica è una riga aggiunta e una tolta, e la review dura un secondo.

Questo è un argomento per formattare le query prima che entrino nel controllo di versione, non solo quando le si legge. Scegli una convenzione, parole chiave maiuscole, due spazi, una colonna per riga è quella diffusa, e applicala a tutto, così un diff non conterrà mai una riformattazione mescolata a una modifica. Se il tuo team usa un linter come sqlfluff nella CI, allinea qui le stesse impostazioni e i due andranno d’accordo.

Incollare una query che tocca dati veri

Una query non è testo neutro. Porta con sé nomi di tabelle, nomi di colonne e spesso valori letterali presi dalla produzione: un indirizzo email in una WHERE, un id interno, la forma di uno schema che non pubblicheresti. Incollarla in un sito che invia a un backend significa consegnare tutto questo.

Qui tutto avviene nella pagina. Non viene inviato niente, lo strumento funziona con la rete staccata e puoi verificarlo nella scheda di rete. Per un formattatore, uno strumento che si apre proprio quando si sta debuggando qualcosa di reale, non è un dettaglio.