pagodera/docs/PRISMA_QUERY_LOGS.md

# 📊 Prisma Query Logs - Explicação Completa

## 🔍 O que são os logs `prisma:query`?

Os logs `prisma:query` são **queries SQL que o Prisma executa automaticamente** no banco de dados PostgreSQL. Eles aparecem no console durante o desenvolvimento para ajudar você a:

1. **Debugar** - Ver exatamente quais queries estão sendo executadas
2. **Otimizar** - Identificar queries lentas ou desnecessárias
3. **Entender** - Compreender o que o Prisma está fazendo "por baixo dos panos"

---

## ⚙️ Configuração Atual

No arquivo `lib/prisma/app.ts`, o Prisma está configurado assim:

```typescript
export const prisma = new PrismaClient({
  log:
    process.env.NODE_ENV === "development"
      ? ["query", "error", "warn"]  // ← Loga queries em desenvolvimento
      : ["error"],                  // ← Apenas erros em produção
});
```

**Isso significa:**
- ✅ **Em desenvolvimento**: Mostra todas as queries SQL
- ✅ **Em produção**: Apenas mostra erros (não mostra queries)

---

## 📝 Análise dos Logs do Seu Terminal

### 1. **INSERT de Telemetria** (Linhas 24-26, 58-59, 93-94)

```sql
INSERT INTO "public"."telemetry_events" 
  ("event_type","ad_id","user_id","session_id","metadata","timestamp") 
VALUES ($1,$2,$3,$4,$5,$6) 
RETURNING ...
```

**O que é:**
- Registra eventos de telemetria (cliques, visualizações, etc.)
- Executado quando o usuário interage com a página

**Por que aparece:**
- O sistema de telemetria está ativo e registrando eventos

---

### 2. **SELECT de Listings** (Linhas 35-36, 79-80)

```sql
SELECT COUNT(*) AS "_count$_all" 
FROM (SELECT "public"."listings"."listing_id" 
      FROM "public"."listings" 
      WHERE "public"."listings"."listing_status" = $1 
      OFFSET $2) AS "sub"
```

**O que é:**
- Conta quantos anúncios ativos existem
- Usado para paginação

**E depois:**

```sql
SELECT "public"."listings"."listing_id", 
       "public"."listings"."seller_id",
       "public"."listings"."item_id",
       -- ... todos os campos ...
FROM "public"."listings" 
WHERE "public"."listings"."listing_status" = $1 
ORDER BY "public"."listings"."created_at" DESC 
LIMIT $2 OFFSET $3
```

**O que é:**
- Busca os anúncios ativos com paginação
- Ordena por data de criação (mais recentes primeiro)
- Limita a 20 resultados por página

**Por que aparece:**
- A página do marketplace (`/en/market`) está carregando
- Está buscando anúncios para exibir

---

### 3. **SELECT de Characters** (Linhas 37, 81)

```sql
SELECT "public"."user_characters"."character_id", 
       "public"."user_characters"."user_id",
       "public"."user_characters"."character_name",
       "public"."user_characters"."server_name",
       "public"."user_characters"."is_main",
       "public"."user_characters"."verified",
       "public"."user_characters"."created_at" 
FROM "public"."user_characters" 
WHERE ("public"."user_characters"."user_id" = $1 
       AND "public"."user_characters"."server_name" = $2 
       AND "public"."user_characters"."is_main" = $3) 
LIMIT $4 OFFSET $5
```

**O que é:**
- Busca o personagem principal do vendedor
- Usado para exibir o nome do personagem nos cards de anúncio

**Por que aparece:**
- Para cada anúncio, busca o nome do personagem do vendedor
- Isso acontece porque implementamos a busca de `seller_character_name`

---

### 4. **SELECT de Servers** (Linha 66)

```sql
SELECT "public"."servers"."server_id", 
       "public"."servers"."server_name",
       -- ... outros campos ...
FROM "public"."servers" 
WHERE "public"."servers"."is_active" = $1 
ORDER BY "public"."servers"."server_name" ASC 
OFFSET $2
```

**O que é:**
- Busca todos os servidores ativos
- Usado para popular o filtro de servidores no marketplace

**Por que aparece:**
- O componente de filtros está carregando a lista de servidores

---

### 5. **BEGIN / COMMIT** (Linhas 23, 27, 57, 60, 92, 95)

```sql
BEGIN
-- ... queries ...
COMMIT
```

**O que é:**
- **Transações** do banco de dados
- Garante que múltiplas operações sejam executadas atomicamente
- Se uma falhar, todas são revertidas (ROLLBACK)

**Por que aparece:**
- Operações que precisam de atomicidade (ex: inserir múltiplos eventos de telemetria em batch)

---

## 🎯 Por que isso é útil?

### ✅ Benefícios:

1. **Debugging:**
   - Ver exatamente quais queries estão sendo executadas
   - Identificar queries N+1 (muitas queries desnecessárias)
   - Verificar se os índices estão sendo usados

2. **Performance:**
   - Identificar queries lentas
   - Ver quantas queries estão sendo executadas
   - Otimizar queries que são executadas repetidamente

3. **Entendimento:**
   - Aprender como o Prisma traduz suas operações para SQL
   - Ver como os relacionamentos são resolvidos

---

## ⚙️ Como Controlar os Logs

### Opção 1: Desabilitar completamente (não recomendado em dev)

```typescript
// lib/prisma/app.ts
export const prisma = new PrismaClient({
  log: ["error"], // Apenas erros
});
```

### Opção 2: Apenas erros e warnings

```typescript
export const prisma = new PrismaClient({
  log: ["error", "warn"],
});
```

### Opção 3: Logs mais detalhados (com informações de tempo)

```typescript
export const prisma = new PrismaClient({
  log: [
    { level: "query", emit: "event" },
    { level: "error", emit: "stdout" },
    { level: "warn", emit: "stdout" },
  ],
});
```

### Opção 4: Manter como está (recomendado)

```typescript
// Atual (já está assim)
export const prisma = new PrismaClient({
  log:
    process.env.NODE_ENV === "development"
      ? ["query", "error", "warn"]  // ← Bom para desenvolvimento
      : ["error"],                   // ← Otimizado para produção
});
```

**✅ Recomendação:** Manter como está! Os logs são úteis em desenvolvimento e não aparecem em produção.

---

## 🔍 Análise de Performance dos Seus Logs

### Queries que aparecem frequentemente:

1. **SELECT listings** (2 queries):
   - Uma para contar total
   - Uma para buscar os itens
   - **Status:** ✅ Normal (paginação requer ambas)

2. **SELECT user_characters** (1 por anúncio):
   - Busca o personagem do vendedor
   - **Status:** ⚠️ Potencial otimização
   - **Sugestão:** Já está otimizado com `Map` para evitar queries duplicadas

3. **INSERT telemetry_events** (em batch):
   - Múltiplos eventos inseridos em uma transação
   - **Status:** ✅ Otimizado (usa transação)

---

## 📊 Níveis de Log do Prisma

O Prisma suporta diferentes níveis de log:

```typescript
log: [
  "query",    // Todas as queries SQL
  "info",     // Informações gerais
  "warn",     // Avisos
  "error",    // Erros
]
```

**Ou com eventos:**

```typescript
log: [
  { level: "query", emit: "event" },  // Evento customizado
  { level: "error", emit: "stdout" }, // Console padrão
]
```

---

## 🎯 Conclusão

**Os logs `prisma:query` são:**
- ✅ **Normais** - Esperados em desenvolvimento
- ✅ **Úteis** - Ajudam a debugar e otimizar
- ✅ **Automáticos** - Não afetam performance
- ✅ **Desabilitados em produção** - Não aparecem em produção

**Você deve:**
- ✅ **Manter** os logs em desenvolvimento
- ✅ **Usar** para identificar problemas de performance
- ✅ **Ignorar** se não estiver debuggando (são apenas informativos)

---

## 🔗 Referências

- [Prisma Logging Documentation](https://www.prisma.io/docs/concepts/components/prisma-client/working-with-prismaclient/logging)
- [Prisma Query Performance](https://www.prisma.io/docs/guides/performance-and-optimization/query-optimization-performance)