Errore nello stabilire una connessione al database in WordPress: cosa significa

Che cosa dice il messaggio

Per ogni pagina che serve, WordPress apre una connessione al suo database MySQL o MariaDB con quattro valori scritti in wp-config.php, nella cartella principale del sito:

define( 'DB_NAME', 'nome_database' );
define( 'DB_USER', 'nome_utente' );
define( 'DB_PASSWORD', 'password' );
define( 'DB_HOST', 'localhost' );

«Errore nello stabilire una connessione al database» significa che questa connessione non è riuscita. Quattro cause lo provocano: credenziali che non corrispondono più, un server di database fermo o irraggiungibile, un server sovraccarico, oppure un database danneggiato. Le sezioni che seguono le passano in rassegna dalla più semplice da verificare alla più rara.

1. Il server del database risponde?

• La pagina di stato del provider: un guasto o una manutenzione del server MySQL vi vengono annunciati.
• Gli altri siti dello stesso account: se mostrano lo stesso errore nello stesso momento, la causa è lato server, e la soluzione spetta al provider.
• phpMyAdmin, dal pannello di hosting: se apre il database e ne mostra le tabelle, il server funziona e il database esiste.

Se il problema è del server, aprite un ticket presso il provider, indicando l'ora di inizio del guasto e il messaggio esatto. Nel frattempo non c'è nulla da modificare sul sito.

2. Le credenziali di wp-config.php sono giuste?

È la causa più frequente dopo un trasferimento del sito, un cambio della password del database nel pannello di hosting o il ripristino di un backup. Confrontate i quattro valori di wp-config.php con la sezione dei database del pannello di hosting:

• DB_NAME e DB_USER: molti provider li fanno precedere dal nome dell'account (account_wordpress). Il prefisso fa parte del nome.
• DB_PASSWORD: nel dubbio, impostate una nuova password per l'utente nel pannello e copiatela nel file.
• DB_HOST: localhost presso molti provider, non tutti. Alcuni indicano un nome di server o un indirizzo, a volte seguito da una porta (:3306). Il valore esatto è nel pannello.
• L'utente deve avere i permessi sul database: nel pannello, verificate che l'utente sia associato al database, con tutti i privilegi.

Una password che contiene un apice singolo (') tronca la stringa PHP che la racchiude in wp-config.php. Fatelo precedere da una barra rovesciata (\'), oppure scegliete una password senza apice singolo.

Testare le credenziali fuori da WordPress

WordPress mostra un messaggio generico. MySQL, invece, dice esattamente che cosa non va. Due modi per chiederglielo, con i valori di wp-config.php:

Da riga di comando, se avete un accesso SSH

mysql -h localhost -u nome_utente -p nome_database

Con WP-CLI, wp db check legge direttamente wp-config.php e controlla le tabelle con quelle credenziali.

Con un file PHP temporaneo

Caricate questo file nella cartella principale del sito con un nome difficile da indovinare, apritelo nel browser, poi eliminatelo subito: contiene la password del database.

<?php
mysqli_report(MYSQLI_REPORT_OFF);
$link = @mysqli_connect('localhost', 'nome_utente', 'password', 'nome_database');
echo $link ? 'Connessione riuscita' : 'Errore: ' . mysqli_connect_error();

La prima riga conta: da PHP 8.1, una connessione che non riesce solleva un'eccezione per impostazione predefinita, e la pagina resterebbe bianca invece di mostrare il messaggio di MySQL.

3. Un database danneggiato: lo strumento di riparazione

Quando le credenziali sono giuste ma alcune tabelle sono danneggiate, il sito pubblico mostra lo stesso errore di connessione, e la bacheca un messaggio più preciso: «Una o più tabelle del database non sono disponibili. Il database potrebbe avere bisogno di essere riparato.» WordPress fornisce uno strumento apposito. Aggiungete questa riga a wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Poi aprite https://www.vostro-sito.com/wp-admin/maint/repair.php e avviate «Riparazione database». Togliete la riga appena terminata la riparazione: finché è presente, quella pagina è raggiungibile da chiunque, senza accesso.

Prima di qualsiasi riparazione, esportate il database (wp db export, oppure la scheda Esporta di phpMyAdmin). Se la riparazione non riesce, il provider può ripristinare il database dai suoi backup.

4. Un errore che va e viene: il carico

Un errore che compare in certi momenti e poi scompare da solo indica un server sovraccarico più che un'impostazione sbagliata. Le cause abituali:

• Un picco di traffico, spesso di bot: tentativi di accesso ripetuti su wp-login.php o xmlrpc.php, visibili nei log di accesso del provider.
• I limiti dell'hosting condiviso: connessioni o processi simultanei limitati per account. I pannelli di hosting li mostrano di solito nella sezione sul consumo di risorse.
• Un plugin pesante: statistiche, registri o operazioni pianificate che scrivono nel database a ogni visita.

Le soluzioni: bloccare i tentativi di accesso abusivi, aggiungere una cache delle pagine, disattivare xmlrpc.php se nessuna applicazione lo usa, e chiedere al provider i log dell'ora dell'errore.