Formatar consultas SQL _

Como funciona a formatação SQL

A formatação SQL é uma reescrita orientada por lexer que percorre cada token da consulta e reemite o espaço em branco ao seu redor com base nas regras do dialeto escolhido. A semântica da consulta nunca muda — apenas o layout.

1. Escolha um dialeto. As crases do MySQL, os casts :: do PostgreSQL, os caminhos de tabela com pontos do BigQuery e os identificadores entre colchetes do T-SQL exigem um tokenizador que os reconheça. O seletor de dialeto escolhe qual gramática aplicar.
2. Tokenizar a entrada. O formatador divide a consulta num fluxo de tokens: palavras-chave (SELECT, JOIN), identificadores, literais, operadores, parênteses e comentários. Literais de string e identificadores com aspas são passados sem alteração para que a sintaxe específica do dialeto continue a funcionar.
3. Aplicar regras de layout. As cláusulas de nível superior (SELECT, FROM, WHERE, GROUP BY, ORDER BY) começam na sua própria linha. Expressões separadas por vírgula na lista de seleção e listas de colunas obtêm cada uma a sua linha, indentada pelo unidade de indentação escolhida.
4. Aplicar capitalização de palavras-chave. O seletor de capitalização reescreve as palavras-chave SQL reconhecidas para maiúsculas, minúsculas ou preserva a capitalização original. Os identificadores nunca são alterados — nomes de colunas e tabelas aparecem sempre tal como foram escritos.
5. Emitir a string formatada. O fluxo de tokens é reunido numa única string com o caractere de indentação (2 espaços, 4 espaços ou tabulação) e a regra de quebra de linha configurada. O modo ao vivo re-executa todo o pipeline com debounce de 200 ms enquanto você digita.

Por que formatar SQL

• Legibilidade dos diffs de pull-request. Um CTE de 200 linhas reescrito numa única linha transforma uma revisão de código num jogo de adivinhação. A formatação consistente mantém o diff focado na mudança que você realmente fez — uma nova coluna, um JOIN adicional, um predicado WHERE diferente — para que o revisor o veja sem ter de desembaraçar espaços em branco.
• Depuração mais fácil. Quando uma consulta devolve uma contagem de linhas errada, a primeira coisa que se faz é lê-la linha a linha. O SQL formatado coloca cada JOIN na sua própria linha e alinha os predicados WHERE, para que um AND em falta ou um OR espúrio salte à vista.
• Estilo consistente da equipa. A maioria das equipas adopta um guia de estilo SQL (dbt Labs, GitLab e Mode Analytics publicam os seus) e quer que cada consulta comprometida o siga. Um formatador executado antes do commit remove o argumento de estilo da revisão e deixa apenas a lógica para discutir.
• Partilhar SQL em documentação. Runbooks, retros de incidentes e documentos Notion beneficiam-se de SQL que se lê de cima para baixo. O SQL formatado cola-se de forma limpa num bloco de código delimitado e imprime-se de forma previsível em exportações PDF, sem quebras de linha estranhas a meio de uma palavra-chave.

Aplicações comuns

A formatação SQL aparece em engenharia analítica, desenvolvimento backend e operações sempre que uma consulta tem de ser lida por alguém que não a escreveu.

• Engenharia analítica: hook de pré-commit num projeto dbt que reformata cada ficheiro de modelo para que os diffs de PR fiquem focados em alterações de lógica e não em mudanças de espaço em branco.
• Administração de bases de dados: cole uma entrada de log de consultas lentas numa linha, formate-a e percorra a ordem dos joins ao escrever a retro do incidente.
• Documentação: retire uma consulta de um explore do Looker ou de um workbook do Tableau, formate-a para um runbook e incorpore-a como exemplo pronto a copiar para a rotação de plantão.

Um exemplo prático

Cole SELECT u.id,u.email,COUNT(o.id) FROM users u LEFT JOIN orders o ON o.user_id=u.id WHERE u.created_at > '2024-01-01' GROUP BY u.id,u.email ORDER BY u.id; no painel de entrada com o dialeto definido como PostgreSQL, indentação de 2 espaços e capitalização MAIÚSCULAS. A saída coloca SELECT, FROM, LEFT JOIN, WHERE, GROUP BY e ORDER BY em linhas próprias; cada coluna na lista de seleção e na lista de group-by obtém a sua própria linha indentada; e o predicado ON fica um nível de indentação mais fundo do que a palavra-chave JOIN a que pertence. A mesma consulta com o dialeto BigQuery produz saída idêntica neste caso, mas manteria identificadores entre crases se existissem.

FAQ

Quais dialetos SQL são suportados?

O menu de dialetos abrange SQL padrão, MySQL, PostgreSQL, SQLite, MariaDB, Transact-SQL (SQL Server / Azure SQL), BigQuery, Snowflake e Redshift. A biblioteca sql-formatter subjacente também reconhece DuckDB, Spark SQL, Hive, Trino, Db2, N1QL, PL/SQL, ClickHouse, TiDB e SingleStoreDB — escolher o dialeto mais próximo produz uma saída sensata mesmo quando o alvo exato não está na lista. Identificadores, literais de string e operadores específicos do dialeto (PostgreSQL @>, prefixos BigQuery SAFE.) são preservados tal como estão.

Isto valida o meu SQL?

Não. O formatador é um reescritor lexical, não um parser. Tokeniza a entrada, aplica regras de layout e emite o resultado; não verifica se a consulta é semanticamente válida, se as tabelas referenciadas existem ou se a sintaxe é legal no dialeto escolhido. Execute a saída formatada na base de dados real (ou num linter SQL como o SQLFluff) para uma verificação de correção real.

Por que as minhas palavras-chave estão a ser escritas em maiúsculas?

O menu de capitalização de palavras-chave está definido por padrão como MAIÚSCULAS, que é a convenção na maioria dos guias de estilo SQL publicados (dbt Labs, Mode, GitLab). Mude para minúsculas se a sua equipa escreve select / from em minúsculas, ou Preservar se quiser que a saída mantenha a capitalização que escreveu. Os identificadores nunca são afetados — apenas o conjunto de palavras-chave reconhecidas é reescrito.

A minha consulta é enviada para algum servidor?

Não. A biblioteca sql-formatter integrada corre no seu navegador, a formatação acontece localmente na sua máquina e o texto da consulta nunca atravessa a rede. Os únicos pedidos externos que esta página faz são os mesmos pedidos de analytics e publicidade que todas as páginas de tools.ultim8soft.com fazem; o texto SQL em si não faz parte de nenhum deles.

O SQL formatado de forma consistente deixa de ser um argumento de estilo assim que um formatador o trata. A ferramenta corre inteiramente no seu navegador, a consulta nunca sai da página, e o mesmo tokenizador com reconhecimento de dialeto que alimenta o pacote npm sql-formatter faz a reescrita.