Errore 'Database connection error': diagnosi

Quando WordPress non riesce a connettersi al database mostra la celebre pagina 'Error establishing a database connection'. Le cause possono essere multiple: credenziali sbagliate, server MySQL down, max_connections raggiunto, problema di rete. WP Error Monitor ti aiuta a distinguere il vero colpevole.

Cosa succede dietro le quinte

WordPress in fase di bootstrap chiama new wpdb($user,$pass,$db,$host). Se mysqli_real_connect fallisce, viene chiamato dead_db() che mostra la pagina di errore senza esporre dettagli all’utente. WP Error Monitor cattura comunque l’evento perchè l’agent si registra prima di wp-db e logga il vero errore MySQL (codice + messaggio): es. 1045 (Access denied), 2002 (Can't connect), 2003 (Connection refused), 1040 (Too many connections).

Cause più frequenti

1) Cambio password DB lato hosting non riflesso in wp-config.php, 2) MySQL server down/restart in corso, 3) max_connections raggiunto (tipico su shared hosting), 4) wait_timeout MySQL troppo basso che chiude connessioni persistenti, 5) firewall che blocca la porta 3306, 6) DB corrotto che richiede REPAIR TABLE, 7) disk full che impedisce write su MySQL data dir.

Strategia di diagnosi rapida

Da SSH lancia: mysql -h$host -u$user -p$pass $db -e 'SELECT 1'. Se fallisce con Access denied → credenziali. Se fallisce con Can't connect → server down o firewall. Se ritorna OK ma WP non si connette → probabile plugin che corrompe wpdb (raro). WP Error Monitor mostra anche la latenza di connessione: >500ms indica problema di rete o server sovraccarico.

HyperDB e replica master/slave

Per siti con traffico alto, una singola istanza MySQL è bottleneck. HyperDB (plugin ufficiale Automattic) permette di configurare master per write e multiple slave per read. WordPress automaticamente smista le query: SELECT vanno su slave, INSERT/UPDATE su master. WP Error Monitor monitora entrambi i pool: se uno slave va in errore, vedi quale specifico. Setup tipico per ecommerce: 1 master + 2-3 slave su LAN gigabit. Replicazione MySQL deve essere row-based per WordPress.

Connection pooling con ProxySQL

ProxySQL è un middleware tra applicazione e MySQL: gestisce connection pooling, failover, read/write split senza modifiche codice. Per WordPress su carichi alti, ProxySQL riduce il numero di connessioni reali a MySQL del 70-90%. Configurazione: WordPress punta a localhost:6033 (ProxySQL), che a sua volta gestisce un pool verso i MySQL reali. WP Error Monitor traccia anche le metriche ProxySQL via stats schema se accessibile.

Health check endpoint per DB

Implementa endpoint /health-check che verifica connettività DB e ritorna 200/503. WordPress non ha questo built-in, ma plugin tipo 'Site Health' lo offrono. Per setup custom: mu-plugin che hook 'init' su URL /healthz, esegue 'SELECT 1' e ritorna stato. Setup load balancer/CDN per usare questo endpoint come probe. Se 503, il load balancer non manda traffico al sito (failover ad altra istanza). WP Error Monitor monitora questo endpoint con synthetic monitoring ogni 60 secondi e alerta se 3 fail consecutivi. Così' incident DB sono rilevati prima che gli utenti vedano errore.

Backup automatici DB con verification

I backup DB sono critici: senza, una corruption è game over. Setup ideale G Tech: 1) backup completo nightly via mysqldump o Percona XtraBackup, 2) backup incrementale ogni 6 ore via binary log, 3) snapshot disk daily (Plesk), 4) replica streaming a server backup geografico. Retention: 30gg backup full, 90gg snapshot, 7gg binary log. Verification: ogni notte un job restora last backup in DB di test e lancia query checksum. WP Error Monitor riceve evento se restore fallisce o checksum diverge. RTO target post-corruption: 30 minuti.

Strategia di monitoraggio DB completa

Per un monitoraggio DB completo che vada oltre i singoli errori, configura un layer dedicato: 1) Percona Monitoring (PMM) o equivalente per metriche MySQL (connessioni, query rate, replica lag, buffer pool), 2) WP Error Monitor per errori applicativi WordPress che coinvolgono DB, 3) Alert su throughput query/sec anomalo, 4) Alert su slow_query_log che cresce velocemente, 5) Backup verification giornaliera. L’integrazione tra strumenti permette di correlare anomalie infrastrutturali con effetti sull’applicazione WordPress, riducendo drasticamente il tempo di root cause analysis.

Procedura passo-passo

1. Apri WP Error Monitor e cerca eventi 'severity ALERT' o 'message contains database connection'.
2. Annota il codice errore MySQL nell’evento.
3. Verifica via SSH la raggiungibilità del DB con mysqladmin ping.
4. Controlla wp-config.php: DB_HOST, DB_USER, DB_PASSWORD, DB_NAME.
5. Se Access denied, rigenera credenziali dal pannello hosting e aggiorna wp-config.php.
6. Se Too many connections, monitora processi MySQL con SHOW PROCESSLIST e killa quelli pendenti.
7. Se Can't connect, verifica che mysqld sia attivo (systemctl status mariadb).
8. Una volta ripristinato, esegui REPAIR TABLE su tabelle wp_options/wp_posts per sicurezza.
9. Per traffico alto, valuta HyperDB per read replica.
10. Considera ProxySQL come middleware connection pool.

Errori comuni e come risolverli

• Errore solo su staging: wp-config.php di staging punta ancora al DB di prod (o viceversa): verifica le credenziali.
• Errore sporadico ogni ora: Cron pesante che apre troppe connessioni: profila con SHOW PROCESSLIST durante l’evento.
• Errore dopo cambio hosting: MySQL versione diversa (es. 5.7 → 8.0) con autenticazione caching_sha2_password: aggiorna driver mysqli o forza mysql_native_password.
• Slave lag alto: Replica lenta: verifica binlog format, network, IOPS storage slave.
• ProxySQL routing sbagliato: Verifica mysql_query_rules: SELECT devono andare a hostgroup slave.

Domande frequenti

D: Posso ricevere alert immediato su questo errore?
R: Sì, è tra i pattern critici di default che attivano notifica istantanea su Slack/email.

D: WP Error Monitor riesce a inviare l’evento anche con DB down?
R: Sì, l’agent salva localmente in /tmp e ritrasmette quando la connessione è ripristinata.

D: Posso usare un DB di failover?
R: Sì, con plugin tipo HyperDB e configurazione master/slave; WP Error Monitor monitora entrambi.

D: HyperDB è difficile da configurare?
R: Medium: serve familiarità con MySQL replication.

D: ProxySQL funziona con MariaDB?
R: Sì, compatibile sia MySQL che MariaDB.

Hai bisogno di aiuto?

Se vuoi affidare il monitoraggio WordPress al team di G Tech Group, scrivici tramite il modulo di contatto.