Cosa fa il formattatore
- Le clausole (SELECT, FROM, WHERE, GROUP BY, ORDER BY, SET, VALUES, RETURNING…) iniziano ciascuna una riga; il loro contenuto è indentato sotto, un elemento per riga per le liste.
- I join iniziano una riga al livello delle clausole; la condizione ON resta con il join e gli ulteriori termini AND/OR si indentano sotto di essa.
- Sottoquery e CTE aprono un blocco tra parentesi il cui contenuto è indentato di un livello; le liste brevi tra parentesi (
IN ('a', 'b'), argomenti di funzione, tuple) restano su una riga. - Le espressioni CASE mettono ogni WHEN e l’ELSE su righe proprie e allineano END con CASE.
- Le funzioni window tengono
OVER (PARTITION BY … ORDER BY …)su una riga quando ci sta. - CREATE TABLE scrive una definizione di colonna per riga; INSERT … VALUES scrive una tupla per riga.
- Le istruzioni sono separate da una riga vuota dopo ogni punto e virgola.
Cosa non tocca mai
Letterali stringa ('it''s', E'\n', $$ … $$), identificatori tra virgolette ("Nome", `nome`, [nome]), commenti (--, #, /* */) e parametri (?, $1, :nome, @var) vengono copiati byte per byte. Cambiano solo gli spazi e il caso delle keyword, quindi la query formattata è la stessa query. La riscrittura del caso si applica alle keyword SQL e alle funzioni standard (COUNT, COALESCE, NOW…), non ai tuoi identificatori: my_table resta my_table anche in modalità maiuscole.
Virgole finali o iniziali
Le virgole finali (a, alla fine di una riga) sono ciò che producono la maggior parte delle guide di stile e degli ORM. Le virgole iniziali (, b all’inizio) permettono di commentare qualsiasi riga di una lista di select tranne la prima senza rompere la query, ed è per questo che sono popolari nell’SQL analitico. Scegli quella che il tuo team legge più in fretta; il formattatore converte tra le due.
Minifica
Minifica compatta tutto su una riga con spazi singoli, trasformando i commenti di riga in commenti a blocco perché sopravvivano. Usala per righe di log, parametri URL, o per incollare una query in una chat senza che gli a capo vengano mangiati.
Dialetti
Il tokenizer capisce PostgreSQL (cast ::, parametri $1, dollar quoting, operatori JSON ->>, FILTER, RETURNING, ON CONFLICT), MySQL/MariaDB (identificatori con backtick, commenti #, STRAIGHT_JOIN, ON DUPLICATE KEY UPDATE, LIMIT x OFFSET y), SQLite e SQL Server (identificatori [tra parentesi quadre], @variabili, TOP, CROSS APPLY). Non valida l’SQL; una query con un errore di sintassi viene formattata al meglio perché tu possa comunque leggerla.
Formattare SQL altrove
# PostgreSQL: pg_format (pgFormatter, Perl) pg_format -s 2 -u 1 query.sql # qualsiasi dialetto: sqlfluff (Python), fa anche lint sqlfluff fix --dialect postgres query.sql # JavaScript: sql-formatter npx sql-formatter -l postgresql query.sql
Domande
Cambia ciò che fa la query?
No. Cambiano solo gli spazi e il caso delle keyword; letterali, identificatori, commenti e parametri vengono copiati invariati. La riscrittura del caso si applica a keyword e nomi di funzioni standard, che non distinguono maiuscole e minuscole in ogni dialetto SQL.
Perché una sottoquery è su più righe anche se è corta?
Qualsiasi gruppo tra parentesi che contiene una keyword di clausola (SELECT, FROM, WHERE…) viene scritto come blocco, perché è ciò che rende leggibili le query annidate. Argomenti di funzione, liste IN e tuple VALUES restano in linea quando sono corti.
Può formattare funzioni PL/pgSQL o stored procedure?
Il corpo di una funzione tra $$ … $$ è per il formattatore un letterale stringa e viene lasciato com’è. L’istruzione CREATE FUNCTION attorno viene formattata. La formattazione completa del linguaggio procedurale è fuori ambito.
Il mio SQL viene inviato a un server?
No. La pagina gira interamente nel tuo browser, che è il punto per query che contengono nomi di tabelle o letterali di produzione.
E l’output di EXPLAIN?
È un altro strumento: incolla il piano nel visualizzatore EXPLAIN, che disegna l’albero e segnala gli errori di stima.