ASE/BUGFIX_pool_pre_ping.md

Bug Fix: pool_pre_ping Parameter Error

Data: 2025-10-11 Severity: HIGH (blocca l'avvio) Status: ✅ RISOLTO

🐛 Problema

Durante il testing del graceful shutdown, l'applicazione falliva all'avvio con errore:

run_orchestrator.ERROR: Errore principale: connect() got an unexpected keyword argument 'pool_pre_ping'

🔍 Causa Root

Il parametro pool_pre_ping=True era stato aggiunto alla configurazione del pool aiomysql, ma questo parametro non è supportato da aiomysql.

Questo parametro esiste in SQLAlchemy per verificare le connessioni prima dell'uso, ma aiomysql usa un meccanismo diverso.

✅ Soluzione

File: src/utils/orchestrator_utils.py

PRIMA (non funzionante):

pool = await aiomysql.create_pool(
    host=cfg.dbhost,
    user=cfg.dbuser,
    password=cfg.dbpass,
    db=cfg.dbname,
    minsize=cfg.max_threads,
    maxsize=cfg.max_threads * 4,
    pool_recycle=3600,
    pool_pre_ping=True,  # ❌ ERRORE: non supportato da aiomysql
)

DOPO (corretto):

pool = await aiomysql.create_pool(
    host=cfg.dbhost,
    user=cfg.dbuser,
    password=cfg.dbpass,
    db=cfg.dbname,
    minsize=cfg.max_threads,
    maxsize=cfg.max_threads * 4,
    pool_recycle=3600,
    # Note: aiomysql doesn't support pool_pre_ping like SQLAlchemy
    # Connection validity is checked via pool_recycle
)

📝 Parametri aiomysql.create_pool Supportati

Ecco i parametri corretti per aiomysql.create_pool:

Parametro	Tipo	Default	Descrizione
host	str	'localhost'	Hostname database
port	int	3306	Porta database
user	str	None	Username
password	str	None	Password
db	str	None	Nome database
minsize	int	1	Numero minimo connessioni nel pool
maxsize	int	10	Numero massimo connessioni nel pool
pool_recycle	int	-1	Secondi prima di riciclare connessioni (-1 = mai)
echo	bool	False	Log delle query SQL
charset	str	''	Character set
connect_timeout	int	None	Timeout connessione in secondi
autocommit	bool	False	Autocommit mode

Non supportati (sono di SQLAlchemy):

• ❌ pool_pre_ping
• ❌ pool_size
• ❌ max_overflow

🔧 Come aiomysql Gestisce Connessioni Stale

aiomysql non ha pool_pre_ping, ma gestisce le connessioni stale tramite:

1. pool_recycle=3600: Ricicla automaticamente connessioni dopo 1 ora (3600 secondi)

   • Previene timeout MySQL (default: 28800 secondi / 8 ore)
   • Previene connessioni stale

2. Exception Handling: Se una connessione è morta, aiomysql la rimuove dal pool automaticamente quando si verifica un errore

3. Lazy Connection: Le connessioni sono create on-demand, non tutte all'avvio

📚 Documentazione Aggiornata

File Aggiornati:

1. ✅ orchestrator_utils.py - Rimosso parametro errato
2. ✅ GRACEFUL_SHUTDOWN.md - Corretta documentazione pool
3. ✅ SECURITY_FIXES.md - Corretta checklist

🧪 Verifica

# Test sintassi
python3 -m py_compile src/utils/orchestrator_utils.py

# Test avvio
python src/send_orchestrator.py
# Dovrebbe avviarsi senza errori

💡 Best Practice per aiomysql

Configurazione Raccomandata

pool = await aiomysql.create_pool(
    host=cfg.dbhost,
    user=cfg.dbuser,
    password=cfg.dbpass,
    db=cfg.dbname,
    minsize=cfg.max_threads,           # 1 connessione per worker
    maxsize=cfg.max_threads * 2,       # Max 2x workers (non 4x)
    pool_recycle=3600,                 # Ricicla ogni ora
    connect_timeout=10,                # Timeout connessione 10s
    charset='utf8mb4',                 # UTF-8 completo
    autocommit=False,                  # Transazioni esplicite
)

Perché maxsize = 2x invece di 4x?

• Ogni worker usa 1 connessione alla volta
• maxsize eccessivo spreca risorse
• Con 4 worker: minsize=4, maxsize=8 è più che sufficiente

🔗 Riferimenti

• aiomysql Documentation
• PyMySQL Connection Arguments
• SQLAlchemy Engine Configuration (per confronto)

---

✅ Checklist Risoluzione

• ✅ Rimosso pool_pre_ping=True da orchestrator_utils.py
• ✅ Aggiunto commento esplicativo
• ✅ Aggiornata documentazione GRACEFUL_SHUTDOWN.md
• ✅ Aggiornata documentazione SECURITY_FIXES.md
• ✅ Verificata sintassi Python
• ⚠️ Test funzionale da completare

---

Grazie per la segnalazione del bug! 🙏

Questo tipo di feedback durante il testing è preziosissimo per individuare problemi prima del deploy in produzione.