Formatador/embelezador de SQL

O Formatador/embelezador de SQL é uma ferramenta gratuita que recebe um código SQL e devolve uma versão mais legível, com formatação consistente.

O que muda ao formatar um SQL?

A formatação altera a apresentação da consulta para facilitar a leitura de cláusulas, expressões e estruturas aninhadas. Em geral, adiciona quebras de linha e recuos em elementos como listas de SELECT, cláusulas JOIN, condições WHERE, subconsultas e expressões CASE.

A formatação não deve mudar o resultado pretendido da consulta. No entanto, existem diferenças entre os dialetos SQL, e apenas formatar não garante que uma instrução tenha mantido seu significado. Revise o SQL gerado antes de executá-lo com dados de produção, principalmente se ele usar operadores específicos de um fornecedor, extensões procedurais ou regras incomuns de uso de aspas.

Um formatador é útil para ler consultas de terceiros, revisar SQL gerado automaticamente, depurar uma instrução longa ou preparar código para um pull request. Uma disposição consistente também facilita a comparação de alterações, pois reduz diferenças de espaçamento que não têm relação com o conteúdo.

Como usar o formatador de SQL?

Cole ou digite a instrução no campo SQL e envie para receber a versão formatada em SQL embelezado. A entrada é enviada ao servidor por HTTPS para processamento e não fica armazenada.

1. Copie a instrução completa, incluindo todas as expressões de tabela comuns que precisam ser preservadas, e confira no resultado os comentários e qualquer ponto e vírgula final.
2. Insira o conteúdo no campo SQL. Sempre que possível, evite formatar trechos isolados.
3. Leia o resultado em SQL embelezado, prestando atenção especial às expressões aninhadas e à sintaxe específica do dialeto.
4. Execute a instrução formatada em um ambiente adequado de desenvolvimento ou homologação antes de implantá-la.

Ao trabalhar com bancos de dados sensíveis, consulte a política da sua organização antes de enviar o texto de uma consulta a qualquer ferramenta executada em servidor. Remova senhas, tokens de acesso, dados pessoais e valores literais confidenciais quando eles não forem necessários para entender a consulta.

Como interpretar o SQL embelezado?

Leia o resultado acompanhando os recuos e os limites das cláusulas. Não considere a nova disposição uma prova de que a instrução é válida. Normalmente, fica mais fácil distinguir SELECT, FROM, WHERE, GROUP BY e ORDER BY no nível principal quando cada parte lógica ocupa sua própria linha ou seu próprio nível de recuo.

• Subconsultas recuadas mostram onde o resultado interno é usado por uma instrução externa.
• Condições alinhadas facilitam a verificação da precedência de AND e OR. Por padrão, AND tem precedência sobre OR, e os parênteses continuam determinando o agrupamento lógico.
• Cláusulas JOIN separadas ajudam a identificar qual condição ON pertence a cada tabela.
• Listas de SELECT expandidas facilitam a identificação de vírgulas ausentes, colunas duplicadas e aliases ambíguos.
• Ramificações CASE visíveis ajudam a relacionar as palavras-chave WHEN, THEN, ELSE e END.

Strings entre aspas, números, sinais de pontuação e comentários têm significado em SQL. Por isso, verifique esses elementos em vez de presumir que servem apenas para apresentação. Caracteres acentuados ou não latinos podem ser válidos em literais de string e identificadores entre aspas, dependendo do banco de dados e da codificação de caracteres usada.

Exemplos simples de formatação

Considere esta entrada compacta.

Entrada: SELECT id,name FROM customers WHERE active=1 ORDER BY name;

Uma versão formatada e legível poderia ser apresentada assim.

Saída: SELECT id, name

FROM customers

WHERE active = 1

ORDER BY name;

Uma consulta com join se beneficia ainda mais dos recuos.

Entrada: SELECT o.id,c.name FROM orders o JOIN customers c ON c.id=o.customer_id WHERE o.total>100;

Uma saída legível poderia colocar SELECT, FROM, JOIN, ON e WHERE em linhas separadas, mantendo a comparação o.total > 100. O uso exato de maiúsculas e minúsculas, o espaçamento e a posição das linhas variam conforme a convenção de formatação. Portanto, considere estes exemplos apenas como possíveis disposições, não como um padrão de estilo garantido.

A formatação consegue encontrar erros de SQL?

Não. Embelezar o SQL não é o mesmo que validá-lo com o analisador sintático de um banco de dados. O resultado declarado desta ferramenta é um SQL formatado, portanto ela não deve ser usada como verificador de sintaxe, verificador de esquema ou planejador de execução.

Ainda assim, uma disposição mais clara pode revelar possíveis erros durante a revisão. Entre os exemplos comuns estão uma vírgula ausente em uma lista de SELECT, parênteses sem correspondência, uma string entre aspas sem fechamento, um JOIN sem a condição pretendida ou uma expressão com AND ou OR agrupada incorretamente. A formatação também pode facilitar a identificação de uma palavra reservada usada como identificador sem aspas.

Alguns problemas só podem ser confirmados no banco de dados de destino. Uma instrução aceita pelo PostgreSQL pode precisar de alterações para funcionar no Microsoft SQL Server, MySQL, Oracle Database ou SQLite. Tabelas ausentes, colunas desconhecidas, tipos de dados incompatíveis e falhas de permissão geralmente exigem o mecanismo do banco de dados ou uma ferramenta de desenvolvimento compatível com o dialeto para serem diagnosticados.

Quando não vale a pena formatar o SQL?

A formatação geralmente é desnecessária quando o SQL já segue um padrão consistente ou será consumido apenas por uma máquina. Reformatar consultas geradas automaticamente pode criar alterações desnecessárias no controle de versão sem melhorar o gerador que as produziu.

A formatação também pode não ser a etapa adequada nestas situações:

• Um arquivo de migração foi assinado, recebeu uma soma de verificação ou é comparado byte por byte de alguma outra forma.
• Uma consulta minificada ou compacta está incorporada a um artefato sensível ao tamanho e ninguém precisa revisá-la.
• A tarefa imediata é validar, analisar o plano de execução ou ajustar o desempenho, e não melhorar a legibilidade.
• A consulta contém valores confidenciais que, segundo a política da organização, não podem ser enviados a um serviço executado em servidor.

Para aplicar uma formatação repetível a todo um repositório, um formatador de linha de comando compatível com o dialeto pode ser mais adequado, pois sua configuração pode ser versionada junto com o código. No caso de payloads estruturados de API que contenham SQL, o Validador e embelezador de JSON pode ajudar a inspecionar o JSON ao redor, mas o próprio SQL ainda precisa ser tratado por uma ferramenta específica para SQL.

Perguntas frequentes

Formatar o SQL muda o comportamento de NULL?

Espaços em branco e recuos não alteram a lógica de três valores do SQL nem o comportamento de NULL. Mesmo assim, confira expressões como column = NULL, que geralmente precisam usar IS NULL, pois um formatador não corrige esse erro semântico.

Posso formatar várias instruções SQL de uma vez?

O suporte à formatação de várias instruções SQL de uma só vez não está documentado. Formate cada instrução separadamente.

É seguro manter os comentários na entrada?

Os comentários podem conter referências a tickets, nomes de hosts internos, dados de clientes ou observações operacionais, mesmo quando o SQL executável não inclui literais sensíveis. Revise tanto os comentários de linha quanto os comentários em bloco antes de enviar o texto ao servidor.

As palavras-chave SQL devem ficar em maiúsculas ou minúsculas?

Em geral, os dois estilos são aceitáveis, pois muitos mecanismos de banco de dados não diferenciam maiúsculas de minúsculas em palavras-chave sem aspas. Siga a convenção adotada pelo repositório e tenha cuidado com identificadores entre aspas, porque alguns bancos de dados preservam ou diferenciam a capitalização deles.

O que devo conferir antes de executar a consulta formatada?

Confirme o dialeto do banco de dados de destino, verifique as condições WHERE e JOIN e confira os limites das transações em instruções UPDATE, DELETE e de alteração de esquema. Execute primeiro as consultas arriscadas em um banco de desenvolvimento ou homologação, de preferência com dados representativos e backups adequados.