heath impl

db-connection-pool.md

@@ -0,0 +1,129 @@
+# Configuração de Pool de Conexões
+
+Este documento descreve a configuração do pool de conexões implementada para os bancos de dados Oracle e PostgreSQL na aplicação.
+
+## Visão Geral
+
+O pool de conexões é uma técnica que mantém um conjunto de conexões abertas com o banco de dados, permitindo seu reuso entre diferentes requisições. Isso traz diversos benefícios:
+
+- **Melhor performance**: Eliminação do overhead de abertura e fechamento de conexões
+- **Melhor escalabilidade**: Gerenciamento eficiente do número máximo de conexões
+- **Maior resiliência**: Tratamento de falhas de conexão e reconexão automática
+- **Menor carga no banco de dados**: Menor número de operações de login/logout
+
+## Configuração do Oracle
+
+### Parâmetros Configuráveis
+
+Os seguintes parâmetros podem ser configurados através do arquivo `.env`:
+
+| Parâmetro | Descrição | Valor Padrão |
+|-----------|-----------|--------------|
+| `ORACLE_POOL_MIN` | Número mínimo de conexões no pool | 5 |
+| `ORACLE_POOL_MAX` | Número máximo de conexões no pool | 20 |
+| `ORACLE_POOL_INCREMENT` | Incremento no número de conexões quando necessário | 5 |
+| `ORACLE_POOL_TIMEOUT` | Tempo máximo (ms) para obter uma conexão | 30000 |
+| `ORACLE_POOL_IDLE_TIMEOUT` | Tempo máximo (ms) que uma conexão pode ficar inativa | 300000 |
+
+### Configurações Adicionais
+
+Além dos parâmetros acima, as seguintes configurações foram implementadas:
+
+- **Statement Cache**: Cache de 30 statements para melhorar a performance de queries repetidas
+- **Connection Class**: Identificador 'PORTALJURU' para rastrear conexões no banco
+- **Pool Ping Interval**: Verificação a cada 60 segundos para manter conexões ativas
+- **Enable Stats**: Habilitação de estatísticas para monitoramento do pool
+
+## Configuração do PostgreSQL
+
+### Parâmetros Configuráveis
+
+Os seguintes parâmetros podem ser configurados através do arquivo `.env`:
+
+| Parâmetro | Descrição | Valor Padrão |
+|-----------|-----------|--------------|
+| `POSTGRES_POOL_MIN` | Número mínimo de conexões no pool | 5 |
+| `POSTGRES_POOL_MAX` | Número máximo de conexões no pool | 20 |
+| `POSTGRES_POOL_IDLE_TIMEOUT` | Tempo máximo (ms) que uma conexão pode ficar inativa | 30000 |
+| `POSTGRES_POOL_CONNECTION_TIMEOUT` | Tempo máximo (ms) para estabelecer uma conexão | 5000 |
+| `POSTGRES_POOL_ACQUIRE_TIMEOUT` | Tempo máximo (ms) para obter uma conexão do pool | 60000 |
+
+### Configurações Adicionais
+
+Além dos parâmetros acima, as seguintes configurações foram implementadas:
+
+- **Statement Timeout**: Limite de 10 segundos para execução de queries
+- **Query Timeout**: Limite de 10 segundos para execução de queries
+- **SSL**: Configuração automática baseada no ambiente (development/production)
+- **Query Cache**: Cache de 60 segundos para resultados de consultas
+
+## Validação de Valores
+
+O sistema implementa validação rigorosa para garantir valores apropriados:
+
+- **Conversão Explícita**: Todos os valores de configuração são explicitamente convertidos para números (parseInt)
+- **Valores Mínimos**: Cada parâmetro tem um valor mínimo aplicado automaticamente
+  - poolMin: no mínimo 1
+  - poolMax: no mínimo poolMin + 1
+  - timeouts: no mínimo 1000ms
+- **Validação de Relações**: O sistema garante que poolMax seja sempre maior que poolMin
+- **Arredondamento**: Valores convertidos de milissegundos para segundos são arredondados (Math.floor)
+
+Estas validações previnem erros comuns como:
+- "NJS-007: invalid value for poolMax"
+- Timeouts negativos ou muito baixos
+- Problemas de conversão entre strings e números
+
+## Boas Práticas
+
+### Dimensionamento do Pool
+
+O dimensionamento do pool de conexões depende da carga esperada:
+
+1. **Fórmula Básica**: `connections = ((core_count * 2) + effective_spindle_count)`
+2. **Ambiente Web**: Considere o número máximo de requisições concorrentes
+3. **Regra 80-20**: O pool deve ser dimensionado para acomodar 80% da carga de pico
+
+### Monitoramento
+
+Para garantir o funcionamento adequado do pool, monitore:
+
+- **Taxa de uso do pool**: Número de conexões ativas vs. total
+- **Tempo de espera por conexão**: Tempo médio para obter uma conexão
+- **Erros de timeout**: Número de falhas por timeout
+- **Conexões mortas**: Conexões que falharam mas não foram removidas do pool
+
+### Ajuste Fino
+
+Para ambientes de produção, considere os seguintes ajustes:
+
+1. **Tamanho do pool**: Ajuste baseado no número de requisições concorrentes
+2. **Tempo de idle**: Reduza em ambientes com muitos usuários esporádicos
+3. **Tempo de timeout**: Aumente em caso de operações mais longas
+4. **Statement cache**: Aumente para aplicações com queries repetitivas
+
+## Implementação no TypeORM
+
+A configuração foi implementada nos arquivos:
+
+- `src/core/configs/typeorm.oracle.config.ts`
+- `src/core/configs/typeorm.postgres.config.ts`
+
+Estas configurações são carregadas no início da aplicação e aplicadas a todas as conexões.
+
+## Resolução de Problemas
+
+### Erros Comuns
+
+| Erro | Causa Provável | Solução |
+|------|----------------|---------|
+| `NJS-007: invalid value for poolMax` | Valor não numérico para poolMax | Agora resolvido com conversão explícita para número |
+| `Connection timeout` | Tempo insuficiente para conectar | Aumente POSTGRES_POOL_CONNECTION_TIMEOUT |
+| `All connections in use` | Pool muito pequeno para a carga | Aumente ORACLE_POOL_MAX/POSTGRES_POOL_MAX |
+| `Error acquiring client` | Problema na criação de conexões | Verifique credenciais e disponibilidade do banco |
+
+### Melhores Práticas para Diagnóstico
+
+1. **Use o endpoint de health check**: Verifique estatísticas do pool em `/health/pool`
+2. **Analise logs**: Procure por padrões de erro relacionados a conexões
+3. **Monitore performance**: Observe tempos de resposta e correlacione com o uso do pool