Formatador/embelezador de SQL

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

O que muda quando se formata SQL?

A formatação altera a apresentação de uma consulta para facilitar a leitura das cláusulas, expressões e estruturas aninhadas. É comum acrescentar quebras de linha e avanços em elementos como listas SELECT, cláusulas JOIN, condições WHERE, subconsultas e expressões CASE.

A formatação não deve alterar o resultado pretendido da consulta. No entanto, os dialetos de SQL variam e a formatação, por si só, não garante que uma instrução manteve o mesmo significado. Revê o SQL gerado antes de o executares com dados de produção, sobretudo se usar operadores específicos de um fornecedor, extensões procedimentais ou regras de delimitação pouco habituais.

Um formatador é útil para ler consultas de terceiros, rever SQL gerado, depurar uma instrução longa ou preparar código para um pull request. Uma apresentação consistente também facilita a comparação de alterações, pois reduz diferenças de espaçamento irrelevantes.

Como se usa o formatador de SQL?

Cola ou introduz a instrução no campo SQL e envia-a para receberes a versão formatada em SQL embelezado. Os dados introduzidos são enviados ao servidor através de HTTPS para processamento e não são armazenados.

1. Copia a instrução completa, incluindo todas as expressões de tabela comuns que pretendas manter, e verifica no resultado os comentários e qualquer ponto e vírgula final.
2. Sempre que possível, introduz a instrução no campo SQL em vez de formatares fragmentos isolados.
3. Lê o resultado em SQL embelezado, prestando especial atenção às expressões aninhadas e à sintaxe específica do dialeto.
4. Executa a instrução formatada num ambiente de desenvolvimento ou de pré-produção adequado antes de a colocares em produção.

Se trabalhares com bases de dados sensíveis, consulta a política da tua organização antes de enviares o texto de uma consulta para qualquer ferramenta alojada num servidor. Remove palavras-passe, tokens de acesso, dados pessoais e valores literais confidenciais que não sejam necessários para compreender a consulta.

Como devo interpretar o SQL embelezado?

Lê o resultado seguindo os avanços e os limites das cláusulas, sem tomares a nova apresentação como prova de que a instrução é válida. Normalmente, torna-se mais fácil distinguir SELECT, FROM, WHERE, GROUP BY e ORDER BY de nível superior quando cada parte lógica ocupa a sua própria linha ou nível de avanço.

• Subconsultas com avanço 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. Ainda assim, por predefinição, AND tem precedência sobre OR e os parênteses continuam a determinar o agrupamento lógico.
• Cláusulas JOIN separadas ajudam a perceber que condição ON pertence a cada tabela.
• Listas SELECT expandidas facilitam a deteção de vírgulas em falta, colunas duplicadas e aliases ambíguos.
• Ramos CASE visíveis ajudam a associar corretamente as palavras-chave WHEN, THEN, ELSE e END.

As cadeias entre aspas, os números, a pontuação e os comentários têm significado em SQL. Por isso, verifica-os em vez de assumires que são apenas elementos de apresentação. Os caracteres acentuados ou não latinos podem ser válidos em literais de cadeia e identificadores delimitados, consoante a base de dados e a respetiva codificação de caracteres.

Pequenos exemplos de formatação

Considera esta entrada compacta.

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

Uma versão formatada e legível poderia ter a seguinte apresentação.

Saída: SELECT id, name

FROM customers

WHERE active = 1

ORDER BY name;

Uma consulta com uma junção beneficia ainda mais dos avanços.

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. A utilização de maiúsculas, o espaçamento e a posição exata das linhas variam entre convenções de formatação. Considera, por isso, estes exemplos como possíveis apresentações, não como um estilo obrigatório.

A formatação consegue detetar erros de SQL?

Não. Embelezar SQL não é o mesmo que validá-lo com o analisador sintático de uma base de dados. O resultado indicado por esta ferramenta é SQL formatado, pelo que não deves usá-la como verificador de sintaxe ou de esquemas, nem como analisador de planos de execução.

Mesmo assim, uma apresentação mais clara pode revelar possíveis erros durante a revisão. Entre os exemplos comuns estão uma vírgula em falta numa lista SELECT, parênteses sem correspondência, uma cadeia entre aspas sem terminação, um JOIN sem a condição pretendida ou uma expressão AND ou OR agrupada incorretamente. Também pode tornar mais evidente uma palavra reservada usada como identificador sem delimitação.

Alguns problemas não podem ser confirmados sem conhecer a base de dados de destino. Uma instrução aceite pelo PostgreSQL pode precisar de alterações para funcionar no Microsoft SQL Server, MySQL, Oracle Database ou SQLite. Em geral, são necessários o motor da base de dados ou uma ferramenta de desenvolvimento que reconheça o dialeto para diagnosticar tabelas inexistentes, colunas desconhecidas, tipos de dados incompatíveis e falhas de permissões.

Quando não vale a pena formatar SQL?

A formatação costuma ser desnecessária quando o SQL já tem uma apresentação consistente ou se destina apenas a ser processado por uma máquina. Reformatar consultas geradas pode criar muitas alterações irrelevantes no controlo de versões sem melhorar o gerador que as produziu.

A formatação também pode não ser o passo certo nestas situações:

• Um ficheiro de migração foi assinado, recebeu uma soma de verificação ou é comparado byte a byte de outra forma.
• Uma consulta minimizada ou compacta está integrada num artefacto com restrições de tamanho e ninguém precisa de a rever.
• A tarefa imediata é validar, analisar o plano de execução ou otimizar 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 para um serviço alojado num servidor.

Para aplicar uma formatação repetível a todo um repositório, um formatador de linha de comandos que reconheça o dialeto pode ser mais adequado, pois a respetiva configuração pode ser guardada no repositório juntamente com o código. No caso de conteúdos estruturados de API que incluam SQL, o Validador e embelezador de JSON pode ajudar a inspecionar o JSON envolvente, mas o SQL continua a exigir tratamento específico.

Perguntas frequentes

Formatar SQL altera o comportamento de NULL?

Os espaços em branco e os avanços não alteram a lógica trivalente do SQL nem o comportamento de NULL. Ainda assim, verifica expressões como column = NULL, que normalmente exigem IS NULL, porque um formatador não corrige esse erro semântico.

Posso formatar várias instruções SQL ao mesmo tempo?

O suporte para várias instruções SQL em simultâneo não está documentado. Formata cada instrução separadamente.

É seguro deixar comentários no conteúdo introduzido?

Os comentários podem incluir referências a tickets, nomes de anfitriões internos, dados de clientes ou notas operacionais, mesmo quando o SQL executável não contém literais sensíveis. Revê os comentários de linha e os comentários de bloco antes de enviares o texto para o servidor.

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

Em geral, ambos os estilos são aceitáveis, porque muitos motores de bases de dados não distinguem entre maiúsculas e minúsculas nas palavras-chave não delimitadas. Segue a convenção usada no repositório e tem cuidado com os identificadores delimitados, pois algumas bases de dados preservam ou distinguem a capitalização.

O que devo verificar antes de executar a consulta formatada?

Confirma o dialeto da base de dados de destino, inspeciona as condições WHERE e JOIN e verifica os limites das transações em instruções UPDATE, DELETE e de alteração do esquema. Executa primeiro as consultas de risco numa base de dados de desenvolvimento ou de pré-produção, de preferência com dados representativos e cópias de segurança adequadas.