Connection Pooling - C-Suite

Visão Geral

Este documento descreve o sistema de connection pooling padronizado para o ecossistema C-Suite. O objetivo é garantir uso eficiente de conexões de banco de dados em todos os apps.

Módulo de Connection Pooling

Localização

O módulo principal está em: common_db_pool.py (raiz do projeto)

Características

Pool configurável: Tamanho do pool, overflow, timeout
Pool pre-ping: Verifica conexões antes de usar
Pool recycle: Recicla conexões antigas automaticamente
Cache de engines: Reutiliza engines entre chamadas
Múltiplos bancos: Suporte a csuite, core, staging
Estatísticas: Monitoramento de uso do pool

Uso Básico

1. Obter Engine com Pool

from common_db_pool import get_db_engine

# Engine para banco csuite
engine = get_db_engine("csuite")

# Engine para banco core
core_engine = get_db_engine("core")

2. Obter Session

from common_db_pool import get_db_session

# Session para banco csuite
session = get_db_session("csuite")

# Usar session
result = session.execute("SELECT * FROM organizations LIMIT 1")
session.close()

3. Scoped Session (Thread-Safe)

from common_db_pool import get_scoped_session

# Scoped session (recomendado para apps multi-threaded)
Session = get_scoped_session("csuite")

# Usar session
session = Session()
try:
    result = session.execute("SELECT * FROM organizations LIMIT 1")
finally:
    Session.remove()  # Importante: remove session do contexto

4. Integração com FastAPI

from fastapi import Depends
from common_db_pool import get_db_session
from sqlalchemy.orm import Session

def get_db():
    """Dependency para FastAPI"""
    session = get_db_session("csuite")
    try:
        yield session
    finally:
        session.close()

@app.get("/api/organizations")
async def list_organizations(db: Session = Depends(get_db)):
    return db.query(Organization).all()

Configuração

Variáveis de Ambiente

# Pool para banco csuite
CSUITE_POOL_SIZE=5              # Tamanho do pool
CSUITE_POOL_MAX_OVERFLOW=10     # Máximo de conexões extras
CSUITE_POOL_TIMEOUT=30          # Timeout em segundos
CSUITE_POOL_RECYCLE=3600        # Reciclar conexões após 1 hora
CSUITE_POOL_PRE_PING=true       # Verificar conexão antes de usar
CSUITE_POOL_ECHO=false          # Log SQL (apenas desenvolvimento)

# Pool para banco core
CORE_POOL_SIZE=10
CORE_POOL_MAX_OVERFLOW=20
CORE_POOL_TIMEOUT=30
CORE_POOL_RECYCLE=3600
CORE_POOL_PRE_PING=true

Configuração por Banco

from common_db_pool import PoolConfig, get_db_engine

# Configuração customizada
pool_config = PoolConfig(
    pool_size=10,
    max_overflow=20,
    pool_timeout=30,
    pool_recycle=3600,
    pool_pre_ping=True
)

engine = get_db_engine("csuite", pool_config=pool_config)

Parâmetros do Pool

pool_size

Número de conexões mantidas no pool.

Padrão: 5
Recomendado: 5-20 dependendo da carga
Muito alto: Consome muitos recursos
Muito baixo: Pode causar espera por conexões

max_overflow

Número máximo de conexões extras além do pool_size.

Padrão: 10
Recomendado: 2x pool_size
Total máximo: pool_size + max_overflow

pool_timeout

Tempo máximo (segundos) para esperar por uma conexão disponível.

Padrão: 30
Recomendado: 30-60
Muito alto: Pode causar timeouts longos
Muito baixo: Pode falhar quando há pico de carga

pool_recycle

Tempo (segundos) após o qual conexões são recicladas.

Padrão: 3600 (1 hora)
Recomendado: 3600-7200
Evita: Conexões "mortas" do MySQL

pool_pre_ping

Verifica se conexão está viva antes de usar.

Padrão: True
Recomendado: Sempre True em produção
Evita: Erros de conexão perdida

Estatísticas do Pool

from common_db_pool import get_pool_stats

# Obter estatísticas
stats = get_pool_stats("csuite")

print(f"Pool size: {stats['pool_size']}")
print(f"Checked out: {stats['checked_out']}")
print(f"Overflow: {stats['overflow']}")
print(f"Checked in: {stats['checked_in']}")

Integração com Apps

csuite-executive

from common_db_pool import get_db_engine, get_scoped_session
from sqlalchemy.orm import Session

# Criar engine uma vez
engine = get_db_engine("csuite")

# Scoped session para FastAPI
SessionLocal = get_scoped_session("csuite")

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        SessionLocal.remove()

4c Decision API

from common_db_pool import get_db_engine

# Engine para banco core
core_engine = get_db_engine("core", pool_config=PoolConfig(
    pool_size=10,
    max_overflow=20
))

4c-suite

from common_db_pool import get_db_engine

# Engines para múltiplos bancos
csuite_engine = get_db_engine("csuite")
core_engine = get_db_engine("core")

Boas Práticas

Use pool_size apropriado:
Apps leves: 5-10
Apps médios: 10-20
Apps pesados: 20-50
Sempre use pool_pre_ping: Evita erros de conexão perdida
Configure pool_recycle: Recicla conexões antigas
Monitore estatísticas: Use get_pool_stats() para monitorar
Feche sessions: Sempre feche sessions após uso
Use scoped_session: Para apps multi-threaded
Não crie múltiplos engines: Reutilize engines do cache

Troubleshooting

Erro: "QueuePool limit of size X overflow Y reached"

Causa: Pool esgotado, muitas conexões em uso

Solução:
1. Aumente pool_size ou max_overflow
2. Verifique se sessions estão sendo fechadas
3. Verifique se há conexões vazando

Erro: "Lost connection to MySQL server"

Causa: Conexão foi fechada pelo servidor

Solução:
1. Configure pool_pre_ping=True
2. Configure pool_recycle apropriado
3. Verifique timeout do MySQL

Performance ruim

Causa: Pool muito pequeno ou muito grande

Solução:
1. Monitore estatísticas do pool
2. Ajuste pool_size baseado em uso
3. Verifique se há espera por conexões

Monitoramento

Health Check com Pool Stats

from common_db_pool import get_pool_stats
from fastapi import APIRouter

router = APIRouter()

@router.get("/health/pool")
async def pool_health():
    stats = get_pool_stats("csuite")

    # Verifica se pool está saudável
    pool_usage = stats['checked_out'] / stats['pool_size']

    if pool_usage > 0.9:
        return {"status": "degraded", "pool_usage": pool_usage, **stats}

    return {"status": "healthy", **stats}

Próximos Passos

✅ Módulo de connection pooling criado
⏳ Migrar apps existentes para usar common_db_pool
⏳ Configurar pools apropriados por app
⏳ Adicionar monitoramento de pools
⏳ Documentar configurações recomendadas por app