Tutorial: construir um endpoint NL2SQL no Postgres

Um endpoint que recebe uma pergunta em linguagem natural, transforma-a em uma consulta SQL validada e limitada e retorna o resultado. O mecanismo nunca executa SQL gerado sem controle: cada consulta passa por validação sintática antes de chegar ao banco de dados.

A questão passa por um LLM configurado — OpenAI, Anthropic (Claude) ou Gemini, os três provedores nativos — que gera um SQL candidato. Este SQL nunca é executado como está: ele passa por um validador que analisa sua árvore de sintaxe (sqlparser), permite apenas consultas SELECT simples e adiciona um LIMIT limitado se algum estiver faltando.

O validador rejeita explicitamente CTE/WITH, subconsultas, UNIONs, cláusulas de bloqueio (FOR UPDATE) e qualquer função fora de uma lista de permissões (count, sum, avg, min, max, lower, upper, coalesce, date_trunc, now). Junções de múltiplas tabelas são suportadas.

Pergunta→LLM (OpenAI/Claude/Gemini)→Validação AST (sqlparser)→Limit limitado→Execução SELECT

O diagrama consultado nunca é fornecido por sua solicitação: ele é introspectado a partir da base real do projeto. Um campo schema, allowed_schema ou schema_context enviado no corpo da solicitação é explicitamente recusado (erro 400) em vez de ignorado silenciosamente - somente o servidor decide o que realmente existe.

Com o JavaScript SDK, o cliente Aurabase expõe aura.ai.nl2sql(). A assinatura é nl2sql(question, options): o esquema não faz parte dela, é introspectado no lado do servidor.

import { aura } from '@/lib/aurabase'

export async function POST(req: Request) {
  const { question } = await req.json()

  const { data, error } = await aura.ai.nl2sql(
    question,
    { limit: 50 }
  )

  if (error) return Response.json({ error }, { status: 400 })
  return Response.json(data)
}

No HTTP bruto, o endpoint é POST /v1/ai/{project_id}/nl2sql, autenticado pela chave de API do projeto.

curl -X POST https://<votre-gateway>/v1/ai/<project_id>/nl2sql \
  -H "apikey: <votre-cle-api>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Combien de commandes ont été passées ce mois-ci par des clients premium ?",
    "limit": 50
  }'

Pergunta enviada: “Quantos pedidos foram feitos este mês por clientes premium?”. Aqui está a forma do SQL realmente renderizado (nomes de tabelas e colunas dependem do seu esquema):

{
  "data": {
    "sql": "SELECT count(*) FROM orders WHERE customer_plan = 'premium' AND created_at >= date_trunc('month', now()) LIMIT 50",
    "explanation": "Compte les commandes de ce mois pour les clients premium.",
    "confidence": 0.85,
    "tables": ["orders"],
    "columns": ["customer_plan", "created_at"],
    "limit": 50,
    "limit_injected": false
  },
  "meta": null
}

limit_injected indica se LIMIT vem do modelo ou foi adicionado pelo servidor. confidence é uma heurística na forma da resposta (bloco SQL bem formado ou não) - não uma medida de correção semântica do SQL gerado. Uma pergunta mal formulada retorna um erro explícito em vez de um SQL alucinado: por exemplo, se o SQL gerado consultar uma tabela que não está no seu esquema, a mensagem nomeia as tabelas realmente disponíveis.

Três verificações antes da implantação: o limite de linha (LIMIT) está adaptado ao seu volume, a função Postgres usada pelo mecanismo permanece restrita ao esquema do projeto e as tabelas confidenciais têm uma política RLS ativa - NL2SQL consulta o mesmo banco de dados que o resto do seu aplicativo, ele não possui direitos de acesso estendidos por padrão.

• O limite de linha padrão é configurável no lado do servidor; um valor solicitado acima do limite do servidor é negado explicitamente, em vez de ser reduzido silenciosamente.
• O acesso ao catálogo do sistema (pg_catalog, information_schema) e aos esquemas que não são do projeto é bloqueado pelo validador, independentemente de suas políticas de RLS.
• O RLS continua sendo sua última linha de defesa em tabelas confidenciais: o validador limita a forma do SQL, não os direitos comerciais sobre os dados.

O mecanismo é estritamente legível: apenas solicitações SELECT são aceitas. Qualquer tentativa deINSERT, UPDATE, DELETE, DROP, CREATE ou ALTER gerada pelo modelo é rejeitada antes da execução - esta não é uma convenção de prompt, é uma regra imposta no nível da árvore de sintaxe.

Outros limites estruturais: sem subconsultas, sem CTE/WITH, sem UNION e uma lista de permissões fechada de dez funções SQL. Uma pergunta que naturalmente exige uma subconsulta (“clientes que nunca fizeram pedidos”) deve ser reformulada para caber em uma simples SELECT, ou tratada de forma diferente no lado da aplicação.

NL2SQL cobre questões estruturadas sobre seus dados relacionais. Para dúvidas sobre conteúdo não estruturado (documentos, notas, tickets), o RAG nativo do Aurabase depende do pgvector e de uma pesquisa HNSW. Ambos os recursos - e como combiná-los em um agente - são detalhados na página IA nativa no Postgres.