«Errore nello stabilire una connessione al database»: la lista dei controlli

Il sito mostra «Error establishing a database connection» (o, in italiano, «Errore nello stabilire una connessione al database»): significa solo che l'applicazione (WordPress o altro CMS) non riesce a parlare con il server MySQL/MariaDB, per un motivo che può essere nel database, nel file di configurazione o nel server stesso. Non dice quale dei tre.

Il test più veloce: è il database o è il sito?

Prima di aprire wp-config.php, si prova la connessione da terminale, fuori dall'applicazione. Su Ubuntu 24.04 con Nginx e PHP-FPM:

mysqladmin ping -h 127.0.0.1 -u utente -p

Se il comando risponde che il server è attivo, il database funziona: il problema è nelle credenziali o nella configurazione dell'app. Se il comando si blocca o restituisce un errore di connessione, il problema è a monte: il servizio è fermo, ha esaurito le connessioni o ha un problema di disco. Su cPanel e Plesk lo stesso comando funziona identico via SSH, perché sotto c'è sempre MySQL o MariaDB.

1. Credenziali cambiate o sbagliate nel file di configurazione

È la causa più frequente, soprattutto dopo una migrazione o un ripristino da backup. Si verifica provando a entrare con le stesse credenziali scritte nel file dell'app:

mysql -u utente -p -h host nome_database

Se risponde "Access denied for user", le credenziali o i permessi non coincidono. Si controlla il file di configurazione (su WordPress, wp-config.php, definizioni DB_NAME, DB_USER, DB_PASSWORD, DB_HOST) e i permessi reali dell'utente sul database con SHOW GRANTS FOR 'utente'@'host';. Su cPanel l'utente del database ha di solito il prefisso dell'account cPanel; su Plesk l'utente va verificato in Database → utente del database dal pannello.

2. Il servizio del database è fermo

Su Ubuntu 24.04:

sudo systemctl status mysql

(o mariadb se è installata MariaDB). Se risulta "inactive" o "failed", si prova il riavvio con sudo systemctl start mysql e si legge subito dopo il motivo del mancato avvio nel log degli errori. Il percorso di default sui pacchetti Ubuntu/Debian è /var/log/mysql/error.log, impostato tramite la direttiva log_error nel file di configurazione: è la stessa convenzione che è comune per le installazioni Yum o APT configurare una posizione del file di log degli errori sotto /var/log con un'opzione come log-error=/var/log/mysqld.log in un file di configurazione del server, e viene confermata nelle installazioni reali Ubuntu/MariaDB dove il valore effettivo di log_error risulta proprio /var/log/mysql/error.log. Su cPanel si riavvia con /scripts/restartsrv_mysql; su Plesk da Strumenti e impostazioni → Gestione servizi.

3. Connessioni esaurite

Se nel log compare un errore di troppe connessioni attive, si confronta il numero di connessioni in uso con il limite:

SHOW STATUS LIKE 'Threads_connected';
SHOW VARIABLES LIKE 'max_connections';

Se il primo valore è vicino o uguale al secondo, le nuove connessioni vengono rifiutate. Si individuano le connessioni bloccate con SHOW PROCESSLIST; e si chiudono quelle inutili con KILL id;. Per sbloccare subito senza riavviare: SET GLOBAL max_connections = 300; (va poi reso permanente nel file di configurazione, altrimenti si perde al riavvio).

4. Tabelle danneggiate

Sintomo tipico nel log: una tabella segnalata come corrotta. Si controlla con il tool ufficiale:

mysqlcheck -u root -p --all-databases

Per riparare, sempre da riga di comando: mysqlcheck --repair fornisce accesso da riga di comando all'istruzione REPAIR TABLE, usando --databases o --all-databases per riparare tutte le tabelle di uno o più database. Attenzione però al motore: il metodo REPAIR TABLE è applicabile solo alle tabelle MyISAM, ARCHIVE e CSV. Le tabelle InnoDB (le più comuni su installazioni recenti) non si riparano così: se CHECK TABLE segnala un guasto InnoDB, bisogna ricorrere all'opzione innodb_force_recovery per far ripartire il server, come indicato dalla documentazione ufficiale.

Quando riparare e quando ripristinare il backup: si ripara se mysqlcheck segnala "OK" dopo l'operazione o recupera i dati senza perdite evidenti. Si ripristina invece da backup quando la riparazione riporta righe perse o danneggiate, quando il motore è InnoDB e nemmeno innodb_force_recovery fa ripartire il server in modo stabile, o quando il disco che ospitava i dati ha dato segni di guasto fisico: in quel caso insistere con la riparazione rischia di sovrascrivere l'ultima copia buona.

5. Spazio disco esaurito

Si controlla con:

df -h

Se la partizione che contiene /var/lib/mysql è piena, il database si blocca e spesso si ferma da solo per evitare danni peggiori. Si libera spazio (log vecchi, binlog con PURGE BINARY LOGS BEFORE, backup locali superflui) e si riavvia il servizio.

6. Host sbagliato: localhost contro socket

Su molte configurazioni, scrivere "localhost" come host fa usare il socket Unix (di norma /var/run/mysqld/mysqld.sock su Ubuntu), mentre "127.0.0.1" forza una connessione TCP. Se l'applicazione è configurata per l'uno e il server risponde solo sull'altro, la connessione fallisce. Si prova con entrambi:

mysql -h 127.0.0.1 -u utente -p
mysql -h localhost -u utente -p

Se solo uno dei due funziona, si allinea l'host nel file di configurazione dell'app, oppure si corregge il percorso del socket nelle direttive pdo_mysql.default_socket e mysqli.default_socket di php.ini.

Se il problema è del fornitore

Se tutti i controlli sopra risultano puliti e il database resta irraggiungibile, il problema può essere del provider (manutenzione, disco pieno lato host, blocco di rete). In questo caso conviene aprire un ticket allegando: l'orario esatto in cui è comparso l'errore, l'output del comando mysqladmin ping lanciato da riga di comando, e l'identificativo del server o del piano di hosting.

Verifica finale

Il problema è risolto quando mysqladmin ping risponde positivamente, il sito carica la home senza errori, e il log degli errori non mostra nuove righe nei minuti successivi (sudo tail -f /var/log/mysql/error.log).