Como formatar consultas SQL

SQL desorganizado e uma das maneiras mais rapidas de introduzir bugs. Quando uma consulta e uma unica linha longa sem indentacao, e dificil ver quais condicoes se aplicam a quais junces, onde subconsultas comecam e terminam, ou se a logica esta correta. Um formatador baseado em navegador lida com todo o trabalho localmente sem enviar suas consultas para um servidor.

Por que a formatacao importa

• Depuracao: uma consulta bem formatada torna os erros de logica visiveis. Voce pode rastrear o fluxo de SELECT a WHERE a JOIN sem adivinhar.
• Revisao de codigo: revisores podem ler SQL formatado em segundos. Uma consulta de uma unica linha os forca a analisa-la mentalmente primeiro.
• Manutencao: quando voce revisita uma consulta meses depois, a formatacao lhe diz o que ela faz num piscar de olhos.
• Colaboracao: formatacao consistente em uma equipe significa que todos leem SQL da mesma maneira.
• Integracao: novos membros da equipe podem ler SQL formatado sem precisar do historico oral de cada consulta.
• Documentacao: quando SQL aparece em documentos de design, runbooks ou wikis, consultas formatadas sao mais faceis de seguir para nao-desenvolvedores.
• Diferencas de controle de versao: SQL formatado produz diferencas mais limpas quando voce muda uma clausula sem reformatar toda a consulta.

Como formatar SQL

1. Cole seu SQL: insira uma consulta minificada ou desorganizada no formatador. Ele lida com SELECT, INSERT, UPDATE, DELETE, CREATE TABLE e consultas complexas com subconsultas e junces.
2. Configure as opcoes: escolha o tamanho da indentacao e se deve colocar palavras-chave em maiusculas. Essas configuracoes correspondem ao guia de estilo do seu projeto.
3. Copie o resultado: o SQL formatado esta pronto para colar de volta no seu editor, cliente de banco de dados ou documentacao.

Como e uma boa formatacao

Uma consulta como select u.name, o.total from users u join orders o on u.id = o.user_id where o.total > 100 and u.active = 1 order by o.total desc se torna:

SELECT
  u.name,
  o.total
FROM users u
JOIN orders o
  ON u.id = o.user_id
WHERE o.total > 100
  AND u.active = 1
ORDER BY o.total DESC

Cada clausula comeca em sua propria linha. As condicoes sao indentadas sob sua clausula pai. As junces e suas condicoes ON estao claramente emparelhadas.

Uma breve historia das convencoes de formatacao SQL

SQL foi criado pelos pesquisadores da IBM Donald Chamberlin e Raymond Boyce em 1974, originalmente chamado SEQUEL (Structured English Query Language). O «QL» no nome original refletia a intencao de que a linguagem se lesse como ingles. Desde o inicio, esse design legivel por humanos implicou uma convencao: indente suas clausulas para que se leiam de cima para baixo como frases.

Durante a maior parte dos anos 1980 e 1990, SQL era escrito a mao em editores de texto e a formatacao era pessoal. Algumas oficinas adotaram «estilo rio» (onde cada palavra-chave se alinha verticalmente a direita de uma coluna virtual), outros usaram «estilo egipcio» (chave-na-mesma-linha equivalente), e a maioria apenas usava o que o autor preferia.

O primeiro formatador SQL amplamente usado foi o Apex SQL Formatter (2000), seguido pelo SQL Complete da Devart (2002) e SQL Prompt da Red Gate (2003). Essas ferramentas trouxeram formatacao em nivel de IDE para desenvolvedores SQL Server e Oracle. Em 2010, todo IDE principal (SSMS, DataGrip, DBeaver) tinha formatacao SQL integrada, e formatadores online se tornaram padrao para limpeza ad hoc.

Em 2017, o ecossistema de formatadores mudou com o sql-formatter (npm), uma biblioteca JavaScript de codigo aberto que alimenta a maioria dos formatadores SQL baseados em navegador hoje, incluindo este. Formatadores modernos lidam com diferencas de dialeto (backticks do MySQL, funcoes de janela do PostgreSQL, colchetes do SQL Server) e produzem saida consistente e configuravel.

Guias de estilo SQL usados por grandes empresas

A maioria das bases de codigo profissionais segue um dos varios guias de estilo SQL publicados:

Se voce esta comecando um novo projeto, escolha um dos guias estabelecidos. Se voce esta entrando em uma base de codigo existente, siga o que ja esta la. Consistencia dentro de um projeto importa mais do que qualquer estilo especifico.

Escolhas comuns de formatacao

• Caso de palavras-chave: MAIUSCULAS (mais comum, torna as palavras-chave visualmente distintas), minusculas (estilo moderno dbt/Snowflake), ou caso original (alguns IDEs preservam o que voce digitou).
• Caso de identificadores: snake_case e o padrao em PostgreSQL e na maioria dos bancos de dados amigaveis ao Unix; PascalCase ou camelCase nas tradicoes Oracle/SQL Server.
• Indentacao: 2 espacos (compacto, cabe em terminal de 80 caracteres), 4 espacos (corresponde a maioria dos guias de estilo de codigo), ou tabulacoes (raro em SQL).
• Colocacao de virgulas: virgulas finais (apos cada coluna em linha separada) ou virgulas iniciais (virgula no inicio da proxima linha, mais facil para adicionar/remover colunas).
• Comprimento da linha: 80 caracteres (amigavel ao terminal), 120 caracteres (padrao IDE moderno), ou ilimitado (menos comum em producao).
• Estilo JOIN: palavra-chave ANSI JOIN (preferida) vs estilo antigo separado por virgulas FROM com condicoes de juncao WHERE (descontinuado).
• Formatacao de subconsultas: indente subconsultas dentro de parenteses, use Common Table Expressions (CTEs) para clareza, ou aninhe com aliases explicitos.

Diferencas de dialeto

Os formatadores SQL precisam lidar com sintaxe especifica do dialeto:

Um bom formatador detecta ou aceita uma dica de dialeto, depois lida com sintaxe que outros dialetos rejeitariam.

Armadilhas comuns

• Reformatacao dentro de scripts de producao: alterar espacos em branco em um script de migracao que ja foi parcialmente aplicado pode causar problemas se sua ferramenta de migracao usar impressao digital por hash. Formate antes da primeira execucao.
• Literais de string reformatados: uma string multilinha dentro de uma consulta nao deveria ser reformatada pelo formatador SQL; alguns formatadores ingenuos quebram strings inline.
• Comentarios perdidos ou mal posicionados: comentarios SQL (tracos de linha unica e barra-asterisco multilinha) precisam sobreviver a formatacao. Alguns formatadores os descartam ou os movem de maneiras confusas.
• Aspas de identificador alteradas: identificadores entre aspas duplas em PostgreSQL ou entre backticks em MySQL tem significados especificos. Um formatador que «normaliza» removendo aspas pode mudar o comportamento da consulta se o identificador precisava de aspas (palavra reservada, caso misto em PostgreSQL).
• Funcoes de janela mal formatadas: OVER (PARTITION BY x ORDER BY y) deve permanecer legivel. Quebra de linha agressiva dentro de parenteses de funcao de janela produz saida desorganizada.
• Cadeias CTE super-indentadas: WITH cte1 AS (...), cte2 AS (...) pode ser aninhado profundamente demais por alguns formatadores. A maioria dos formatadores modernos mantem CTEs no nivel superior.
• Strings entre dolares (funcoes PostgreSQL): corpos de funcao envolvidos em $$ nao deveriam ter seu conteudo reformatado. Alguns formatadores os mutilam.
• Palavras-chave especificas do fornecedor mal classificadas: um formatador que nao conhece QUALIFY (Snowflake) ou LATERAL (PostgreSQL) pode nao as capitalizar ou alinhar corretamente.
• Procedimentos armazenados com fluxo de controle: blocos BEGIN/END, IF/THEN/ELSE em T-SQL ou PL/SQL precisam de regras de indentacao diferentes de consultas puras.

Dicas

• Formate antes de fazer commit: passe seu SQL por um formatador antes de adiciona-lo ao controle de versao. Isso mantem as diferencas limpas e as revisoes focadas na logica, nao no estilo.
• Use casos de palavras-chave consistentes: escolha palavras-chave em maiusculas ou minusculas e mantenha-se com elas em todo o seu projeto. Misturar estilos torna as consultas mais dificeis de ler.
• Quebre consultas complexas: se uma consulta ainda for dificil de ler apos a formatacao, considere quebra-la em CTEs (Common Table Expressions) ou views. A formatacao nao pode corrigir logica fundamentalmente complexa.
• Verifique o realce de sintaxe: um bom formatador fornece realce codificado por cores que torna palavras-chave, strings e numeros visualmente distintos, o que ajuda a capturar erros de digitacao.
• Formate apenas o que voce muda: em uma base de codigo existente grande, reformatar tudo de uma vez produz uma diferenca enorme que obscurece as mudancas reais. Formate incrementalmente ao tocar nas consultas.
• Configure seu editor: VS Code (SQLTools, vscode-sql-formatter), DataGrip, DBeaver e pgAdmin todos tem formatadores integrados ou baseados em extensoes. Configure uma vez e esqueca.
• Cuidado com bancos de dados sensiveis a maiusculas: PostgreSQL e sensivel a maiusculas para identificadores entre aspas. Um formatador que altera o caso de identificadores entre aspas quebrara as consultas.
• Teste a consulta formatada: apos reformatar, execute a consulta para verificar que a saida nao mudou. A maioria dos formatadores e confiavel, mas um bug no formatador pode corromper uma consulta.
• Use CTEs em vez de subconsultas aninhadas: uma cadeia CTE e quase sempre mais facil de ler e depurar do que a subconsulta aninhada equivalente, mesmo apos a formatacao.

Privacidade e consultas confidenciais

O formatador SQL roda inteiramente no seu navegador. As consultas que voce cola, o processamento intermediario e a saida formatada ficam todos no seu dispositivo. Nada e enviado para um servidor, registrado ou compartilhado com ninguem.

Isso importa porque consultas SQL frequentemente contem informacoes extremamente sensiveis: nomes de tabelas que revelam a arquitetura do produto, nomes de colunas que expoem a logica de negocios e metricas, IDs de clientes reais em clausulas WHERE, endpoints de API internos em procedimentos armazenados, SSNs e numeros de cartao de credito em dados de teste, compensacao de funcionarios em consultas de RH, numeros financeiros em consultas analiticas, enderecos de e-mail de clientes em consultas de marketing. Formatadores SQL em nuvem registram cada consulta em seus logs de requisicao, as vezes os retem para «melhoria do servico», e estiveram envolvidos em violacoes reais onde consultas de producao coladas vazaram esquemas e dados sensiveis. Um formatador baseado em navegador tem exposicao zero: a consulta nunca sai da sua maquina.

A formatacao baseada em navegador tambem funciona offline depois que a pagina e carregada, util para formatar consultas em avioes, em ambientes seguros sem acesso a internet, ou em qualquer lugar onde voce nao pode ou nao deveria colar uma consulta de banco de dados em um servico de terceiros.