Formatador SQL
Formate e embeleze consultas SQL. Cole SQL desordenado e obtenha uma saida limpa e indentada com destaque de sintaxe.
Principais recursos
- Conversão automática de palavras-chave para maiúsculas
- Indentação configurável
- Destaque de sintaxe
- Suporte a dialetos SQL comuns
Guide
Formatação SQL transforma consultas densas e ilegíveis em código estruturado e consistentemente indentado que é fácil de ler, revisar, depurar e manter. Uma consulta que funciona perfeitamente quando escrita como uma única linha torna-se um fardo de manutenção quando outra pessoa (ou você, três meses depois) precisa entender o que ela faz. Formatação SQL consistente não é cosmética. Ela reduz bugs, acelera a revisão de código e torna consultas complexas tratáveis. Este guia cobre convenções de formatação, estrutura de cláusulas, padrões comuns para diferentes tipos de consulta e como a formatação interage com otimização de consulta. A regra fundacional da formatação SQL é uma cláusula por linha. SELECT, FROM, WHERE, JOIN, ON, GROUP BY, HAVING, ORDER BY, LIMIT, INSERT INTO, VALUES, UPDATE, SET e DELETE FROM cada uma começam em sua própria linha no nível de indentação base. Essa estrutura torna a consulta escaneável. Você pode ver de relance quais colunas são selecionadas, quais tabelas estão envolvidas, quais condições filtram os dados e como os resultados são ordenados. Uma consulta formatada dessa forma lê-se como um documento estruturado em vez de uma frase interminável. A formatação da cláusula SELECT lista cada coluna em sua própria linha, indentada um nível a partir da palavra-chave SELECT. Vírgulas iniciais (vírgulas no início de cada linha em vez do final) são uma convenção popular porque facilitam comentar colunas individuais e produzem diffs mais limpos no controle de versão. Tanto vírgulas finais quanto iniciais são aceitáveis, desde que a escolha seja consistente em todo o código. Apelidos de coluna devem usar a palavra-chave AS explicitamente (nome_coluna AS apelido) em vez da abreviação (nome_coluna apelido) para clareza. Quando uma expressão de coluna é longa (uma declaração CASE ou uma chamada de função com múltiplos argumentos), coloque-a em sua própria linha e indente a continuação. Cláusulas FROM e JOIN beneficiam-se de alinhamento consistente. Cada JOIN recebe sua própria linha na mesma indentação que FROM. A condição ON é indentada abaixo de seu JOIN. Para consultas com muitos joins, essa estrutura visual torna os relacionamentos de tabela claros: 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 O tipo de join (INNER JOIN, LEFT JOIN, RIGHT JOIN, CROSS JOIN, FULL OUTER JOIN) carrega significado. Formatação que separa visualmente cada join ajuda os revisores a verificar se o tipo de join correto é usado para cada relacionamento. Um LEFT JOIN que deveria ser um INNER JOIN (ou vice-versa) é um bug comum que código formatado torna mais fácil de detectar. A formatação da cláusula WHERE coloca cada condição em sua própria linha com AND ou OR no início da linha. Indentar condições abaixo de WHERE torna a lógica de filtro visível: WHERE o.order_date >= '2026-01-01' AND o.status = 'completed' AND c.country = 'US' AND (p.category = 'electronics' OR p.category = 'appliances') Lógica booleana complexa com operadores AND e OR mistos é uma fonte comum de bugs. Formatação com parênteses explícitos e indentação clara mostra o agrupamento lógico. Sem formatação, WHERE a = 1 AND b = 2 OR c = 3 é ambíguo para leitores humanos (embora SQL avalie AND antes de OR, então significa (a = 1 AND b = 2) OR c = 3). Formatado com parênteses, a intenção torna-se clara. Sempre use parênteses com AND/OR misto para tornar a precedência explícita. Subconsultas devem ser indentadas um nível dentro de seus parênteses. Cada subconsulta é formatada usando as mesmas regras que uma consulta de nível superior. Subconsultas correlacionadas (aquelas que referenciam colunas da consulta externa) são particularmente importantes de formatar claramente porque seu relacionamento com a consulta externa determina seu comportamento: SELECT customer_name , total_spent FROM customers c WHERE total_spent > ( SELECT AVG(total_spent) FROM customers WHERE country = c.country ) A indentação mostra que a subconsulta está aninhada dentro da cláusula WHERE e referencia c.country da consulta externa. Para subconsultas profundamente aninhadas (três ou mais níveis), considere refatorar para CTEs, pois aninhamento profundo torna-se difícil de seguir independentemente da formatação. Common Table Expressions (CTEs) usando cláusulas WITH devem ser formatadas com cada CTE como um bloco nomeado separado: 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 CTEs são um dos recursos SQL mais poderosos para dividir consultas complexas em componentes legíveis e testáveis. Cada CTE pode ser testado independentemente executando apenas sua declaração SELECT. Formatação adequada torna o propósito de cada CTE visível e o fluxo de dados entre CTEs rastreável. Nomeie seus CTEs descritivamente: monthly_sales é melhor do que cte1. Cláusulas GROUP BY e ORDER BY seguem o mesmo padrão multilinha que SELECT quando referenciam múltiplas colunas. Liste cada coluna em sua própria linha indentada. Para GROUP BY, isso facilita verificar se todas as colunas SELECT não agregadas estão incluídas (um requisito em SQL padrão e imposto pelo PostgreSQL, embora MySQL seja permissivo por padrão). Para ORDER BY, listar cada coluna de ordenação com sua direção (ASC ou DESC) em uma linha separada esclarece a prioridade de ordenação. Declarar ASC explicitamente (mesmo sendo o padrão) melhora a legibilidade. A formatação da cláusula HAVING segue as mesmas regras que WHERE. HAVING filtra grupos após agregação, e suas condições devem ser formatadas com uma condição por linha. Um erro comum de formatação é colocar condições HAVING na cláusula WHERE ou vice-versa. WHERE filtra linhas antes do agrupamento. HAVING filtra grupos após agregação. A colocação correta é essencial tanto para correção quanto para desempenho, e formatação clara facilita a verificação. Expressões CASE são construções multilinha que devem ser formatadas para mostrar cada par 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 Expressões CASE aninhadas (CASE dentro de CASE) devem ser evitadas quando possível porque tornam-se ilegíveis independentemente da formatação. Refatore para CTEs, colunas computadas ou uma tabela de lookup adicionada à consulta em vez disso. Declarações INSERT têm dois formatos comuns. Para inserções de linha única com colunas nomeadas, liste cada par coluna-valor de forma legível: INSERT INTO customers ( customer_name , email , country , created_at ) VALUES ( 'John Doe' , 'john@example.com' , 'US' , CURRENT_TIMESTAMP ) Alinhar as entradas VALUES com seus nomes de coluna correspondentes facilita verificar se cada valor corresponde à coluna correta. Para declarações INSERT...SELECT, formate a porção SELECT usando regras padrão de formatação SELECT. Declarações UPDATE beneficiam-se de formatar cada atribuição SET em sua própria linha: UPDATE customers SET email = 'newemail@example.com' , updated_at = CURRENT_TIMESTAMP , status = 'verified' WHERE customer_id = 12345 Essa estrutura deixa claro quais colunas estão sendo modificadas e impede a omissão acidental da cláusula WHERE, que atualizaria cada linha da tabela. A cláusula WHERE em declarações UPDATE e DELETE é a cláusula mais crítica de acertar. Formatação que coloca WHERE em sua própria linha no mesmo nível que UPDATE ou DELETE torna sua presença (ou ausência) óbvia. Declarações DELETE devem sempre ter sua cláusula WHERE claramente visível: DELETE FROM order_items WHERE order_id = 12345 AND item_status = 'cancelled' Um DELETE sem WHERE remove todas as linhas da tabela. Código formatado torna a presença ou ausência de WHERE imediatamente visível. Algumas equipes adotam uma convenção de sempre escrever consultas DELETE primeiro como consultas SELECT (substituindo DELETE FROM por SELECT * FROM) para verificar quais linhas serão afetadas, depois convertendo de volta para DELETE. Funções de janela estão entre as construções SQL mais complexas de formatar. A cláusula OVER com PARTITION BY e ORDER BY deve estar em suas próprias linhas indentadas quando longas: 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 Para especificações de janela curtas, mantê-las em uma linha é aceitável: ROW_NUMBER() OVER (ORDER BY id) AS row_num. O objetivo é legibilidade no comprimento e complexidade da expressão real. Definições de janela nomeadas (WINDOW w AS (PARTITION BY customer_id ORDER BY order_date)) seguidas por OVER w reduzem repetição quando múltiplas colunas usam a mesma especificação de janela. Capitalização de palavras-chave é uma escolha de estilo com opiniões fortes em ambos os lados. Palavras-chave MAIÚSCULAS (SELECT, FROM, WHERE) distinguem visualmente sintaxe SQL de nomes de tabela e coluna. Palavras-chave minúsculas misturam-se, mas são mais fáceis de digitar. A coisa mais importante é consistência. Escolha uma convenção e imponha-a em toda a equipe. Muitas organizações usam maiúsculas para palavras-chave e minúsculas para identificadores. Alguns guias de estilo modernos preferem tudo minúsculo, argumentando que o destaque de sintaxe em editores já distingue palavras-chave de identificadores. Uma terceira abordagem capitaliza apenas as principais palavras-chave de cláusula (SELECT, FROM, WHERE) e deixa nomes de função e palavras-chave menores em minúsculas. Apelidos de tabela devem ser significativos. Usar apelidos de letra única (a, b, c) economiza digitação, mas torna consultas mais difíceis de ler, especialmente com muitos joins. Abreviações curtas derivadas do nome da tabela são melhores: customers AS c, orders AS o, order_items AS oi. Em consultas complexas com muitas tabelas, apelidos mais longos melhoram a clareza: customers AS cust, order_items AS items. Sempre use a palavra-chave AS para apelidos para distingui-los de erros de digitação ou vírgulas esquecidas. Nunca use palavras reservadas como apelidos. A largura de indentação deve ser consistente. Dois espaços e quatro espaços são ambas escolhas comuns. Tabs versus espaços é uma preferência, mas espaços produzem alinhamento mais consistente entre editores e ferramentas. A ferramenta formatadora SQL permite que você configure a largura de indentação para corresponder ao padrão da sua equipe. Qualquer largura que você escolher, use-a uniformemente para todos os níveis de indentação: corpo de cláusula, aninhamento de subconsulta, corpos de expressão CASE e definições de CTE. Formatação de comentário em SQL usa -- para comentários de linha única e /* */ para comentários multilinha. Coloque comentários acima da cláusula ou expressão que eles descrevem, não inline no final de uma linha longa onde podem ser perdidos. Para lógica de negócios complexa em cláusulas WHERE, um comentário explicando por que uma condição existe é valioso: -- Excluir contas de teste criadas pela equipe de QA antes da condição de filtro. Comentários que reafirmam o SQL (-- Join customers table) adicionam ruído sem valor. Bons comentários explicam intenção, não mecânica. Formatação e desempenho de consulta não estão diretamente relacionados. O motor do banco de dados analisa e otimiza a consulta independentemente de espaços em branco e quebras de linha. No entanto, consultas bem formatadas são mais fáceis de otimizar porque você pode ver a estrutura claramente. Uma consulta mal formatada com um problema de desempenho esconde o problema em um muro de texto. A mesma consulta, devidamente formatada, revela a subconsulta problemática, condição de join ausente, DISTINCT desnecessário ou cláusula WHERE não sargable de relance. Formatação é uma ferramenta de depuração e otimização. Controle de versão e formatação SQL interagem de maneiras importantes. Reformatar uma consulta inteira em um único commit produz um diff que toca cada linha, tornando impossível ver o que realmente mudou. Ao adotar um formatador para um código existente, faça a formatação em um commit dedicado com uma mensagem clara como "Apply SQL formatting standard". Mudanças subsequentes então produzem diffs limpos e significativos. Vírgulas iniciais são populares em parte porque adicionar uma nova coluna a um SELECT produz um diff de uma linha (a nova linha), enquanto vírgulas finais exigem modificar a linha anterior para adicionar uma vírgula, criando um diff de duas linhas. Diferenças de dialeto afetam escolhas de formatação. PostgreSQL, MySQL, SQL Server, Oracle, SQLite e BigQuery cada um têm variações de sintaxe. PostgreSQL usa casting de dois pontos (value::type) e strings com cifrão. MySQL usa aspas inversas para identificadores e LIMIT com OFFSET. SQL Server usa aspas de colchete, TOP em vez de LIMIT e CROSS APPLY em vez de LATERAL JOIN. Oracle usa ROWNUM, CONNECT BY para consultas hierárquicas e funções de data diferentes. BigQuery usa aspas inversas para nomes de tabela qualificados por projeto. Um formatador deve lidar com o dialeto que sua equipe usa. A ferramenta formatadora SQL suporta sintaxe SQL padrão que é compatível com todos os principais dialetos. Adoção em equipe de padrões de formatação SQL exige uma configuração compartilhada e idealmente imposição automatizada. Inclua regras de formatação SQL no seu guia de estilo de código. Use hooks pre-commit ou verificações de CI para verificar formatação em arquivos SQL. Defina o padrão em um arquivo de configuração de ferramenta (como .sql-formatter.json) que é commitado no repositório. O custo inicial de concordar com um padrão é pago de volta através de cada revisão de código que não inclui mais picuinhas de formatação e cada sessão de depuração que começa com código legível em vez de um exercício de reformatação. SQL em código de aplicativo (embutido em Python, JavaScript, Java ou outras linguagens) apresenta desafios adicionais de formatação. Uma string SQL bruta dentro de uma função Python ou um template literal JavaScript está sujeita tanto às regras de formatação da linguagem hospedeira quanto às regras de formatação SQL. Literais de string multilinha (três aspas em Python, crases em JavaScript) permitem que você mantenha formatação SQL dentro do código de aplicativo. Separe a string SQL da lógica do aplicativo: atribua a consulta a uma constante nomeada (const FIND_ACTIVE_USERS = ...) e referencie-a onde necessário. Para grandes coleções de consultas, mova SQL para arquivos .sql separados e carregue-os em tempo de execução. SQL gerado por ORM costuma precisa de formatação para depuração. Quando sua consulta Django, SQLAlchemy, ActiveRecord ou Prisma produz resultados inesperados, visualizar o SQL gerado ajuda a diagnosticar o problema. A maioria das ORMs fornece uma maneira de produzir o SQL bruto (query.toString() em Knex, str(query) em SQLAlchemy, .explain() em Django). Cole o SQL gerado em um formatador para entender sua estrutura. SQL gerado por ORM é tipicamente denso e difícil de ler porque nunca foi feito para humanos. Saída formatada torna os joins, condições e subconsultas visíveis. Procedimentos armazenados e funções exigem disciplina de formatação além de consultas individuais. Cada procedimento contém múltiplas declarações SQL, declarações de variáveis, fluxo de controle (IF/ELSE, WHILE, FOR) e manipulação de exceções (TRY/CATCH, BEGIN/EXCEPTION). Formate cada declaração SQL dentro do procedimento usando as regras padrão de formatação de consulta. Indente corpos de fluxo de controle um nível de suas palavras-chave. Coloque BEGIN e END em suas próprias linhas. Adicione linhas em branco entre seções lógicas dentro do procedimento. Procedimentos armazenados bem formatados são dramaticamente mais fáceis de depurar do que densos e não formatados. Arquivos de migração beneficiam-se de formatação SQL porque são revisados em pull requests e representam mudanças permanentes de esquema de banco de dados. Uma declaração CREATE TABLE com definições de coluna formatadas é fácil de revisar para tipos de dados corretos, restrições, nulidade e padrões. Um ALTER TABLE com múltiplas declarações ADD COLUMN deve listar cada coluna em sua própria linha. Formatação torna a revisão de migração mais rápida e reduz a chance de enviar uma migração com tipos de coluna incorretos ou restrições ausentes. Consultas de análise de desempenho (EXPLAIN, EXPLAIN ANALYZE) produzem saída que é mais fácil de correlacionar com a consulta quando a própria consulta está formatada. Se você cola uma consulta de uma linha no EXPLAIN ANALYZE, a saída referencia operações em componentes específicos da consulta que são difíceis de localizar na string de uma linha. A mesma consulta, devidamente formatada, permite que você corresponda cada linha do plano de execução à cláusula correspondente na consulta. Essa correlação é essencial para identificar qual join ou subconsulta está causando problemas de desempenho. Geração de SQL dinâmico em código de aplicativo deve produzir saída formatada. Ao construir consultas programaticamente (construindo strings SQL com base em entrada do usuário ou configuração), adicione novas linhas e indentação à consulta gerada. Isso não custa nada em tempo de execução, mas torna registro e depuração dramaticamente mais fáceis. Quando uma consulta gerada causa um erro ou tem desempenho ruim, você pode ler o SQL formatado no log e entender imediatamente a estrutura. Concatenar tudo em uma linha economiza alguns caracteres, mas cria dores de cabeça de depuração. Checklists de revisão de código SQL beneficiam-se de padrões de formatação. Um revisor verificando SQL formatado pode verificar sistematicamente: tipos de join corretos para cada relacionamento de tabela, condições de cláusula WHERE que correspondem ao requisito de negócios, GROUP BY incluindo todas as colunas não agregadas, ORDER BY refletindo a ordenação esperada, uso apropriado de LEFT JOIN versus INNER JOIN (um LEFT JOIN onde INNER bastaria indica um bug ou cautela desnecessária) e ausência de antipadrões comuns como SELECT * em código de produção, cross joins implícitos e subconsultas correlacionadas que poderiam ser reescritas como joins. Formatar grandes consultas legadas é um dos usos mais valiosos de um formatador SQL. Bancos de dados empresariais acumulam consultas ao longo de anos ou décadas. Consultas escritas por desenvolvedores que já deixaram a empresa há muito tempo, modificadas múltiplas vezes e nunca reformatadas tornam-se muros de texto que ninguém ousa tocar. Executar essas consultas através de um formatador é o primeiro passo para torná-las manteníveis. Formate a consulta, commit a mudança de formatação separadamente, depois comece o trabalho de modificação real com um ponto de partida legível. A ferramenta formatadora SQL recebe qualquer consulta SQL válida, analisa sua estrutura e produz SQL consistentemente formatado seguindo regras configuráveis para indentação, maiúsculas e minúsculas de palavras-chave e colocação de cláusulas. Cole sua consulta, clique em formatar e copie o resultado. Use-a para formatar consultas antes de commit, limpar SQL legado para revisão, padronizar consultas recebidas de colegas ou geradas por ferramentas ORM e preparar SQL para documentação ou apresentações.
Perguntas frequentes
Quais dialetos SQL são suportados?
O formatador suporta sintaxe SQL padrão, incluindo SELECT, JOIN, WHERE, GROUP BY e outras cláusulas comuns.
Ele altera a lógica da minha consulta?
Não, o formatador altera apenas espaços em branco e maiúsculas/minúsculas. A lógica da sua consulta permanece exatamente a mesma.
