O SQL é padronizado desde 1987 e é mantido como ISO/IEC 9075, embora cada mecanismo adicione seu próprio dialeto no topo - é exatamente por isso que um formatador precisa analisar em vez de combinar padrões.
A pior consulta que eu já tive que revisar foi de 340 linhas em um único pensamento lógico: um relatório de receita para um Laravel SaaS, escrito como um DB::select() Raw String, construído ao longo de oito meses por três desenvolvedores, cada um com uma ideia diferente sobre capitalização e nenhuma sobre quebras de linha. Em algum lugar naquela parede de texto, um LEFT JOIN se tornou silenciosamente um INNER JOIN durante um refator, e os clientes com zero pedidos desapareceram do relatório O bug era uma palavra Encontrar levou um dia e meio - não porque a lógica era difícil, mas porque a consulta era ilegível, e o código ilegível esconde seus bugs à vista de todos.
Aqui está o que acontece com o SQL: O banco de dados não se importa com sua formatação. O analisador lê select id,name from users where active=1 e SELECT id, name FROM users WHERE active = 1 como a mesma instrução, produz o mesmo plano de execução, retorna as mesmas linhas ao mesmo tempo Formatar SQL é puramente para humanos - e é exatamente por isso que vale a pena fazer it' s, porque os humanos são os que o revisam, depuram em 2 AM, e herdam três trabalhos depois Uma consulta que você pode' t skim é uma consulta que você pode' t verificar.
um formatador sql transforma qualquer consulta - colada a partir de um log, uma saída de depuração ORM' s, uma mensagem Slack do colega de trabalho' s, um procedimento armazenado legado - em SQL consistentemente recuado, consistentemente encapsulado e revisável em um clique O do Toolz.dev é executado inteiramente em seu navegador, o que importa mais para SQL do que para quase qualquer outro texto que você' d colar em uma ferramenta on-line, porque as consultas de produção carregam seu esquema e, às vezes, seus dados.
Este guia aborda como usá-lo, as convenções de formatação que realmente importam (caixa de palavras-chave, recuo e a guerra da vírgula eterna) e os fluxos de trabalho em que um formatador se paga diariamente.
tl;dr: Cole qualquer consulta no Formatador SQL Toolz.dev e volte consistentemente recuado, SQL com caixa de palavras-chave - instantâneo, gratuito, lado do cliente, sem inscrição A formatação nunca altera o que uma consulta faz ou a rapidez com que é executada; muda se um ser humano pode verificá-la Convenções que valem a pena adotar: palavras-chave maiúsculas, uma cláusula por linha, recuo sob cada cláusula, e escolha um estilo de vírgula e pare de discutir sobre isso Emparelhe com o formatador json Para a camada de API acima do seu banco de dados e o ferramenta diff de texto Para comparar duas versões de uma consulta.
Principais características
Recuo consistente com um clique
O movimento central do formatador's: cada cláusula principal - SELECT, FROM, WHERE, GROUP BY, ORDER BY - inicia a sua própria linha, com colunas, condições e junções recuadas por baixo Esta é a janela do & quot; river" estrutura leitores SQL experientes digitalizam por: o olho percorre as palavras - chave da cláusula de leitura da borda esquerda, depois mergulha na cláusula que importa Uma consulta formatada de 60 linhas com revisões claras da estrutura mais rápido do que uma de 6 linhas não formatada, porque a estrutura está fazendo metade da leitura para você Minha história de terror de 340 linhas teria sido uma revisão de vinte minutos com essa forma - o tipo de junção alterado teria ficado sozinho em sua própria linha, visivelmente errado.
Normalização de casos de palavras-chave
SELECT contra select genuinamente não & #39; importa para qualquer banco de dados - as palavras-chave SQL são insensíveis a maiúsculas e minúsculas de acordo com o padrão, e cada dialeto honra isso. É muito importante para uma base de código, porque o invólucro misto é o ruído visual que faz com que consultas estruturalmente idênticas pareçam diferentes. Palavras-chave maiúsculas são a convenção mais antiga, datando de editores sem destaque de sintaxe, onde SELECT em maiúsculas foi o destaque. Eu ainda escrevo letras maiúsculas - palavras-chave pop contra identificadores minúsculos, e ele sobrevive a todos os contextos que retiram o destaque: logs, diffs, e-mail de texto simples, saída de terminal O formatador normaliza para sua convenção escolhida para que uma base de código escrita por cinco pessoas leia como se tivesse sido escrita por um.
Lida com ORM e saída de log
As consultas mais necessitadas de formatação são aquelas que não são humanos escreveu: saída de registro eloqüente e ativo, junções geradas pela doutrina, os monstros de linha única em seu log de consulta lenta. A saída ORM chega como uma linha com aliases gerados por máquina (t0, t1, laravel_reserved_0), e lê-lo cru é como você tem dores de cabeça Meu único uso mais frequente do formatador: pegue a consulta de Laravel' s log de consulta ou Telescópio, formatá-lo, e realmente ver o que o ORM decidiu fazer - que é o primeiro passo de cada & quot; por que é este endpoint slow" investigação, pouco antes EXPLAIN.
tolerância multi-dialeto
O SQL do mundo real é uma família de dialetos: identificadores citados pelo MySQL, aspas duplas do PostgreSQL e :: Casts, colchetes quadrados do SQL Server e TOP, SQLite tudo descontraído. Um formatador útil lida com todos eles sem exigir que você declare um dialeto primeiro, preservando a sintaxe específica do dialeto em vez de "correr" de TI. O padrão ANSI/ISO SQL (ISO/IEC 9075) define o núcleo comum, mas ninguém escreve SQL padrão puro na prática, e um formatador que fala apenas o padrão se engancharia no primeiro backtick.
Conserva a semântica, garantida
Vale a pena declarar explicitamente porque é o medo que impede as pessoas: a formatação não pode alterar os resultados. O espaço em branco e o caso das palavras-chave não são semânticos no SQL - a única ressalva histórica é isso literais de string São comparados com maiúsculas e minúsculas ou não dependendo do seu agrupamento, e um formatador nunca toca o interior de suas strings citadas. A saída é a mesma instrução, byte-for-byte onde os bytes são importantes. Execute EXPLAIN Em ambas as versões, se você quiser ver: planos idênticos.
Lado do cliente, o que realmente importa aqui
SQL é a categoria de texto mais sensível que é rotineiramente colada em ferramentas online As consultas revelam que seu esquema - nomes de tabelas, nomes de colunas, relacionamentos - e as consultas copiadas de logs geralmente contêm valores literais: e-mails em WHERE Cláusulas, intervalos de ID, ocasionalmente algo que nunca deveria estar em uma string de consulta. o Formatador Toolz.dev processa tudo no seu navegador; nada é transmitido Para SQL especificamente, I & #39; d chamar processamento do lado do cliente um requisito, não um recurso - verificá-lo na guia Rede e, em seguida, relaxar.
Como usar o Formatador SQL
Etapa 1: capturar a consulta
Copie o SQL de sua origem: seu arquivo de migração, um procedimento armazenado, a saída de depuração do ORM (DB::listen() ou telescópio em Laravel, ActiveRecord::Base.logger em Rails), o log de consulta lenta ou a guia de consulta da ferramenta APM. Se vier de um log, pode ter escapado de aspas ou espaços reservados para parâmetros (?, $1) - isso e #39; tudo bem, os formatadores lidam com espaços reservados e vê-los claramente costuma ser o objetivo.
Passo 2: Colar e formatar
abra o formatador sql, colar, e a versão formatada aparece Nenhuma cerimônia de dialeto, nenhuma configuração necessária para obter um bom padrão Se sua consulta incluir várias instruções separadas por ponto e vírgula, elas se formatam como instruções separadas - úteis para ler scripts de migração inteiros.
Passo 3: leia como um revisor
Agora faça a coisa que a formatação existe para: escaneie a aresta esquerda. Quais tabelas são unidas e com quais tipos de junção? faz o WHERE cláusula tem as condições que você espera - e são as AND/OR Agrupamentos entre parênteses da maneira que você pensar eles se agrupam? (precedência do operador em sql puts AND antes ORe as misturas não parentetizadas dos dois são a segunda maior fonte de bugs que vejo em análise, logo após os tipos de junção incorretas.) O SQL formatado torna os dois erros visíveis em segundos.
Passo 4: Copie-o de volta - Seletivamente
Para consultas com base em sua base de código, copie a versão formatada na migração, o ->select() expressão crua, o .sql arquivo. Para depuração única, não se preocupe em fazer uma viagem de volta; a cópia formatada serviu ao seu propósito no momento em que você a lê. um lugar não Para colar SQL formatado: de volta aos sistemas que armazenam consultas como strings de configuração, onde as ferramentas de diff de alguém agora mostram uma parede de mudanças de espaço em branco. Formato para leitura sempre; reformate as consultas armazenadas somente quando você estiver preparado para possuir o diff.
Etapa 5: Padronize a convenção da equipe
O maior valor do formatador' é composto: escolha as convenções que você pode automatizar - caso de palavra-chave e largura de recuo são os dois que este formatador controla diretamente - formate tudo de novo no caminho para a base de código, e o atrito de revisão SQL cai permanentemente Escreva a escolha em seu guia contribuinte A convenção específica escolhida importa muito menos do que todos usando o mesmo - uma frase que é verdadeira para cada debate de formatação em software e acreditada por aproximadamente ninguém no meio do debate.
Mergulho Técnico Profundo: as convenções que valem a pena ter opiniões sobre
Caixa de palavras-chave. Palavras-chave maiúsculas, identificadores minúsculos é a convenção dominante e minha recomendação O argumento é & #39; t tradição - it' s robustez O realce de sintaxe desaparece em logs, terminais, comentários de revisão de código e respostas Stack Overflow coladas no Slack; palavras-chave maiúsculas estão destacando que viaja com o texto O contra-argumento (minúsculas tudo, deixe o editor destacar) é coerente e I & #39; tem trabalhado em bases de código que o usaram alegremente O que & #39; não é coerente é misturar, que é o que você obtém sem um formatador reforçando a escolha.
Uma cláusula por linha, conteúdos recuados. A regra estrutural com maior recompensa. SELECT Inicia uma linha; suas colunas são recuadas abaixo (ou na mesma linha, se curtas). cada JOIN obtém sua própria linha com sua ON condição visível - as condições de junção ocultas na linha média são onde os bugs de junção errada se escondem. WHERE As condições empilham um por linha, alinhada, com AND/OR Liderando cada linha para que a estrutura lógica leia verticalmente. Quando as condições de uma consulta são lidas como uma coluna, uma condição ausente é visível como um lacuna em um padrão, que os olhos humanos são excepcionalmente bons em detectar.
A guerra de vírgulas. As vírgulas à direita (após cada coluna) lidas naturalmente; as vírgulas líderes (antes de cada coluna, no início da linha) tornam a pontuação estrutural:
-- Trailing (most common)
SELECT
u.id,
u.email,
o.total
-- Leading (the DBA classic)
SELECT
u.id
, u.email
, o.total
Os defensores da vírgula principal têm dois pontos genuinamente bons: comentar qualquer linha, exceto a primeira, nunca quebra a declaração, e uma vírgula ausente é instantaneamente visível na margem esquerda. Os defensores da vírgula final têm uma: parece que todas as outras linguagens que você escreve. Escrevo vírgulas finais e parei de me sentir mal com isso - mas observe que o SQL, ao contrário do JavaScript ou Python moderno, sim não perdoe uma vírgula pendurada após a coluna final, e é por isso que este debate existe e é por isso que o estilo líder se recusa a morrer nos círculos DBA. Divulgação completa: o formatador Toolz.dev fica do lado mainstream e emite vírgulas à direita - não tem modo de vírgula principal, então se você & #39; é uma loja de vírgulas líder comprometida, esta é a única convenção que ela ganhou & #39; t reformatar para você Escolha um estilo de casa, aplique-o de forma consistente e siga em frente.
O que a formatação não faz. Não otimiza. um formatado SELECT * Em uma junção de cinco mesas, há um problema de desempenho maravilhosamente recuado. A formatação é o pré-condição para otimização - você não pode raciocinar sobre uma consulta que não pode ler - mas o raciocínio ainda requer EXPLAIN, índice de reconhecimento e conhecimento da forma dos seus dados. Penso no pipeline como: formato, leitura, EXPLAIN, então otimize. Pular o primeiro passo não o torna mais rápido; torna os passos dois a quatro mais lentos. A mesma disciplina aplica uma camada acima da API, e é por isso que o Guia do formatador JSON Faz um argumento estruturalmente idêntico sobre cargas úteis.
Os comentários sobrevivem. Ao contrário da minificação, a formatação preserva os comentários - -- Comentários de linha e /* */ Os blocos chegam intactos. Use-os. um -- deliberately LEFT JOIN: include customers with no orders O comentário acima é o seguro de bug mais barato já escrito, e é o comentário que minha história de terror de 340 linhas precisava.
Casos de uso comuns
Revisão do código
SQL não formatado em uma solicitação pull é uma revisão que é & #39; t vai acontecer - o revisor & #39; s olhos deslizam da parede de texto e a aprovação cai de qualquer maneira Formatar a consulta antes de abrir o PR é cortesia básica com recompensa mensurável: tipos de junção, agrupamentos de condições e listas de colunas tornam-se individualmente visíveis, o que significa que eles se tornam individualmente revisáveis Todo bug SQL genuíno I & #39; peguei em revisão - a junção errada, o não parentalizado OR, o DELETE faltando metade do seu WHERE cláusula - Eu peguei porque a consulta foi formatada bem o suficiente para ler linha por linha.
Depurando consultas geradas por ORM
ORMs são maravilhosos até que o ponto final seja lento, momento em que você precisa ver o SQL real - e a saída ORM é sempre uma linha densa Formate-o e a história aparecerá: o N + 1 que o carregamento ansioso perdeu, a definição de junção do relacionamento adicionada silenciosamente, o ORDER BY em uma coluna não indexada. Em Laravel Work, este é um ritual várias vezes semanal: telescópio, cópia, formato, estremece, corrija o código eloquente, repita. O formatador não diagnostica nada sozinho; torna a consulta legível o suficiente para você pode.
Arqueologia em consultas legadas
Todo sistema de longa duração os possui: o procedimento armazenado de 2015, a visualização de relatórios que ninguém se atreve a tocar, a consulta incorporada em um arquivo de configuração com o autor original' s formatação (ou seja, nenhum).Antes de modificar o SQL legado, formate-o e leia-o de ponta a ponta - você' encontrará rotineiramente condições que podem ' nunca ser verdade, junta-se a tabelas que não recebem mais gravações e lógica a equipe atual' suposições contradizem. Formatar primeiros turnos " consulta e quot legado assustador; em " consulta longa, mas legível, " que é um problema diferente e melhor.
Comparando versões de consulta
Quando um relatório & #39; s números mudam entre lançamentos, a pergunta é & quot; o que mudou na consulta, & quot; e a resposta requer a diffing duas versões - que só funciona se ambos são formatados identicamente primeiro Formatar ambos com as mesmas configurações, em seguida, executá-los através do ferramenta diff de texto: O ruído desaparece e as duas linhas mudadas ficam sozinhas. Essa sequência exata encontrou meu bug de junção interna, eventualmente. agora faço antes O dia e meio de confusão em vez de depois.
Ensino e documentação
SQL em tutoriais, runbooks e documentos internos é lido muito mais vezes do que é escrito, por leitores menos familiarizados com o esquema do que o autor Exemplos formatados com palavras-chave maiúsculas e estrutura de um conceito por linha são dramaticamente mais fáceis de aprender - a estrutura ensina junto com o conteúdo Quando escrevo documentação com consultas incorporadas, cada um passa primeiro pelo formatador; SQL não formatado em documentos informa ao leitor que o autor fez & #39; Espera que alguém realmente leia.
Convenções de formatação comparadas
| Escolha da convenção | Opção A | Opção B | minha tomada |
|---|---|---|---|
| caso de palavras-chave | SELECT (maiúscula) |
select (minúsculas) |
Maiúscula - sobrevive a contextos sem realçar |
| caso identificador | caixa_snake | Definições de tabela de correspondência | Definições de correspondência; nunca lute contra o esquema |
| vírgula | Trancando (id,) |
Liderando (, id) |
Perder, mas liderar é defensável - basta escolher um |
| Layout de clá | Uma cláusula por linha | linha única compacta | um por linha para qualquer coisa que tenha passado de trivial |
AND/OR colocação |
Liderando cada linha de condição | Travendo a linha anterior | Liderando - a lógica lê verticalmente |
| Condições de entrada | ON em sua própria linha ou em linha com JOIN |
Linha média enterrada | visível com a junção, sempre |
| Largura do recuo | 2 espaços | 4 espaços | Qualquer um; SQL se aninha menos que JSON, então 4 está bem aqui |
Nenhuma destas linhas tem uma resposta errada, e que o & #39; s precisamente a armadilha - porque cada opção é defensável, as equipes re-litiga-los para sempre, a menos que um formatador torna a decisão mecânica O movimento vencedor é chato: escolher, configurar, formatar tudo, e gastar o tempo argumento recuperado em coisas que afetam o plano de execução Para o resto do kit de ferramentas diárias em torno deste, veja o Guia de ferramentas de codificação E o mais amplo Kit de ferramentas para desenvolvedores web.
FAQ
O que faz um formatador SQL?
Um formatador SQL reescreve uma consulta & #39; s espaço em branco, quebras de linha e invólucro de palavras-chave em uma estrutura consistente e legível - cada cláusula em sua própria linha, condições e colunas recuadas, palavras-chave normalizadas para um caso O significado de instrução & #39; s é intocado: os analisadores SQL ignoram a formatação inteiramente, de modo que a consulta formatada retorna resultados idênticos com um plano de execução idêntico A mudança é puramente para os humanos que revisam, depuram e mantêm a consulta.
A formatação do SQL altera o desempenho da consulta?
No. Whitespace e caso de palavra-chave não são semânticos em SQL - o banco de dados analisa ambas as versões na mesma representação interna e produz o mesmo plano de execução, que você pode verificar executando EXPLAIN em cada um. A formatação é a pré-condição para o trabalho de desempenho em vez de um trabalho de desempenho em si: você não pode raciocinar sobre índices e ingressar na ordem em uma consulta que não pode ler.
As palavras-chave SQL devem ser maiúsculas ou minúsculas?
Ambos são válidos - as palavras-chave SQL são case-insensitive de acordo com o padrão - então esta é uma convenção de legibilidade, não uma regra de correção Palavras-chave maiúsculas (uppercase)SELECT, FROM, WHERE) continuam sendo a escolha mais comum porque atuam como destaques integrados em contextos que retiram as cores: logs, diffs, terminais e mensagens de texto simples. Seja qual for a sua escolha, a consistência em toda a base de código importa muito mais do que a escolha em si.
O que são vírgulas líderes no SQL e por que as pessoas as usam?
O estilo de vírgula principal coloca a vírgula no início de cada linha de coluna (, email) em vez do fim do anterior Os advogados gostam porque comentar qualquer coluna, exceto a primeira, nunca produz um erro de sintaxe, e as vírgulas ausentes são instantaneamente visíveis na margem esquerda - vantagens reais, já que o SQL tolera & #39; t tolerar uma vírgula pendente após a coluna final da maneira que o JavaScript moderno faz Vírgulas à direita permanecem mais comuns; qualquer um funciona se aplicado de forma consistente.
Posso formatar o SQL gerado por um ORM como Eloquent ou ActiveRecord?
Sim, e it' s um dos melhores usos de um formatador - ORM saída de depuração chega como uma única linha densa com aliases gerados por máquina, e formatá-lo é o primeiro passo de diagnosticar endpoints lentos e problemas N + 1. capturar a consulta a partir de seu ORM' s log (Laravel Telescope, ActiveRecord logs), colá-lo no formatador sqle leia o que o ORM realmente construiu antes de buscar EXPLAIN.
O formatador funciona com sintaxe MySQL, PostgreSQL e SQL Server?
Sim - formatadores práticos lidam com os principais dialetos' peculiaridades, preservando backticks MySQL, identificadores de aspas duplas PostgreSQL e :: Casts e colchetes do SQL Server em vez de reescrevê-los. O padrão ANSI SQL define o núcleo compartilhado, mas nenhum banco de dados de produção fala SQL padrão puro, portanto, a tolerância ao dialeto é um requisito para que um formatador seja útil em consultas reais.
É seguro colar consultas de produção em um formatador SQL online?
Apenas em um cliente, porque o SQL é excepcionalmente sensível: as consultas expõem seu esquema e as consultas copiadas de logs geralmente contêm valores literais, como e-mails ou IDs em WHERE cláusulas. o Formatador SQL Toolz.dev processa tudo no seu navegador sem nada transmitido ou armazenado - verifique você mesmo assistindo a guia Rede enquanto cola Evite formatadores baseados em servidor para qualquer coisa da produção.
A formatação preserva os comentários do SQL?
Sim - ambos -- Comentários de linha e /* */ Os comentários do bloco passam intactos, ao contrário da minificação, o que os exclui. Isso torna a formatação segura para consultas anotadas e procedimentos armazenados em que os comentários carregam a intenção. Use isso: um comentário de uma linha explicando uma LEFT JOIN Ou uma condição incomum é a proteção mais barata contra o próximo desenvolvedor "Corrigindo" algo que não estava quebrado.
