“Errore nello stabilire una connessione al database”: le 4 cause che si vedono davvero

Apri il sito e trovi una pagina bianca con una frase sola. Niente logo, niente menu, niente da cliccare. Provi a entrare in bacheca e trovi la stessa frase.

Questa guida serve a capire da dove arriva quell'errore, in che ordine controllare le cose e cosa dire al tuo hosting. Alla fine saprai riconoscere le quattro cause che si vedono davvero, e in quale schermata guardare per ognuna.

In una frase: il messaggio non dice che il database è rotto, dice che WordPress non riesce ad aprire la connessione. Nella pratica succede quasi sempre per quattro motivi — e sono quelli di questa guida; le cause rare arrivano più avanti. O le credenziali in wp-config.php non corrispondono, o il server del database non risponde, o una tabella è danneggiata, o qualcosa è cambiato sotto WordPress.

Cosa significa davvero quel messaggio?

Il testo completo è più utile di quanto sembri. Questa è la versione standard, come la riporta un utente nel forum italiano ufficiale:

«Errore nello stabilire una connessione al database. Ciò significa che le informazioni sul nome utente o sulla password presenti nel file wp-config.php non sono corrette o che non è possibile contattare il server del database. Il database server del fornitore di hosting potrebbe essere non attivo».

Forum WordPress.org Italia, topic «[SOLVED] errore nello stabilire una connessione al database»

Vale la pena sapere come è fatta la catena. Il browser chiede la pagina, PHP la costruisce e per farlo si presenta al server del database con i dati scritti nel file di configurazione. Il server apre il database e PHP legge le tabelle. Se un passaggio non riesce, WordPress si ferma e mostra sempre la stessa frase. Quattro problemi diversi, un solo messaggio.

Prima di toccare qualsiasi cosa: il backup

Due delle quattro cause si sistemano modificando dati. Se la modifica non va come previsto, senza una copia non si torna indietro.

Il primo passo è quindi scaricare il database. Da phpMyAdmin si usa la scheda Esporta, scegliendo il formato SQL. Se phpMyAdmin non si apre — cosa probabile proprio quando il database non risponde — le alternative sono due: il Backup del pannello di hosting (molti fornitori fanno copie automatiche: controlla che l'ultima sia recente) oppure la riga di comando via SSH con mysqldump, che funziona anche quando l'interfaccia web è bloccata. Su molti pannelli esiste anche una voce Backup dentro la scheda del database. Se il tuo hosting fa copie automatiche, controlla che l'ultima sia recente e che il ripristino sia già stato provato: il metodo completo è in questa guida.

Causa 1 — Le credenziali in wp-config.php non corrispondono

È la causa più frequente e la più facile da controllare. WordPress tiene i dati di accesso al database in un file di testo nella cartella principale dell'installazione: wp-config.php. Quattro righe contano davvero.

RigaCosa contieneDove la trovi nel pannello dell'hostingDB_NAMEil nome del databasesezione Database MySQL, accanto al nome del databaseDB_USERl'utente autorizzato su quel databasestessa sezione, riga «Utente»DB_PASSWORDla password di quell'utentestessa sezione, spesso da rigenerareDB_HOSTl'indirizzo del server del databasestessa sezione, riga «Host»: a volte localhost, a volte un indirizzo IP

Un dettaglio che sfugge: nei pannelli di hosting l'utente va associato al database, con i suoi privilegi. Puoi avere la password giusta e l'utente esistente, ma se non è associato a quel database la connessione viene rifiutata lo stesso — e l'errore è identico.

Per aprire il file si usa il gestore file del pannello di hosting, oppure un client FTP. Cerca wp-config.php nella cartella in cui hai installato WordPress, non dentro wp-content. Si legge e si modifica con un editor di testo semplice. Se non hai mai visto questo file, la scheda del database e i file dell'installazione sono descritti qui.

Il caso classico: l'indirizzo del server è cambiato

Su molti hosting condivisi il database non sta sulla stessa macchina dei file. In quel caso DB_HOST contiene un indirizzo IP al posto di localhost. Se il fornitore sposta il database, quell'indirizzo cambia. WordPress continua a bussare alla porta vecchia.

Nel forum italiano c'è un caso risolto che descrive esattamente questo. Elisa aggiorna la versione di MySQL dal pannello di Aruba e da quel momento il sito mostra l'errore. Dopo il ticket riporta la risposta del fornitore: «A seguito dell'aggiornamento di versione del database, non aveva ancora provveduto ad aggiornare il file di configurazione di WordPress con il nuovo indirizzo IP del server Mysql».

La spiegazione di Gianluca Molina chiarisce cosa era successo: «Quello che hanno chiamato "aggiornamento" de facto si è trattato di uno "spostamento": per quello hanno dovuto cambiare l'IP». Dove database e file stanno sullo stesso server, invece, il file non contiene un indirizzo ma la parola localhost.

Gli altri due casi: la password e i dati sbagliati

La password si rompe più spesso di quanto si creda. Nel forum, davanti a un utente convinto che le credenziali fossero giuste, la risposta di tizz è secca: «Dal fatto che le credenziali non sono corrette (o le hai copia-incollate con un editor di testo che aggiunge formattazione)». Virgolette tipografiche, uno spazio finale, un ritorno a capo invisibile: basta uno di questi.

Il terzo caso è il più insidioso: i dati sono corretti, ma sono quelli dell'installazione sbagliata. Nel forum c'è un caso di errore comparso subito dopo una clonazione. Se hai copiato il sito da un altro spazio, o hai cambiato dominio, è il primo posto da guardare.

Come si capisce se è questa la causa?

• Apri phpMyAdmin e prova a entrare con lo stesso utente e la stessa password scritti nel file. Se entra, le credenziali funzionano e il problema sta nel file. Su molti hosting però non c'è una schermata dove digitarle — si entra in phpMyAdmin per Single Sign-On con l'utente dell'hosting: in quel caso il test non si può fare e si va per esclusione.
• Confronta il valore di DB_HOST con quello scritto nella scheda del database.
• Riscrivi la password a mano invece di incollarla, e controlla che non ci siano spazi prima o dopo il valore.

Causa 2 — Il database non risponde

Qui le credenziali sono giuste, ma dall'altra parte non c'è nessuno che risponde. Le situazioni che si vedono nella pratica sono due.

Il database è scaduto o sospeso?

Alcuni hosting vendono il database come servizio a parte, con una data di scadenza. Nel forum, davanti a un caso identico, la prima risposta — di Gianluca Molina — è stata: «Controlla la schermata relativa al MySQL, guarda la data di scadenza!». Nel pannello di hosting il database ha una scheda con una data. Se è passata, il database è sospeso: si rinnova e il sito torna.

Il server è in sovraccarico?

Il sintomo è riconoscibile: il sito a volte funziona e a volte no, senza che tu abbia cambiato niente. Un utente lo descrive così: «Riscontro un errore [nell'originale: «unnerrore»] di connessione al DB pur essendo il config correttamente impostato. L'errore appare in modo alternato, a volte tutto funziona, a volte no». Poi aggiunge il dettaglio che spiega tutto: «Ha iniziato a presentarsi inizialmente con diversi accessi al sito simultanei: più di dieci andava in errore».

Un errore alternato è quasi sempre un problema di risorse, non di credenziali. Sui piani condivisi esiste un numero massimo di connessioni contemporanee al database: quando lo si supera, le richieste in eccesso cadono. Nello stesso thread un utente propone la controprova: un file PHP caricato via FTP che si collega al database con gli stessi parametri del sito. Se quel file si collega mentre il sito dà errore, il collo di bottiglia è altrove.

Causa 3 — Le tabelle del database sono danneggiate

Attenzione: questo guasto non produce il messaggio di questo articolo. Quando una tabella è danneggiata la connessione riesce: il sito si rompe in un altro modo — un avviso sulle tabelle non disponibili, o una pagina bianca. Se stai leggendo perché vedi «Errore nello stabilire una connessione al database», questo non è il tuo caso. La sezione resta qui perché è il guasto con cui si confonde più spesso.

Il database risponde, le credenziali sono giuste, eppure il sito non si apre. Oppure si aprono solo alcune pagine: la home funziona e un articolo no. È il segno che una tabella è danneggiata. In genere succede dopo una scrittura interrotta: un aggiornamento fermato a metà, un riavvio del server, un disco pieno.

Quando è questa la causa, l'errore nei log è più esplicito del messaggio a schermo: «Table ... is marked as crashed and should be repaired», oppure «Errore 145». I log li trovi nella sezione del pannello di hosting, oppure attivando la modalità di debug di WordPress come descritto nella documentazione ufficiale.

Come si riparano le tabelle danneggiate?

WordPress ha una modalità di riparazione che si attiva da sola. Si aggiunge a wp-config.php questa riga, si apre l'indirizzo tuosito.it/wp-admin/maint/repair.php e la pagina offre due pulsanti: Ripara database e Ripara e ottimizza.

define( 'WP_ALLOW_REPAIR', true );

La documentazione ufficiale avverte di due cose. La riga va attivata solo se serve e rimossa appena il problema è risolto. E finché è attiva, la pagina di riparazione è raggiungibile da chiunque, senza login. Quindi: si aggiunge, si ripara, si toglie. E chi la lascia attiva non rischia solo l'accesso: chiunque può premere anche l'ottimizzazione, che blocca le tabelle mentre gira.

Ma la riparazione non funziona su tutte le tabelle. Il comando che WordPress esegue lì dentro, REPAIR TABLE, copre solo i formati Archive, Aria, CSV e MyISAM. InnoDB — il motore che WordPress usa oggi — non lo supporta: su un'installazione recente quel pulsante può non fare niente. Quando succede, la strada è un'altra: ripristinare un backup (ecco perché si scarica prima), oppure far intervenire l'hosting con i modi di recupero di InnoDB (innodb_force_recovery): è una configurazione lato server, non una voce di pannello. Se serve, si apre un ticket spiegando che il database non risponde e che la riparazione standard non ha prodotto effetti.

È la strada che nel forum italiano ha risolto il caso di un sito su Aruba che dava l'errore dopo l'aggiornamento di PHP. MrTux — Emilio Petrozzi spiega: «Di solito per risolvere questo problema di connessione con il database MySql quando si fa l'upgrade di PHP è necessario inserire questa stringa in wp-config.php». E avverte: «Ovviamente dopo aver fatto un backup, in quanto se non va a buon fine si rischia di perdere i dati».

L'alternativa, senza toccare wp-config.php, è riparare da phpMyAdmin: si selezionano le tabelle e nel menu a tendina si sceglie Ripara. La documentazione di WordPress consiglia questa strada anche a chi non è pratico, e suggerisce di chiedere al fornitore di eseguire un controllo sul database.

Causa 4 — È cambiato qualcosa sotto WordPress

Tutte le verifiche precedenti passano: credenziali giuste, server che risponde, tabelle sane. Il problema è comparso dopo un'operazione fatta a monte. Tre le più frequenti.

Hai aggiornato la versione di PHP?

Quando si cambia versione di PHP dal pannello di hosting, cambia anche l'insieme di estensioni attive sul server. WordPress ha bisogno di quelle estensioni per parlare con MySQL. Se mancano, la connessione non parte anche con le credenziali perfette. La pagina dei requisiti ufficiali elenca cosa deve offrire un hosting: PHP 8.3 o superiore, MariaDB 10.11 o MySQL 8.0, HTTPS. WordPress funziona anche su PHP 7.4 e MySQL 5.5.5, ma sono versioni a fine vita.

Come si verifica: cerca nel pannello di hosting la voce con le estensioni PHP attive, oppure chiedi al supporto quali sono abilitate sull'account. Se hai appena cambiato versione e prima funzionava tutto, è il primo sospetto.

Hai spostato o clonato il sito?

Se il problema è nato subito dopo la migrazione, la causa più probabile è la **1: le credenziali rimaste quelle vecchie. Qui sotto c'è il caso opposto.

Un sito migrato porta con sé il vecchio wp-config.php, e quindi il vecchio nome del database, il vecchio utente e il vecchio indirizzo del server. È la stessa famiglia di problemi della causa 1, ma la soluzione cambia: qui non c'è niente da riparare, vanno messi i dati nuovi. La procedura completa è nella guida su come migrare WordPress a un nuovo hosting.

Stai lavorando in locale?

Su XAMPP, MAMP o Local il database non è un servizio dell'hosting: è un programma che deve essere acceso. Se MySQL non è in esecuzione, WordPress non lo trova e mostra lo stesso errore. Un utente lo racconta nel forum, con il testo esatto: «mysqli::real_connect(): (HY000/2002): Impossibile stabilire la connessione. Rifiuto persistente del computer di destinazione». Quel «rifiuto persistente» significa una cosa sola: sulla porta non c'è nessuno in ascolto. Si apre il pannello di XAMPP o MAMP e si avvia MySQL.

Un secondo caso locale è la porta occupata: se MySQL è su una porta diversa, DB_HOST deve dirlo, e diventa per esempio 127.0.0.1:3306. Va scritto l'indirizzo 127.0.0.1 e non localhost: su Unix quest'ultimo fa tentare la connessione attraverso il socket, e la porta viene ignorata. E la porta di MySQL è la 3306, non una porta da server web..

Le cause rare, e come escluderle

Se le quattro cause precedenti non spiegano il problema, restano le situazioni poco frequenti. La documentazione ufficiale mette nell'elenco anche il sito compromesso. Un accesso non autorizzato può cancellare o alterare le tabelle, e il risultato a schermo è lo stesso. Il controllo suggerito è una scansione esterna, per esempio con Sucuri SiteCheck. Se il sito risulta compromesso si procede come in una pulizia da malware, non come in un problema di database.

Le altre due ipotesi rare sono il disco pieno e i limiti di risorse dell'account. Nel thread del forum italiano da cui viene il caso dell'errore alternato, le cause vengono riassunte così: credenziali sbagliate nel file di configurazione, server MySQL spento o sovraccarico, tabelle corrotte, conflitto tra plugin o tema, limiti di memoria o CPU superati. Nello stesso thread c'è una verifica in più: disattivare i plugin per capire se uno di loro sovraccarica il server.

La riparazione in 4 passi, nel giusto ordine

1. Scarica il database da phpMyAdmin prima di modificare qualsiasi cosa.
2. Confronta le quattro righe di wp-config.php con la scheda del database nel pannello di hosting.
3. Se le credenziali tornano, apri phpMyAdmin e prova la riparazione delle tabelle.
4. Se nemmeno così si risolve, apri un ticket all'hosting con l'errore esatto e le prove già raccolte.

Nel ticket servono quattro informazioni. Il messaggio esatto, l'ora in cui il sito ha smesso di funzionare, cosa hai già controllato, e se phpMyAdmin riesce ad aprire il database. Quest'ultimo dettaglio fa risparmiare un giro di email, perché distingue subito un problema di credenziali da un problema del server.

Che cosa non fare in questi casi?

• Non cancellare il database per rifare l'installazione: il messaggio non significa che i dati sono persi.
• Non cambiare la password dell'utente del database prima di aver capito cosa non funziona.
• Non rinominare o spostare le tabelle a mano da phpMyAdmin.
• Non incollare le credenziali del database in un forum, in una chat o in un assistente automatico.

In sintesi

L'errore di connessione al database non è un guasto del sito: è WordPress che non riesce ad aprire la porta giusta. Prima si controlla se la porta è quella giusta, cioè le quattro righe di wp-config.php contro il pannello di hosting. Poi si verifica se dall'altra parte qualcuno risponde. Poi si controlla lo stato delle tabelle con la riparazione. Solo alla fine si chiama l'hosting, con i dati raccolti nei passaggi precedenti. Con un backup fatto prima di iniziare, ogni tentativo è reversibile.

Domande frequenti

Se dopo la riparazione il sito è di nuovo online ma più lento di prima, il passo successivo è capire quale collo di bottiglia di hosting è rimasto.