Safe SQL Execution: rastreie a origem do SQL no Supabase Studio

ANÁLISE EDITORIAL

Uma consulta pode sair da interface de um produto e chegar ao banco do próprio usuário. Nesse caminho, a pergunta decisiva não é apenas se o SQL está bem formado, mas quem controlou cada fragmento antes da execução. A Skill Safe SQL Execution, mantida no repositório do Supabase, documenta essa fronteira para quem desenvolve o Supabase Studio. Ela ajuda um agente a reconhecer SQL escrito pelo usuário, SQL fixo da aplicação e texto influenciável por terceiros. Não instala uma proteção automática e não substitui revisão de código.

O que a Skill faz

O arquivo orienta a revisão de qualquer código que monte, obtenha, apresente ou execute SQL contra o Postgres de um usuário no Supabase Studio. O gatilho é amplo de propósito: vale para editores de políticas RLS, construtores de consultas, rotas com nomes de tabelas, trechos salvos e botões que executam SQL. A instrução pede que o agente carregue a Skill antes de alterar esse fluxo, mesmo quando a solicitação parece ser apenas uma melhoria de interface. O motivo está no próprio mapa de Skills do monorepositório, que identifica essa orientação para alterações que constroem ou executam consultas.

O modelo descrito distingue três origens. SQL fixo no código da aplicação pode usar o utilitário safeSql. Texto que pode ser influenciado por terceiros, como um parâmetro de URL ou saída de um modelo, deve permanecer marcado como não confiável com untrustedSql. SQL digitado pelo usuário na interface exige cuidado extra: um campo preenchido previamente com dado externo mistura origens, e um clique não deve ser presumido onde há execução automática. Tipos como SafeSqlFragment e UntrustedSqlFragment ajudam a tornar essa distinção visível no código. São convenções específicas do projeto, não uma propriedade universal de toda consulta SQL.

Para quem serve, e para quem não serve

A página interessa sobretudo a quem contribui com o Supabase Studio ou revisa integrações que seguem as mesmas convenções de seu código. É especialmente útil quando uma mudança toca o editor SQL, políticas RLS, definições de funções e views ou consultas de logs. O valor da Skill está em oferecer perguntas concretas para uma revisão: de onde veio o fragmento, onde ele foi classificado, quem o pode alterar e qual gesto autoriza a execução? Ela também serve como estudo de caso para equipes que desejam desenhar uma fronteira semelhante, desde que adaptem as regras ao próprio produto em vez de copiar tipos e caminhos inexistentes.

Não é um guia genérico de administração do Postgres nem uma ferramenta para otimizar consultas. A Skill cita módulos internos do Studio e do pacote pg-meta; fora desse monorepositório, esses nomes podem não existir. Também não concede permissão para um agente abrir o banco, alterar políticas ou executar SQL em nome do leitor. O fato de uma expressão estar tipada como segura não prova que o usuário tenha privilégio correto, que o SQL faça o que se pretendia ou que não haja outro risco de segurança no aplicativo.

Compatibilidade e pré-requisitos

O download local contém um SKILL.md no formato de instrução para agentes. Para uso direto, é preciso um agente que reconheça Skills e um checkout compatível do repositório supabase/supabase, no qual os utilitários citados estejam presentes. Esta cópia foi fixada no commit 7425d4930528931400fb3e656e860b1094cb224e. Antes de aplicar exemplos, compare o checkout real, as assinaturas do @supabase/pg-meta e os arquivos do Studio. A estrutura pode mudar em commits posteriores; o ZIP não acompanha essas alterações automaticamente.

Para apenas estudar a proposta, não é necessário configurar Supabase, Postgres nem uma conta. Para revisar uma mudança real, o agente precisa de acesso de leitura ao código afetado e às convenções do projeto. Testes locais, quando autorizados, dependem das dependências e do ambiente do repositório; não estão embutidos nesta Skill. A pasta oficial de pg-meta é uma referência para conferir as funções citadas, enquanto o componente SafeSqlInput mostra como a origem da entrada é tratada no contexto do Studio.

Instalação e configuração segura

Baixe o ZIP documental no card desta página, compare o SHA-256 publicado e confira seu conteúdo antes de extrair. O arquivo contém .agents/skills/safe-sql-execution/SKILL.md, LICENSE e ORIGEM.md. O último identifica repositório, commit, licença e hashes de origem. Se você estiver trabalhando no monorepositório da Supabase no mesmo commit, a Skill já faz parte da árvore oficial: não duplique a pasta. Prefira ler a versão presente no checkout e compare-a com este pacote apenas para auditoria ou estudo.

Em outro projeto, copie a pasta safe-sql-execution para o local de Skills aceito pelo seu agente somente se houver uma razão clara para adaptar a metodologia. Confira no cliente se a Skill foi carregada e informe ao agente que os caminhos do Supabase são exemplos, não arquivos garantidos no seu projeto. Comece com uma revisão somente leitura. Não conecte credenciais de produção nem permita que uma instrução documental execute SQL automaticamente. O botão de repositório oficial leva ao conteúdo do mantenedor; o download local é uma cópia separada e limitada, não um instalador do Studio.

Primeiro uso e resultado esperado

Escolha uma alteração pequena que forme uma consulta a partir de nome de tabela, coluna ou filtro recebido pela interface. Peça ao agente: “Leia a Skill Safe SQL Execution do projeto, examine somente os arquivos envolvidos e trace a origem de cada parte da consulta até a função de execução. Diferencie texto fixo, parâmetro externo e entrada escrita pelo usuário. Aponte onde há sanitização ou aprovação explícita. Não edite arquivos e não execute SQL.” O pedido produz um mapa de fluxo verificável, não uma mudança automática. Depois, o desenvolvedor decide se precisa de um patch, de teste ou de uma revisão de segurança formal.

O resultado esperado é uma análise com caminhos de arquivo, pontos de entrada, tipos de fragmento e o local em que o SQL chegaria à função de execução. Se um identificador vier de parâmetro externo, a Skill sugere as funções apropriadas para identificadores, literais ou palavras-chave permitidas, como ident, literal e keyword, conforme o caso. Uma string arbitrária não vira segura apenas porque foi interpolada num template. Se a expressão for livre, como parte de uma política RLS, o fluxo documentado exige uma ação explícita do usuário para promover o fragmento não confiável antes da execução. Isso ainda pede revisão da interface e de testes: o texto da Skill não prova que uma implementação específica esteja correta.

Permissões, dados e riscos

O pacote em si só contém Markdown e licença. O risco aparece quando o agente recebe ferramentas para ler repositórios privados, modificar código ou usar um banco. Dê acesso mínimo: no primeiro uso, leitura do trecho necessário e nenhuma credencial de produção. Se um teste requerer execução, use ambiente descartável, confirme o SQL final e aprove separadamente o comando e seu destino. Nunca cole chaves, cadeias de conexão ou dados de clientes numa consulta pública para explicar o problema. A documentação oficial do banco de dados da Supabase ajuda a situar o Postgres no produto, mas não deve ser interpretada como autorização para operar um projeto específico.

Há duas armadilhas que a Skill destaca. Trechos de SQL salvos automaticamente podem voltar do banco com aparência de conteúdo do próprio usuário, sem que a origem tenha sido revalidada; o documento trata snippets como não confiáveis. E uma função que promove SQL não confiável, como acceptUntrustedSql, deve ficar dentro do manipulador de uma ação explícita, não em useEffect, renderização ou consulta que possa disparar sozinha. Para logs em BigQuery e ClickHouse, a Skill descreve uma marcação separada, SafeLogSqlFragment, porque as regras de escape não são intercambiáveis com as do Postgres. Misturar marcas seria um erro conceitual, mesmo que um exemplo pareça compilar.

Se algo der errado

Se o agente não encontrar safeSql, SafeSqlInput ou executeSql, confirme primeiro o commit do checkout, o pacote e o caminho. Não invente importações para completar um exemplo. Abra a árvore oficial fixada e procure a implementação atual no repositório em uso. Se o código tipado rejeitar uma string bruta, trate o erro como sinal para rastrear a origem; um cast para SafeSqlFragment pode silenciar o compilador sem resolver o risco. Quando a necessidade é apenas mostrar SQL, use um tipo de apresentação e não um atalho para executar.

Se uma consulta parece disparar sem clique, procure useQuery, efeitos, estados derivados e pré-preenchimento por URL. Retire a promoção de fragmentos não confiáveis de qualquer caminho automático e submeta a mudança a revisão humana. Se um snippet salvo for reapresentado, confirme que o usuário vê o conteúdo antes da ação de executar. Para analytics, não reuse helpers de Postgres em consultas BigQuery ou ClickHouse; volte ao módulo específico de logs citado no texto da Skill. Quando faltar contexto ou teste, registre essa limitação em vez de afirmar que a consulta está segura.

Revisão, licença e download local

O projeto oficial supabase/supabase tinha 111.684 estrelas na consulta à API do GitHub em 17/10/2026. Esse número é temporal e não mede a eficácia desta Skill. O mantenedor é a organização Supabase, o caminho auditado é .agents/skills/safe-sql-execution/SKILL.md, e a revisão foi fixada no commit 7425d4930528931400fb3e656e860b1094cb224e. O arquivo LICENSE do mesmo commit contém a Apache License 2.0, que permite redistribuição com preservação dos avisos. A página não afirma que houve execução de testes no Studio.

O espelho local preserva o SKILL.md original, inclui a licença e adiciona ORIGEM.md com hashes dos arquivos. Seu SHA-256 é 2647e08158ff1551060db2da99739c8dd029b020d280c95a397b316203619c62. Compare esse valor após o download. O pacote não contém o aplicativo, módulos npm, scripts, executáveis, binários, dependências, credenciais ou dados. O card de download e o botão para o repositório são ações diferentes. A fonte oficial pode ter mudado depois do commit fixado; quem for usar a Skill no projeto deve conferir o estado atual antes de aplicar qualquer orientação a produção.

Fontes primárias

• SKILL.md oficial Safe SQL Execution, commit auditado.
• AGENTS.md do monorepositório Supabase.
• Licença Apache-2.0 no commit fixado.
• Código de pg-meta no repositório oficial.
• Visão geral oficial do banco de dados Supabase.