diagnosticando-banco

name: diagnosticando-banco description: >- Skill READ-only de diagnostico de saude, performance e otimizacao do PostgreSQL (script local + Postgres MCP Pro). Usar quando o usuario pergunta "como esta o banco?", "queries lentas", "cache hit rate", "precisa de vacuum?", "quais indices criar?", "EXPLAIN ANALYZE", "por que essa query e lenta?", "sequences proximas do limite?". NAO usar para consultas analiticas de dados de negocio -> consultando-sql. Matriz USAR/NAO-USAR completa no corpo. allowed-tools: Read, Bash, Glob, Grep, mcp__postgres__analyze_db_health, mcp__postgres__get_top_queries, mcp__postgres__analyze_workload_indexes, mcp__postgres__analyze_query_indexes, mcp__postgres__explain_query, mcp__postgres__execute_sql, mcp__postgres__list_schemas, mcp__postgres__list_objects, mcp__postgres__get_object_details

Diagnosticando Banco — Health Check & Otimizacao PostgreSQL

Skill para diagnosticos de saude, performance e otimizacao do banco PostgreSQL. Combina um script local com o Postgres MCP Pro (9 tools DBA-level).

ESCOPO: Esta skill executa checks read-only no banco. Nao modifica dados nem estrutura. Para consultas de dados de negocio, use consultando-sql. Para metricas de infra (CPU, memoria, HTTP), use mcp__render__get_metrics.

Quando usar / Quando NAO usar

USAR QUANDO: diagnostico de saude, performance e otimizacao do PostgreSQL — incluindo analisar plano de execucao de uma query, receber sugestoes de indices para melhorar performance, ou investigar problemas de lentidao no banco. Gatilhos por categoria:

• Saude geral: "como esta o banco?", "saude do banco", "indices nao usados", "cache hit rate", "bloat"
• Conexoes: "quantas conexoes?", "conexoes ativas", "conexoes idle", "pool"
• Vacuum: "precisa de vacuum?", "dead tuples", "tabelas inchadas"
• Sequences: "sequences proximas do limite?", "risco de overflow INTEGER"
• Tamanho: "maiores tabelas", "tamanho do banco", "quanto ocupa?"
• Indices: "quais indices criar?", "recomendacao de indice", "indice pra essa query", "indices redundantes", "indice hipotetico"
• Performance: "query lenta", "otimizar query", "EXPLAIN", "EXPLAIN ANALYZE", "plano de execucao", "por que essa query e lenta?"

NAO USAR PARA:

REGRAS CRITICAS

R1: FIDELIDADE AO OUTPUT

OBRIGATORIO: Toda informacao apresentada ao usuario DEVE vir EXATAMENTE
do output da tool ou script utilizado.

PROIBIDO:
- Inventar valores que nao existem no output (ex: "shared_buffers = 256MB")
- Arredondar ou alterar percentuais do output
- Especular causa de problemas sem evidencia no output
- Inventar recomendacoes com valores especificos nao fornecidos pela tool

PERMITIDO:
- Usar as faixas de interpretacao desta SKILL.md (cache >= 99% = EXCELENTE)
- Citar acoes sugeridas que existem no output
- Alertar sobre dados criticos (sequences > 50%, cache < 90%)

R2: MODO DE EXECUCAO — QUAL USAR

O sistema oferece 3 modos. A escolha depende do contexto:

MODO 1 — POSTGRES MCP PRO (preferido para producao)
  Quando: Claude Code com acesso ao MCP server "postgres"
  Como: Chamar tools mcp__postgres__* diretamente
  Vantagem: 9 tools DBA-level, recomendacao de indices, EXPLAIN hipotetico
  Usar para: health check, queries lentas, otimizacao de indices, EXPLAIN

MODO 2 — SCRIPT LOCAL (dev/staging)
  Quando: Ambiente local com acesso ao banco via .env
  Como: Executar health_check_banco.py via Bash
  Vantagem: JSON estruturado, resumo executivo, 9 checks combinaveis
  Usar para: checks rapidos em dev, validacao pre-deploy

MODO 3 — RENDER MCP SQL (fallback para producao)
  Quando: MCP postgres NAO disponivel (ex: agente web)
  Como: mcp__render__query_render_postgres com SQLs desta skill
  Vantagem: Funciona sem postgres-mcp instalado
  Usar para: checks basicos quando Modo 1 indisponivel

Regra de selecao: Tentar Modo 1 primeiro. Se tool nao disponivel, usar Modo 2 (local) ou Modo 3 (producao).

R3: RESULTADOS VAZIOS OU ERROS

Se o output retorna lista vazia ou total: 0:
  → Informar CLARAMENTE: "Nenhum [tipo] encontrado"
  → NAO inventar explicacao para resultado vazio

Se a tool/script falha (erro de conexao, permissao):
  → Mostrar a mensagem de erro EXATA
  → Sugerir verificar conexao com o banco
  → NAO tentar adivinhar a causa

DECISION TREE — Qual Ferramenta Usar?

Diagnosticos de saude (checks existentes)

Otimizacao de performance (capacidades NOVAS — apenas Modo 1)

Estas capacidades so estao disponiveis via Postgres MCP Pro (Modo 1). Se o usuario pedir e o MCP nao estiver disponivel, informar que requer o server postgres-mcp.

R4: NAO IMPROVISAR CAPACIDADES DO MODO 1

QUANDO O USUARIO PEDIR:
- Recomendacao de indices para o banco (analyze_workload_indexes)
- Recomendacao de indice para query especifica (analyze_query_indexes)
- EXPLAIN / plano de execucao (explain_query)

E O MCP POSTGRES NAO ESTIVER DISPONIVEL:

→ INFORMAR: "Essa capacidade requer o server postgres-mcp que nao esta ativo."
→ NAO IMPROVISAR: NAO tentar substituir com queries manuais, scripts ou Modo 3
→ MOTIVO: Essas tools usam algoritmos internos (workload analysis, hypothetical indexes)
          que NAO podem ser replicados com SQL simples. Improvisar gera resultados
          de qualidade inferior e pode levar a recomendacoes incorretas.

EXCECAO: get_object_details e list_objects podem ser substituidos por queries
information_schema/pg_catalog (Modo 3), pois retornam dados factuais.

Cenarios Compostos

"Diagnostico completo" ou "o que precisa de atencao":

1. Modo 1: analyze_db_health (cobre tudo em uma chamada)
2. Modo 2: --all --resumo primeiro → detalhar problemas
3. Priorizar: sequences > 50% → cache < 90% → vacuum > 10% → indices

"Essa query ta lenta, o que fazer?":

1. explain_query com a query do usuario → ver plano de execucao
2. analyze_query_indexes com a query → receber recomendacao de indice
3. Apresentar: plano atual + indice sugerido + ganho estimado

"Quais indices criar pra melhorar performance?":

1. analyze_workload_indexes → analisa queries reais do pg_stat_statements
2. Apresentar: indices sugeridos com impacto estimado
3. Se usuario quiser validar: explain_query com indice hipotetico

Modo 1: Postgres MCP Pro (producao — preferido)

Tools Disponiveis

Exemplo de uso: Diagnostico completo

1. Chamar mcp__postgres__analyze_db_health
2. Se problemas de performance → mcp__postgres__get_top_queries
3. Se queries lentas identificadas → mcp__postgres__analyze_query_indexes com as queries
4. Apresentar resultado consolidado ao usuario

Exemplo de uso: Otimizar query

1. mcp__postgres__explain_query com a query do usuario
2. mcp__postgres__analyze_query_indexes com a mesma query
3. Se indice sugerido → mcp__postgres__explain_query novamente COM indice hipotetico
4. Mostrar: plano antes vs depois + indice sugerido

Modo 2: Script Local (dev/staging)

source .venv/bin/activate && \
python .claude/skills/diagnosticando-banco/scripts/health_check_banco.py [opcoes]

Combinando Checks

# Checks especificos combinados
health_check_banco.py --check unused_indexes cache_hit_rate connections

# Todos com resumo executivo
health_check_banco.py --all --resumo

Para parametros completos, retornos JSON e exemplos: LER SCRIPTS.md

Modo 3: Render MCP SQL (fallback producao)

Para producao quando Postgres MCP Pro nao estiver disponivel. Usar mcp__render__query_render_postgres com o postgresId do banco sistema-fretes-db — obter o ID em .claude/references/INFRAESTRUTURA.md (secao "IDs dos Recursos", linha Postgres / sistema-fretes-db).

Indices Nao Usados

SELECT s.relname AS tabela, s.indexrelname AS indice,
       pg_size_pretty(pg_relation_size(s.indexrelid)) AS tamanho,
       s.idx_scan AS scans
FROM pg_stat_user_indexes s
JOIN pg_index i ON s.indexrelid = i.indexrelid
WHERE s.idx_scan = 0 AND NOT i.indisunique AND NOT i.indisprimary
  AND s.schemaname = 'public'
ORDER BY pg_relation_size(s.indexrelid) DESC LIMIT 20;

Cache Hit Rate

SELECT round(sum(heap_blks_hit)::numeric /
  NULLIF(sum(heap_blks_hit) + sum(heap_blks_read), 0) * 100, 2) AS hit_rate_pct
FROM pg_statio_user_tables;

Top Queries Lentas (requer pg_stat_statements)

SELECT substring(query, 1, 200) AS query, calls,
       round(total_exec_time::numeric, 2) AS tempo_total_ms,
       round(mean_exec_time::numeric, 2) AS tempo_medio_ms, rows
FROM pg_stat_statements
WHERE query NOT LIKE 'SET %' AND query NOT LIKE 'BEGIN%'
  AND userid = (SELECT usesysid FROM pg_user WHERE usename = current_user)
ORDER BY total_exec_time DESC LIMIT 10;

Conexoes Ativas

SELECT state, count(*) AS quantidade,
  max(extract(epoch from (now() - state_change)))::integer AS max_duracao_seg
FROM pg_stat_activity WHERE pid <> pg_backend_pid()
GROUP BY state ORDER BY quantidade DESC;

Maiores Tabelas

SELECT relname AS tabela,
  pg_size_pretty(pg_total_relation_size(relid)) AS tamanho_total,
  n_live_tup AS linhas_vivas, n_dead_tup AS linhas_mortas
FROM pg_stat_user_tables WHERE schemaname = 'public'
ORDER BY pg_total_relation_size(relid) DESC LIMIT 20;

Sequences (Risco de Overflow INTEGER)

SELECT sequencename, last_value,
  round(last_value::numeric / 2147483647 * 100, 4) AS uso_pct
FROM pg_sequences WHERE schemaname = 'public' AND last_value IS NOT NULL
ORDER BY last_value DESC;

Interpretacao de Resultados

Cache Hit Rate

Sequences

Vacuum

Conexoes

Formato de Resposta ao Usuario

Diagnostico Completo

## Saude do Banco: [STATUS]

### Problemas Encontrados
- [Listar problemas — EXATAMENTE como vem do output]

### Destaques
- [Listar destaques positivos — EXATAMENTE como vem do output]

### Detalhes [se solicitado]
[Expandir checks individuais com dados EXATOS do output]

Recomendacao de Indices (novo)

## Indices Recomendados

### Indice 1: [nome sugerido]
- Tabela: [tabela]
- Colunas: [colunas]
- Impacto estimado: [ganho projetado pela tool]
- Query beneficiada: [query que melhora]

### Como criar:
CREATE INDEX CONCURRENTLY [nome] ON [tabela] ([colunas]);

Nota: Usar CONCURRENTLY para nao bloquear operacoes.

Analise de Query (novo)

## Analise de Performance: [query resumida]

### Plano de Execucao Atual
[Output do EXPLAIN formatado]

### Gargalos Identificados
- [Seq Scan onde Index Scan seria melhor]
- [Custo alto em operacoes especificas]

### Indice Sugerido
[CREATE INDEX recomendado]

### Plano Estimado COM Indice
[Output do EXPLAIN com indice hipotetico, se disponivel]

Pre-requisitos

Nota sobre HypoPG: explain_query suporta indices hipoteticos, mas depende da extensao HypoPG estar instalada no servidor. No Render, HypoPG nao esta disponivel, entao indices hipoteticos nao funcionarao no EXPLAIN. O analyze_workload_indexes e analyze_query_indexes ainda funcionam normalmente (usam algoritmo proprio para recomendar indices).

Referencia Cruzada