Como Formatar Queries SQL para Legibilidade e Depuração

Todo desenvolvedor já passou por isso. Você tira uma query lenta dos logs da aplicação, copia para o editor e se depara com uma muralha de 300 caracteres em letras minúsculas, sem espaços, sem quebras de linha e sem piedade. Ou você encontra uma resposta no Stack Overflow com exatamente a query que precisa, mas ela está escrita em uma única linha. Ou seu ORM gentilmente registra o SQL que está gerando — como uma única string concatenada. Em todos esses casos, a query bruta está tecnicamente correta, mas é praticamente ilegível.

Formatar SQL não é questão de estética. É sobre conseguir entender o que uma query faz de relance — quais tabelas ela lê, quais condições ela filtra e quais colunas ela retorna. Uma query bem formatada pode ser revisada, depurada e otimizada em minutos. Uma não formatada pode desperdiçar horas.

O Formatador de SQL do BrowseryTools permite colar qualquer query SQL e formatá-la instantaneamente com indentação adequada, palavras-chave em maiúsculas e separação de cláusulas — tudo processado localmente no seu navegador, sem que nenhuma query seja enviada a um servidor.

Por que SQL Não Formatado é Tão Doloroso

SQL é uma das poucas linguagens em que os desenvolvedores rotineiramente trabalham com código que não escreveram e não podem reformatar na fonte. Considere as três fontes mais comuns de SQL feio:

• Queries geradas por ORM. Hibernate, SQLAlchemy, ActiveRecord e seus similares geram SQL dinamicamente. Quando você ativa o log de queries para depurar um problema de desempenho, você obtém o SQL bruto gerado — geralmente uma única linha com valores de parâmetros dinâmicos, apelidos como t0_ e condições de junção que exigem algumas leituras para interpretar.
• Logs de queries de bancos de dados em produção. O slow query log do MySQL e o pg_stat_statements do PostgreSQL armazenam queries como foram submetidas — sem formatação aplicada. Esses são inestimáveis para análise de desempenho, mas quase impossíveis de ler sem reformatar primeiro.
• Respostas em uma linha do Stack Overflow e de documentação. Código compartilhado em respostas e documentos muitas vezes é comprimido em uma única linha para economizar espaço vertical. A lógica é sólida, mas o layout dificulta a adaptação ao seu próprio esquema.

Antes e Depois: A Mesma Query, Formatada

Aqui está uma query realista como pode aparecer em um slow query log ou saída de ORM — tudo em uma linha com palavras-chave em minúsculas:

select u.id,u.name,u.email,count(o.id) as order_count,sum(o.total) as total_spent from users u left join orders o on u.id=o.user_id where u.created_at>='2024-01-01' and u.status='active' group by u.id,u.name,u.email having count(o.id)>0 order by total_spent desc limit 20;

Após a formatação com convenções SQL consistentes, a mesma query torna-se imediatamente legível:

SELECT
    u.id,
    u.name,
    u.email,
    COUNT(o.id)  AS order_count,
    SUM(o.total) AS total_spent
FROM users AS u
LEFT JOIN orders AS o
    ON u.id = o.user_id
WHERE u.created_at >= '2024-01-01'
  AND u.status = 'active'
GROUP BY
    u.id,
    u.name,
    u.email
HAVING COUNT(o.id) > 0
ORDER BY total_spent DESC
LIMIT 20;

A estrutura agora é imediatamente visível: você pode ver que este é um relatório de usuários que puxa contagens de pedidos e totais de gastos, filtrado para usuários ativos a partir de 2024, agrupado por usuário e limitado aos 20 maiores gastadores. Isso levou cinco segundos para entender — em vez de cinco minutos.

Convenções de Formatação de SQL

Não existe um guia de estilo SQL oficial único, mas um conjunto de convenções amplamente aceitas emergiu no setor. Seguir essas convenções torna seu SQL legível para qualquer desenvolvedor que conheça a linguagem.

Palavras-Chave em Maiúsculas

Palavras-chave SQL — SELECT, FROM, WHERE, JOIN, ON, GROUP BY, ORDER BY, HAVING, LIMIT, INSERT, UPDATE, DELETE, WITH, AS, AND, OR, NOT, IN, LIKE, BETWEEN, IS NULL — devem estar em maiúsculas. Nomes de tabelas, colunas, apelidos e literais de string permanecem em sua capitalização natural. Esse contraste visual entre PALAVRAS-CHAVE e identificadores torna as queries digitalizáveis de relance.

Cada Cláusula Principal em Sua Própria Linha

Cada cláusula de nível superior começa em uma nova linha: SELECT, FROM, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT. Isso dá à query um esqueleto visual claro. Quando você abre uma query formatada, seu olho encontra imediatamente cada cláusula porque todas começam na margem esquerda (ou em um nível de indentação consistente).

Listas de Colunas e Condições Indentadas

Nomes de colunas na lista SELECT e condições em WHERE são indentados por quatro espaços (ou uma tabulação). Cada AND e OR em uma cláusula WHERE começa em sua própria linha no mesmo nível de indentação que a primeira condição, tornando trivial adicionar, remover ou comentar condições individuais:

WHERE u.created_at >= '2024-01-01'
  AND u.status = 'active'
  AND u.country IN ('US', 'CA', 'GB')

Posicionamento de Vírgula: Duas Escolas de Pensamento

O debate sobre posicionamento de vírgula em SQL é similar ao debate sobre vírgula final em JavaScript. Existem dois estilos legítimos:

• Vírgulas ao final (vírgula no final de cada linha): o estilo mais comum, compatível com como a maioria dos desenvolvedores escreve listas em outras linguagens. A desvantagem é que comentar o último item requer também remover sua vírgula final do item acima.
• Vírgula no início (vírgula no início de cada linha após a primeira): facilita comentar qualquer linha individual sem tocar nas linhas adjacentes. Preferido por equipes que frequentemente modificam listas de colunas durante o desenvolvimento.

Ambos são válidos. Escolha um e use-o consistentemente dentro de um projeto. O Formatador de SQL do BrowseryTools usa vírgulas ao final por padrão, o que se alinha com a maioria dos guias de estilo e é a convenção que a maioria dos leitores espera.

Apelidos Alinhados com AS

Sempre use AS explícito para apelidos — nunca o estilo de nome nu implícito que alguns dialetos permitem (COUNT(o.id) order_count). Quando vários apelidos aparecem em uma lista SELECT, alinhar a palavra-chave AS na mesma coluna torna a lista de apelidos digitalizável:

SELECT
    COUNT(o.id)      AS order_count,
    SUM(o.total)     AS total_spent,
    AVG(o.total)     AS average_order,
    MAX(o.created_at) AS last_order_date

Como Ler uma Query Complexa com Múltiplos JOINs

Quando você encontra uma query com três, quatro ou cinco JOINs, não comece do topo. Comece pela cláusula FROM. Isso diz qual é a tabela primária — a âncora da query. Cada JOIN subsequente adiciona outra tabela ao conjunto de resultados, e a condição ON diz como as linhas daquela tabela se relacionam com as linhas já acumuladas. Somente após entender o modelo de dados de FROM e JOIN você deve voltar a SELECT para ver quais colunas são retornadas, depois WHERE para filtragem e depois GROUP BY para agregação.

Ordem de leitura para qualquer query SELECT: FROM → JOIN(s) → WHERE → GROUP BY → HAVING → SELECT → ORDER BY → LIMIT. Isso corresponde à ordem em que o mecanismo de banco de dados processa as cláusulas, e mapeia como você deve raciocinar sobre os dados fluindo por cada etapa.

Formatação de Subqueries

Subqueries — queries aninhadas dentro de outra query — merecem seu próprio nível de indentação. Cada nível de aninhamento adiciona um nível de indentação, para que a estrutura permaneça clara mesmo com dois ou três níveis de profundidade:

SELECT
    u.id,
    u.name,
    u.email
FROM users AS u
WHERE u.id IN (
    SELECT DISTINCT o.user_id
    FROM orders AS o
    WHERE o.total > 500
      AND o.created_at >= '2024-01-01'
)
ORDER BY u.name;

A query interna é claramente subordinada à externa. O parêntese de fechamento está alinhado com a palavra-chave (WHERE) que introduziu a subquery. Para subqueries profundamente aninhadas ou complexas, CTEs (Expressões de Tabela Comuns) são quase sempre preferíveis porque podem ser nomeadas e colocadas no topo da query onde são fáceis de ler.

Padrões Comuns de Query e Suas Formas Formatadas

INSERT INTO ... SELECT

INSERT INTO order_archive (
    id,
    user_id,
    total,
    created_at
)
SELECT
    id,
    user_id,
    total,
    created_at
FROM orders
WHERE created_at < '2023-01-01';

UPDATE com JOIN (sintaxe MySQL / SQL Server)

UPDATE users AS u
JOIN subscriptions AS s
    ON u.id = s.user_id
SET u.plan = s.plan_name,
    u.plan_updated_at = NOW()
WHERE s.status = 'active'
  AND s.updated_at >= '2024-01-01';

Query com WITH (CTE)

Expressões de Tabela Comuns são a ferramenta de formatação mais poderosa em SQL. Elas permitem dar nomes a conjuntos de resultados intermediários, transformando uma query profundamente aninhada em uma série de etapas claramente nomeadas:

WITH active_users AS (
    SELECT id, name, email
    FROM users
    WHERE status = 'active'
      AND created_at >= '2024-01-01'
),
user_orders AS (
    SELECT
        user_id,
        COUNT(id)  AS order_count,
        SUM(total) AS total_spent
    FROM orders
    GROUP BY user_id
)
SELECT
    au.id,
    au.name,
    au.email,
    uo.order_count,
    uo.total_spent
FROM active_users AS au
LEFT JOIN user_orders AS uo
    ON au.id = uo.user_id
ORDER BY uo.total_spent DESC
LIMIT 20;

Por que a Formatação Importa para a Revisão de Desempenho

A formatação não é apenas sobre legibilidade para humanos — ela também torna os problemas de desempenho visíveis. Quando uma query está devidamente estruturada, várias classes de problemas se tornam fáceis de identificar:

• Índices ausentes. Uma cláusula WHERE formatada com todas as condições em suas próprias linhas facilita verificar que cada coluna de condição tem um índice. Sem formatação, condições enterradas em uma linha são fáceis de ignorar.
• Produtos cartesianos. Um JOIN sem uma condição ON (ou com uma condição sempre verdadeira) produz um cross join que multiplica contagens de linhas. Quando cada JOIN está em sua própria linha com sua condição ON indentada abaixo, uma condição ausente é imediatamente óbvia.
• Padrões N+1 em queries. Ver uma query selecionar uma lista de IDs em uma subquery e depois fazer join de volta à mesma tabela é um sinal de que a query poderia ser reescrita com um join direto — eliminando o N+1 no nível SQL em vez de no código da aplicação.
• Funções em colunas indexadas. WHERE DATE(created_at) = '2024-01-01' impede o banco de dados de usar um índice em created_at. Em uma query formatada, esse padrão se destaca; em uma linha minificada, é invisível.

Dialetos SQL: Diferenças de Sintaxe para Conhecer

SQL é um padrão (ISO/IEC 9075), mas todo grande banco de dados o estende com sintaxe específica de dialeto. Aqui está o que importa para a formatação:

PostgreSQL: Aspas Duplas e Sensibilidade a Maiúsculas

No PostgreSQL, identificadores sem aspas são convertidos para minúsculas. Se você criou uma tabela como CREATE TABLE "UserProfiles" (com aspas duplas), você deve sempre referenciá-la como "UserProfiles" com aspas. Sem aspas, o PostgreSQL procura userprofiles e falha. Isso é uma fonte comum de confusão ao migrar do MySQL ou quando ORMs geram esquemas com nomes mistos.

MySQL: Citação com Crases

MySQL usa crases para citar identificadores, não aspas duplas (embora o MySQL no modo ANSI_QUOTES aceite aspas duplas). Você verá crases no DDL gerado pelo MySQL e em queries exportadas por ferramentas como phpMyAdmin. O Formatador de SQL lida com identificadores entre crases e os preserva para que a saída permaneça válida para o seu banco de dados específico.

Como Usar o Formatador de SQL do BrowseryTools

Usar o formatador leva três passos:

• Cole sua query. Copie o SQL bruto do arquivo de log, saída do ORM ou editor e cole na área de entrada. O formatador aceita qualquer quantidade de SQL — instruções únicas, múltiplas instruções ou scripts completos.
• Clique em Formatar. O formatador aplica palavras-chave em maiúsculas, separação de cláusulas, indentação e espaçamento consistente. O resultado aparece no painel de saída instantaneamente — sem requisição de rede e sem demora.
• Copie o resultado. Use o botão Copiar para colocar o SQL formatado na área de transferência, pronto para colar no seu editor, cliente de banco de dados ou PR.

Como o formatador funciona inteiramente no seu navegador, você pode colar com segurança queries contendo dados sensíveis — nomes de tabelas de produção, IDs de clientes, detalhes internos de esquema — sem que nada saia do seu computador. Não há backend para registrar suas queries.

Formate Suas Queries SQL Agora

Seja desembaraçando um monstro gerado por ORM, revisando o pull request de um colega, depurando uma query lenta ou apenas tentando entender o que uma resposta do Stack Overflow está realmente fazendo — SQL formatado torna cada uma dessas tarefas mais rápida e menos propensa a erros. Boa formatação é a otimização de desempenho mais barata que você pode fazer antes de recorrer ao EXPLAIN.