Formattatore SQL
Formatta e abbellisci query SQL. Incolla SQL disordinato e ottieni un output pulito e indentato con evidenziazione della sintassi.
Funzionalita principali
- Maiuscolizzazione automatica delle parole chiave
- Indentazione configurabile
- Evidenziazione della sintassi
- Supporto per i comuni dialetti SQL
Guide
La formattazione SQL trasforma query dense e illeggibili in codice strutturato, con rientro coerente, facile da leggere, revisionare, eseguire il debug e mantenere. Una query che funziona perfettamente quando scritta come singola riga diventa un onere di manutenzione quando qualcun altro (o tu, tre mesi dopo) deve capire cosa fa. Una formattazione SQL coerente non e cosmetica. Riduce i bug, accelera la revisione del codice e rende gestibili le query complesse. Questa guida tratta le convenzioni di formattazione, la struttura delle clausole, i pattern comuni per diversi tipi di query e come la formattazione interagisce con l'ottimizzazione delle query. La regola fondamentale della formattazione SQL e una clausola per riga. SELECT, FROM, WHERE, JOIN, ON, GROUP BY, HAVING, ORDER BY, LIMIT, INSERT INTO, VALUES, UPDATE, SET e DELETE FROM iniziano ciascuna sulla propria riga al livello di rientro base. Questa struttura rende la query scansionabile. Puoi vedere a colpo d'occhio quali colonne sono selezionate, quali tabelle sono coinvolte, quali condizioni filtrano i dati e come sono ordinati i risultati. Una query formattata in questo modo si legge come un documento strutturato anziche come un'unica frase interminabile. La formattazione della clausola SELECT elenca ciascuna colonna sulla propria riga, rientrata di un livello rispetto alla parola chiave SELECT. Le virgole iniziali (virgole all'inizio di ogni riga anziche alla fine) sono una convenzione popolare perche rendono facile commentare le singole colonne e producono diff piu puliti nel controllo di versione. Sia le virgole finali sia quelle iniziali sono accettabili purché la scelta sia coerente in tutto il codebase. Gli alias di colonna dovrebbero usare esplicitamente la parola chiave AS (nome_colonna AS alias) anziche la scorciatoia (nome_colonna alias) per chiarezza. Quando un'espressione di colonna e lunga (un'istruzione CASE o una chiamata di funzione con argomenti multipli), posizionala sulla propria riga e rientra la continuazione. Le clausole FROM e JOIN beneficiano di un allineamento coerente. Ciascun JOIN ottiene la propria riga allo stesso livello di rientro di FROM. La condizione ON e rientrata sotto il suo JOIN. Per le query con molti join, questa struttura visiva rende chiare le relazioni tra tabelle: FROM orders o JOIN customers c ON c.customer_id = o.customer_id JOIN products p ON p.product_id = o.product_id LEFT JOIN shipping s ON s.order_id = o.order_id Il tipo di join (INNER JOIN, LEFT JOIN, RIGHT JOIN, CROSS JOIN, FULL OUTER JOIN) porta un significato. Una formattazione che separa visivamente ciascun join aiuta i revisori a verificare che il tipo di join corretto sia usato per ciascuna relazione. Un LEFT JOIN che dovrebbe essere un INNER JOIN (o viceversa) e un bug comune che il codice formattato rende piu facile da individuare. La formattazione della clausola WHERE posiziona ciascuna condizione sulla propria riga con AND o OR all'inizio della riga. Il rientro delle condizioni sotto WHERE rende visibile la logica di filtro: WHERE o.order_date >= '2026-01-01' AND o.status = 'completed' AND c.country = 'US' AND (p.category = 'electronics' OR p.category = 'appliances') La logica booleana complessa con operatori AND e OR misti e una fonte comune di bug. La formattazione con parentesi esplicite e rientro chiaro mostra il raggruppamento logico. Senza formattazione, WHERE a = 1 AND b = 2 OR c = 3 e ambigua per i lettori umani (sebbene SQL valuti AND prima di OR, quindi significa (a = 1 AND b = 2) OR c = 3). Formattata con parentesi, l'intento diventa chiaro. Usa sempre le parentesi con AND/OR misti per rendere esplicita la precedenza. Le subquery dovrebbero essere rientrate di un livello all'interno delle loro parentesi. Ciascuna subquery e formattata usando le stesse regole di una query di livello superiore. Le subquery correlate (quelle che fanno riferimento a colonne dalla query esterna) sono particolarmente importanti da formattare chiaramente perche la loro relazione con la query esterna determina il loro comportamento: SELECT customer_name , total_spent FROM customers c WHERE total_spent > ( SELECT AVG(total_spent) FROM customers WHERE country = c.country ) Il rientro mostra che la subquery e nidificata all'interno della clausola WHERE e fa riferimento a c.country dalla query esterna. Per le subquery profondamente nidificate (tre o piu livelli), valuta il refactoring in CTE, poiche la nidificazione profonda diventa difficile da seguire indipendentemente dalla formattazione. Le Common Table Expressions (CTE) che usano le clausole WITH dovrebbero essere formattate con ciascuna CTE come blocco denominato separato: WITH monthly_sales AS ( SELECT DATE_TRUNC('month', order_date) AS month , SUM(amount) AS total FROM orders GROUP BY DATE_TRUNC('month', order_date) ), monthly_avg AS ( SELECT AVG(total) AS avg_total FROM monthly_sales ) SELECT m.month , m.total , a.avg_total FROM monthly_sales m CROSS JOIN monthly_avg a WHERE m.total > a.avg_total Le CTE sono una delle funzionalita SQL piu potenti per suddividere query complesse in componenti leggibili e testabili. Ciascuna CTE puo essere testata indipendentemente eseguendo solo la sua istruzione SELECT. Una formattazione corretta rende visibile lo scopo di ciascuna CTE e tracciabile il flusso di dati tra le CTE. Dai alle tue CTE nomi descrittivi: monthly_sales e meglio di cte1. Le clausole GROUP BY e ORDER BY seguono lo stesso pattern multiriga di SELECT quando fanno riferimento a piu colonne. Elenca ciascuna colonna sulla propria riga rientrata. Per GROUP BY, cio rende facile verificare che tutte le colonne SELECT non aggregate siano incluse (un requisito nello standard SQL e applicato da PostgreSQL, sebbene MySQL sia permissivo per impostazione predefinita). Per ORDER BY, elencare ciascuna colonna di ordinamento con la sua direzione (ASC o DESC) su una riga separata chiarisce la priorita di ordinamento. Dichiarare esplicitamente ASC (anche se e il valore predefinito) migliora la leggibilita. La formattazione della clausola HAVING segue le stesse regole di WHERE. HAVING filtra i gruppi dopo l'aggregazione e le sue condizioni dovrebbero essere formattate con una condizione per riga. Un errore di formattazione comune e posizionare le condizioni HAVING nella clausola WHERE o viceversa. WHERE filtra le righe prima del raggruppamento. HAVING filtra i gruppi dopo l'aggregazione. Il posizionamento corretto e essenziale sia per la correttezza sia per le prestazioni e una formattazione chiara rende facile verificarlo. Le espressioni CASE sono costrutti multiriga che dovrebbero essere formattate per mostrare ciascuna coppia WHEN/THEN: SELECT order_id , CASE WHEN status = 'shipped' THEN 'In Transit' WHEN status = 'delivered' THEN 'Complete' WHEN status = 'returned' THEN 'Returned' ELSE 'Processing' END AS status_label FROM orders Le espressioni CASE nidificate (CASE dentro CASE) dovrebbero essere evitate quando possibile perche diventano illeggibili indipendentemente dalla formattazione. Effettua invece il refactoring in CTE, colonne calcolate o una tabella di lookup inserita nella query con un join. Le istruzioni INSERT hanno due formati comuni. Per gli insert a riga singola con colonne denominate, elenca ciascuna coppia colonna-valore in modo leggibile: INSERT INTO customers ( customer_name , email , country , created_at ) VALUES ( 'John Doe' , 'john@example.com' , 'US' , CURRENT_TIMESTAMP ) Allineare le voci di VALUES con i nomi delle colonne corrispondenti rende facile verificare che ciascun valore corrisponda alla colonna corretta. Per le istruzioni INSERT...SELECT, formatta la parte SELECT usando le regole di formattazione standard di SELECT. Le istruzioni UPDATE beneficiano della formattazione di ciascun assegnamento SET sulla propria riga: UPDATE customers SET email = 'newemail@example.com' , updated_at = CURRENT_TIMESTAMP , status = 'verified' WHERE customer_id = 12345 Questa struttura rende chiaro quali colonne vengono modificate e previene l'omissione accidentale della clausola WHERE, che aggiornerebbe ogni riga della tabella. La clausola WHERE nelle istruzioni UPDATE e DELETE e la clausola piu critica da impostare correttamente. Una formattazione che posiziona WHERE sulla propria riga allo stesso livello di UPDATE o DELETE rende evidente la sua presenza (o assenza). Le istruzioni DELETE dovrebbero sempre avere la loro clausola WHERE chiaramente visibile: DELETE FROM order_items WHERE order_id = 12345 AND item_status = 'cancelled' Un DELETE senza WHERE rimuove tutte le righe dalla tabella. Il codice formattato rende immediatamente visibile la presenza o l'assenza di WHERE. Alcuni team adottano una convenzione di scrivere sempre prima le query DELETE come query SELECT (sostituendo DELETE FROM con SELECT * FROM) per verificare quali righe saranno interessate, per poi riconvertirle in DELETE. Le funzioni finestra sono tra i costrutti SQL piu complessi da formattare. La clausola OVER con PARTITION BY e ORDER BY dovrebbe essere sulle proprie righe rientrate quando sono lunghe: SELECT customer_id , order_date , amount , SUM(amount) OVER ( PARTITION BY customer_id ORDER BY order_date ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW ) AS running_total FROM orders Per specifiche finestra brevi, tenerle su una sola riga e accettabile: ROW_NUMBER() OVER (ORDER BY id) AS row_num. L'obiettivo e la leggibilita in base alla lunghezza e alla complessita dell'espressione effettiva. Le definizioni di finestra denominate (WINDOW w AS (PARTITION BY customer_id ORDER BY order_date)) seguite da OVER w riducono la ripetizione quando piu colonne usano la stessa specifica di finestra. La capitalizzazione delle parole chiave e una scelta di stile con forti opinioni da entrambe le parti. Le parole chiave in MAIUSCOLO (SELECT, FROM, WHERE) distinguono visivamente la sintassi SQL dai nomi di tabelle e colonne. Le parole chiave in minuscolo si fondono ma sono piu facili da digitare. La cosa piu importante e la coerenza. Scegli una convenzione e applicala in tutto il team. Molte organizzazioni usano il maiuscolo per le parole chiave e il minuscolo per gli identificatori. Alcune guide di stile moderne preferiscono tutto in minuscolo, sostenendo che l'evidenziazione della sintassi negli editor distingue gia le parole chiave dagli identificatori. Un terzo approccio capitalizza solo le parole chiave principali (SELECT, FROM, WHERE) e lascia in minuscolo i nomi delle funzioni e le parole chiave secondarie. Gli alias di tabella dovrebbero essere significativi. L'uso di alias a singola lettera (a, b, c) fa risparmiare digitazione ma rende le query piu difficili da leggere, specialmente con molti join. Le brevi abbreviazioni derivate dal nome della tabella sono migliori: customers AS c, orders AS o, order_items AS oi. Nelle query complesse con molte tabelle, alias piu lunghi migliorano la chiarezza: customers AS cust, order_items AS items. Usa sempre la parola chiave AS per gli alias per distinguerli da errori di battitura o virgole dimenticate. Non usare mai parole riservate come alias. La larghezza del rientro dovrebbe essere coerente. Due spazi e quattro spazi sono entrambe scelte comuni. Tabulazioni contro spazi e una preferenza, ma gli spazi producono un allineamento piu coerente tra editor e strumenti. Lo strumento di formattazione SQL ti consente di configurare la larghezza del rientro per corrispondere allo standard del tuo team. Qualsiasi larghezza scegli, usala uniformemente per tutti i livelli di rientro: corpo della clausola, nidificazione delle subquery, corpi delle espressioni CASE e definizioni delle CTE. La formattazione dei commenti in SQL usa -- per i commenti su riga singola e /* */ per i commenti multiriga. Posiziona i commenti sopra la clausola o l'espressione che descrivono, non in linea alla fine di una riga lunga dove potrebbero passare inosservati. Per la logica di business complessa nelle clausole WHERE, un commento che spiega perche esiste una condizione e prezioso: -- Esclude gli account di test creati dal team QA prima della condizione di filtro. I commenti che riprendono il SQL (-- Join customers table) aggiungono rumore senza valore. I buoni commenti spiegano l'intento, non i meccanismi. La formattazione e le prestazioni delle query non sono direttamente correlate. Il motore del database analizza e ottimizza la query indipendentemente dagli spazi bianchi e dalle interruzioni di riga. Tuttavia, le query ben formattate sono piu facili da ottimizzare perche puoi vedere la struttura chiaramente. Una query formattata male con un problema di prestazioni nasconde il problema in un muro di testo. La stessa query, formattata correttamente, rivela la subquery problematica, la condizione di join mancante, il DISTINCT non necessario o la clausola WHERE non sargable a colpo d'occhio. La formattazione e uno strumento di debug e ottimizzazione. Il controllo di versione e la formattazione SQL interagiscono in modi importanti. Riformattare un'intera query in un singolo commit produce un diff che tocca ogni riga, rendendo impossibile vedere cosa e realmente cambiato. Quando adotti un formattatore per un codebase esistente, fai la formattazione in un commit dedicato con un messaggio chiaro come "Applica lo standard di formattazione SQL". Le modifiche successive producono quindi diff puliti e significativi. Le virgole iniziali sono popolate in parte perche aggiungere una nuova colonna a SELECT produce un diff di una riga (la nuova riga), mentre le virgole finali richiedono la modifica della riga precedente per aggiungere una virgola, creando un diff di due righe. Le differenze di dialetto influenzano le scelte di formattazione. PostgreSQL, MySQL, SQL Server, Oracle, SQLite e BigQuery hanno ciascuno variazioni di sintassi. PostgreSQL usa il casting con due punti (value::type) e le stringhe con quoting in dollari. MySQL usa il quoting con backtick per gli identificatori e LIMIT con OFFSET. SQL Server usa il quoting con parentesi quadre, TOP invece di LIMIT e CROSS APPLY invece di LATERAL JOIN. Oracle usa ROWNUM, CONNECT BY per le query gerarchiche e funzioni di data diverse. BigQuery usa il quoting con backtick per i nomi di tabella qualificati da progetto. Un formattatore dovrebbe gestire il dialetto usato dal tuo team. Lo strumento di formattazione SQL supporta la sintassi SQL standard compatibile con tutti i principali dialetti. L'adozione da parte del team di standard di formattazione SQL richiede una configurazione condivisa e idealmente un'applicazione automatizzata. Includi le regole di formattazione SQL nella tua guida di stile del codice. Usa pre-commit hook o controlli CI per verificare la formattazione sui file SQL. Definisci lo standard in un file di configurazione dello strumento (come .sql-formatter.json) che viene sottoposto a commit nel repository. Il costo iniziale di accordarsi su uno standard e ripagato attraverso ogni revisione del codice che non include piu pignolerie sulla formattazione e ogni sessione di debug che inizia con codice leggibile anziche con un esercizio di riformattazione. Il SQL nel codice dell'applicazione (incorporato in Python, JavaScript, Java o altri linguaggi) pone ulteriori sfide di formattazione. Una stringa SQL grezza all'interno di una funzione Python o di un template literal JavaScript e soggetta sia alle regole di formattazione del linguaggio host sia alle regole di formattazione SQL. I letterali stringa multiriga (triple-quote di Python, backtick di JavaScript) ti consentono di mantenere la formattazione SQL all'interno del codice dell'applicazione. Separa la stringa SQL dalla logica dell'applicazione: assegna la query a una costante denominata (const FIND_ACTIVE_USERS = ...) e referenziala dove necessario. Per grandi raccolte di query, sposta il SQL in file .sql separati e caricali a runtime. Il SQL generato dagli ORM spesso ha bisogno di formattazione per il debug. Quando la tua query Django, SQLAlchemy, ActiveRecord o Prisma produce risultati imprevisti, visualizzare il SQL generato aiuta a diagnosticare il problema. La maggior parte degli ORM fornisce un modo per restituire il SQL grezzo (query.toString() in Knex, str(query) in SQLAlchemy, .explain() in Django). Incolla il SQL generato in un formattatore per comprenderne la struttura. Il SQL generato dagli ORM e tipicamente denso e difficile da leggere perche non era destinato agli esseri umani. L'output formattato rende visibili join, condizioni e subquery. Le stored procedure e le funzioni richiedono disciplina di formattazione oltre le singole query. Ciascuna procedura contiene piu istruzioni SQL, dichiarazioni di variabili, flusso di controllo (IF/ELSE, WHILE, FOR) e gestione delle eccezioni (TRY/CATCH, BEGIN/EXCEPTION). Formatta ciascuna istruzione SQL all'interno della procedura usando le regole standard di formattazione delle query. Rientra i corpi del flusso di controllo di un livello rispetto alle loro parole chiave. Posiziona BEGIN e END sulle proprie righe. Aggiungi righe vuote tra le sezioni logiche all'interno della procedura. Le stored procedure ben formattate sono drammaticamente piu facili da sottoporre a debug di quelle dense e non formattate. I file di migrazione beneficiano della formattazione SQL perche vengono revisionati nelle pull request e rappresentano modifiche permanenti allo schema del database. Un'istruzione CREATE TABLE con definizioni di colonna formattate e facile da revisionare per i tipi di dati corretti, i vincoli, la nullabilita e i valori predefiniti. Un ALTER TABLE con piu istruzioni ADD COLUMN dovrebbe elencare ciascuna colonna sulla propria riga. La formattazione rende la revisione delle migrazioni piu veloce e riduce la possibilita di spedire una migrazione con tipi di colonna errati o vincoli mancanti. Le query di analisi delle prestazioni (EXPLAIN, EXPLAIN ANALYZE) producono output piu facile da correlare alla query quando la query stessa e formattata. Se incolli una query su una riga in EXPLAIN ANALYZE, l'output fa riferimento a operazioni su componenti specifici della query che sono difficili da individuare nella stringa su una riga. La stessa query, formattata correttamente, ti consente di abbinare ciascuna riga del piano di esecuzione alla clausola corrispondente nella query. Questa correlazione e essenziale per identificare quale join o subquery sta causando problemi di prestazioni. La generazione di SQL dinamico nel codice dell'applicazione dovrebbe produrre output formattato. Quando costruisci query a livello di codice (costruendo stringhe SQL in base all'input dell'utente o alla configurazione), aggiungi nuove righe e rientri alla query generata. Questo non costa nulla a runtime ma rende drammaticamente piu facile la registrazione e il debug. Quando una query generata causa un errore o ha prestazioni scadenti, puoi leggere il SQL formattato nel log e comprendere immediatamente la struttura. Concatenare tutto su una riga risparmia alcuni caratteri ma crea mal di testa per il debug. Le checklist di revisione del codice SQL beneficiano degli standard di formattazione. Un revisore che controlla SQL formattato puo verificare sistematicamente: tipi di join corretti per ciascuna relazione tra tabelle, condizioni della clausola WHERE che corrispondono al requisito di business, GROUP BY che include tutte le colonne non aggregate, ORDER BY che riflette l'ordinamento previsto, uso appropriato di LEFT JOIN rispetto a INNER JOIN (un LEFT JOIN dove basterebbe un INNER indica un bug o un'eccessiva cautela) e assenza di anti-pattern comuni come SELECT * nel codice di produzione, cross join impliciti e subquery correlate che potrebbero essere riscritte come join. La formattazione di grandi query legacy e uno degli usi piu preziosi di un formattatore SQL. I database aziendali accumulano query nel corso di anni o decenni. Query scritte da sviluppatori che hanno lasciato l'azienda da tempo, modificate piu volte e mai riformattate diventano muri di testo che nessuno osa toccare. Eseguire queste query attraverso un formattatore e il primo passo per renderle gestibili. Formatta la query, sottoponi a commit la modifica di formattazione separatamente, quindi inizia il lavoro di modifica effettivo con un punto di partenza leggibile. Lo strumento di formattazione SQL prende qualsiasi query SQL valida, ne analizza la struttura e restituisce SQL formattato in modo coerente seguendo regole configurabili per rientro, maiuscole/minuscole delle parole chiave e posizionamento delle clausole. Incolla la tua query, fai clic su formatta e copia il risultato. Usalo per formattare le query prima del commit, pulire il SQL legacy per la revisione, standardizzare le query ricevute dai colleghi o generate dagli strumenti ORM e preparare SQL per documentazione o presentazioni.
Domande frequenti
Quali dialetti SQL sono supportati?
Il formattatore supporta la sintassi SQL standard inclusi SELECT, JOIN, WHERE, GROUP BY e altre clausole comuni.
Modifica la logica della mia query?
No, il formattatore cambia solo spazi bianchi e maiuscole. La logica della tua resta esattamente la stessa.
