---
type: rule
name: consultar-banco-query-ia
description: Define como agentes devem consultar o banco de dados via rota dedicada /query-ia — proibindo acesso direto ao banco fora deste protocolo
scope: global
trigger: context_match
priority: alta
updatedAt: "2026-07-01"
---

# Regra: Consultar Banco de Dados via `/query-ia`

## Contexto

Quando um agente precisa inspecionar dados reais do banco de dados — para diagnóstico, auditoria, validação de registros ou investigação de bugs — existe uma rota dedicada e segura para isso no backend do projeto.

Essa rota é exclusiva para desenvolvimento e **nunca deve ser usada em produção**. Ela bloqueia automaticamente comandos destrutivos.

## Rota

```
GET  http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia   → retorna documentação da rota (texto plano)
POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia   → executa consulta SQL e retorna JSON
```

> **`<porta-back>` e `<nome_modulo>` são definidos por módulo** — cada módulo do ecossistema usa uma porta e prefixo de rota específicos (ex: `http://127.0.0.1:5260/qualifica/query-ia`). Antes de usar a rota:
> - O acesso **GET** retorna a documentação do endpoint.
> - O acesso **POST** executa a consulta SQL e retorna os dados em JSON.
> - Verificar `package.json` do `*-back` (campo `scripts.dev` ou `scripts.start`) ou o arquivo `.env` do módulo.

## Como usar

### Descobrir a porta e consultar a documentação

```bash
# Verificar a porta no package.json do módulo back
cat package.json | jq '.scripts.dev'

# Consultar a documentação da rota (substitua <porta-back> pela porta real)
curl http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia
```

### Executar uma consulta SQL

```bash
curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
  -H 'Content-Type: application/json' \
  -d '{
    "sql": "SELECT * FROM empresas LIMIT 10",
    "parametros": []
  }' | jq .
```

### Consulta com parâmetros (binding seguro)

```bash
curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
  -H 'Content-Type: application/json' \
  -d '{
    "sql": "SELECT * FROM avaliacoes WHERE empresa_id = ? AND status = ?",
    "parametros": ["uuid-da-empresa", "aprovado"]
  }' | jq .
```

## Comandos bloqueados

Os seguintes comandos são **automaticamente rejeitados** pela rota (retorno 400):

- `DELETE`
- `UPDATE`
- `DROP`
- `ALTER`
- `TRUNCATE`
- `INSERT`

Apenas **leitura** (`SELECT`, `WITH`, `EXPLAIN`, etc.) é permitida.

## Retorno

```json
{
  "rows": [...],
  "rowCount": 42
}
```

Em caso de erro SQL:

```json
{
  "erro": "mensagem de erro",
  "stack": "stack trace (apenas em desenvolvimento)"
}
```

## Regra

O agente **DEVE** usar esta rota sempre que precisar de dados reais do banco — diagnóstico, contagem de registros, verificação de estado, auditoria de dados.

O agente **NUNCA** deve:

- Tentar acessar o banco diretamente via código (modificar arquivos para adicionar logs de DB)
- Inventar dados ou assumir estado sem verificar
- Usar esta rota para comandos de escrita — use as APIs REST do módulo para isso

## Exemplos

### ✅ Correto — inspecionar registros via query-ia

```bash
curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
  -d '{"sql": "SELECT codigo, nome, status FROM empresas ORDER BY criado_em DESC LIMIT 20"}' \
  -H 'Content-Type: application/json' | jq '.rows'
```

### ✅ Correto — verificar schemas PostgreSQL disponíveis

```bash
curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
  -d '{"sql": "SELECT schema_name FROM information_schema.schemata ORDER BY schema_name"}' \
  -H 'Content-Type: application/json' | jq '.rows'
```

### ✅ Correto — contar registros por inquilino

```bash
curl -s -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
  -d '{"sql": "SELECT inquilino, COUNT(*) as total FROM empresas GROUP BY inquilino"}' \
  -H 'Content-Type: application/json' | jq '.rows'
```

### ❌ Errado — tentar escrever via query-ia

```bash
# Será bloqueado com status 400
curl -X POST http://127.0.0.1:<porta-back>/<nome_modulo>/query-ia \
  -d '{"sql": "UPDATE empresas SET status = ?", "parametros": ["ativo"]}'`
```

### ❌ Errado — modificar código para adicionar log de banco

```typescript
// NÃO fazer isso para "ver os dados" — usar a rota query-ia
const debug = await dbKnex('empresas').select('*').limit(10)
console.log(debug)
```

## Impacto

Sem esta regra, agentes podem modificar código de produção apenas para inspecionar dados, ou assumir estados do banco sem verificação — gerando diagnósticos incorretos e alterações desnecessárias.

## Referências

- Implementação de referência: `qualifica-back/src/utilitarios-IA/query-ia.ts`
- Rule: `global/rules/autonomia-agente` (ações autônomas sem aprovação)