portalweb-api/db-connection-pool.md

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