Por que eu construí o SchemaBrain

Eu não queria dar a um agente de IA acesso direto ao SQL bruto do Postgres em produção — então construí um limite diferente. Um que compila a intenção em SQL seguro, recusa PII antes da execução da consulta e mantém uma auditoria à prova de adulteração.

Um comando — sem chave de API, sem Docker, sem Postgres. O firewall computa a métrica segura, recusa os dois vazamentos (PII + credenciais), recupera os dois que não consegue responder e então verifica a cadeia de auditoria. O agente nunca escreveu SQL.

Passei minha carreira como engenheiro de dados — Postgres, RDS, Oracle, dbt. A maior parte dela foi para uma verdade silenciosa e sem glamour: o esquema nunca é toda a história. Nomes de colunas mentem. A lógica de negócios que os explica vive na cabeça de alguém, em uma página do Confluence que ninguém atualizou há dois anos, em um thread do Teams ou Slack. Uma coluna status tem sete valores e apenas três deles significam o que você imaginaria. Eu vi isso de perto, mais de uma vez.

Aqui está o que esse trabalho te ensina: qualquer coisa pode ser dados, mas o que realmente é útil é a parte que é curada — a parte da qual você pode inferir algo real. Transformar tabelas brutas em significados em que você pode confiar é o trabalho inteiro da engenharia de dados.

Então, quando os agentes de IA começaram a ter acesso ao banco de dados, eu os vi bater na mesma parede que os humanos — exceto mais rápido e mais confiantes em seus erros. Eles tinham o esquema. Eles não tinham o significado.

O verdadeiro problema

Apontar um modelo capaz para um banco de dados Postgres em produção e três coisas dão errado quase imediatamente.

O esquema não se encaixa na janela de contexto, e não ajudaria se se encaixasse. Um banco de dados real tem centenas de tabelas e milhares de colunas. Mesmo que você despeje tudo isso no prompt, o agente ainda não sabe que unit_price_cents é um inteiro em centavos, ou que "receita" significa itens de linha de assinatura contratados e não faturas coletadas. O esquema te diz a forma. Não te diz o significado.

Colunas crípticas. dt_ref, flg_2, amt. O modelo adivinha. Às vezes ele adivinha certo. O caso perigoso é quando ele adivinha plausivelmente e você não percebe.

O verdadeiro perigo do SQL bruto. Este é o que me impediu de enviar a solução óbvia. O padrão padrão — dar ao agente uma ferramenta que executa SQL — significa que o agente pode executar qualquer SQL. Um agente confuso escreve um cross join de 40 milhões de linhas. Um agente desbloqueado lê sua tabela users, incluindo a coluna que ninguém se lembrou que armazenava chaves de API em texto simples. E você descobre pelo log de auditoria, se você tiver um.

A resposta usual é "dê credenciais somente de leitura e espere." Somente leitura impede as gravações. Não faz nada sobre o cross join, e nada sobre um agente felizmente SELECT-ando cada endereço de e-mail no banco de dados porque um prompt pediu.

A percepção

A solução não é um prompt melhor ou um modelo mais inteligente. É um limite diferente.

Eu não queria dar ao agente controle total sobre os dados apenas para que ele pudesse entender os dados — essas são duas coisas diferentes, e confundir elas é todo o problema. Então eu parei de pensar nisso como "dar acesso ao banco de dados ao agente" e comecei a pensar nisso como uma camada de confiança e inteligência que fica entre o agente e o Postgres. Uma camada com uma opinião forte: o agente nunca escreve SQL, e a camada nunca executa SQL que o agente escreveu.

A camada fica entre o agente e o Postgres. O agente envia a intenção; o SchemaBrain compila e executa o SQL por conta própria.

Em vez disso, o agente expressa intenção — uma entidade, uma métrica, um grão ("receita contratada, por nível de plano"). O SchemaBrain compila essa intenção em SQL parametrizado por conta própria e o executa. O agente recebe linhas de volta, e recebe o SQL exato que foi executado, mas não há caminho de um prompt do agente para uma declaração arbitrária em seu banco de dados. A garantia é estrutural, não uma flag de configuração que o agente pode contornar.

Uma vez que você tem essa etapa de compilação, você pode colocar verificações reais na fronteira:

• Recusar PII antes da consulta ser executada, não depois que já está na resposta.
• Recusar-se a fabricar — se o join não existir, diga isso, e devolva uma maneira legível por máquina de recuperar em vez de um parágrafo que o agente tem que analisar.
• Registrar cada chamada em um log à prova de adulteração, para que "o que o agente realmente fez" tenha uma resposta criptográfica.

O que é realmente o SchemaBrain

É um servidor MCP de código aberto (Apache-2.0) que dá aos agentes de IA acesso seguro e semântico a um banco de dados Postgres. É local-first: o servidor roda inteiramente na sua máquina, e as consultas de um agente nunca saem dela. A única coisa que pode sair da caixa é a passagem opcional de enriquecimento semântico no tempo de indexação — uma chamada LLM com custo limitado com amostras redigidas que você opta por incluir — e a demonstração incluída nem isso. Essa restrição não é uma estratégia de marketing que eu acrescentei; é o ponto inteiro. A proposta de confiança só funciona se a própria camada de confiança não estiver silenciosamente enviando seu esquema para algum lugar.

Concretamente, quatro estágios:

1. Indexação. O SchemaBrain lê seu esquema do Postgres em um armazenamento local SQLite. Tabelas, colunas, tipos, chaves estrangeiras declaradas.

2. Enriquecimento semântico. É aqui que vem a inteligência. Uma passagem LLM com custo limitado escreve uma descrição em linguagem simples para cada coluna, propõe entidades (a tabela users é um Usuário), e minera joins de três fontes: chaves estrangeiras declaradas, seu log de consultas e testes de relationships do dbt. Ele constrói um gráfico de joins canônico com BFS de múltiplas etapas, para que a camada saiba como chegar de Usuário a Fatura mesmo quando são três etapas através de uma tabela de junção. Embeddings no dispositivo (BAAI/bge-small, ONNX) alimentam a recuperação semântica por cosseno, para que o agente possa encontrar as tabelas certas pelo significado, não apenas pelo nome. Você revisa e aplica as sugestões explicitamente — nada é auto-confirmado em sua camada semântica.

O SchemaBrain oferece uma solução inovadora para empresas brasileiras que buscam integrar agentes de IA com segurança em seus bancos de dados. Ele evita o acesso direto a SQL, protegendo informações sensíveis e garantindo auditoria. Isso é crucial para a conformidade e segurança de dados em um ambiente cada vez mais digital.