L’erreur de connexion à la base de données WordPress (message officiel : « Error Establishing a Database Connection ») s’affiche quand WordPress ne parvient pas à joindre MySQL. La cause est presque toujours l’une de ces cinq : identifiants incorrects dans wp-config.php, serveur MySQL arrêté, tables corrompues, migration ratée, ou saturation des connexions chez l’hébergeur. Solution directe : ouvrez wp-config.php via FTP, vérifiez DB_HOST, DB_NAME, DB_USER et DB_PASSWORD, redémarrez MySQL si vous avez la main, puis lancez wp db check en WP-CLI. Ce guide couvre chaque scénario, localhost, Docker et migration inclus.

Qu’est-ce que l’erreur de connexion à la base de données WordPress ?

WordPress stocke tout son contenu (articles, pages, réglages, utilisateurs) dans une base de données MySQL ou MariaDB. À chaque chargement de page, PHP ouvre une connexion à cette base. Si cette connexion échoue, WordPress affiche le message « Error Establishing a Database Connection » sur la page publique, et une variante légèrement différente sur /wp-admin/ : « One or more database tables are unavailable. The database may need to be repaired. »

Ce message peut apparaître sur le frontend uniquement, sur le backend uniquement, ou sur les deux. Cette distinction oriente directement le diagnostic :

  • Erreur sur le frontend et le backend : problème de credentials ou serveur MySQL indisponible.
  • Erreur sur le backend seulement, frontend OK : tables corrompues (mode réparation à activer).
  • Erreur intermittente : saturation du nombre de connexions simultanées (max_connections atteint).

Selon les données de WordPress.org, cette erreur figure parmi les trois problèmes les plus signalés sur les forums d’assistance, toutes versions confondues.

Les 5 causes les plus fréquentes

Avant de plonger dans chaque solution, voici les causes classées par fréquence d’occurrence réelle :

  1. Identifiants wp-config.php incorrects : après une migration ou un changement de mot de passe MySQL, DB_PASSWORD ou DB_USER ne correspond plus à la base réelle.
  2. Serveur MySQL arrêté : redémarrage du VPS, mise à jour système, surcharge CPU. MySQL s’arrête et PHP ne peut plus s’y connecter.
  3. Tables corrompues : crash serveur brutal, panne d’électricité, bug de plugin pendant une écriture en base. Les tables InnoDB peuvent se retrouver dans un état incohérent.
  4. Mauvais DB_HOST : chez certains hébergeurs mutualisés (o2switch, OVH), l’hôte n’est pas localhost mais un socket Unix ou une IP privée spécifique. Après migration, cette valeur est souvent copiée telle quelle depuis l’ancien serveur.
  5. Saturation des connexions : un site à fort trafic avec des plugins mal codés peut ouvrir des centaines de connexions simultanées, épuisant le pool MySQL.

Vérifier et corriger wp-config.php en premier

C’est le point de départ systématique. Connectez-vous en FTP ou via le gestionnaire de fichiers cPanel et ouvrez wp-config.php à la racine de votre installation.

<?php
// Verifier ces quatre constantes
define( 'DB_NAME',     'nom_de_la_base' );  // Nom exact dans phpMyAdmin
define( 'DB_USER',     'utilisateur_sql' ); // Utilisateur MySQL
define( 'DB_PASSWORD', 'mot_de_passe' );    // Mot de passe MySQL
define( 'DB_HOST',     'localhost' );       // localhost ou IP privee selon hebergeur

Pour valider rapidement que ces identifiants fonctionnent indépendamment de WordPress, créez un fichier test-db.php temporaire à la racine :

<?php
$link = mysqli_connect(
    'localhost',      // DB_HOST
    'utilisateur_sql', // DB_USER
    'mot_de_passe',   // DB_PASSWORD
    'nom_de_la_base'  // DB_NAME
);
if ( ! $link ) {
    die( 'Connexion impossible : ' . mysqli_connect_error() );
}
echo 'Connexion MySQL OK. Version : ' . mysqli_get_server_info( $link );
mysqli_close( $link );

Appellez ce fichier via votre navigateur (https://monsite.com/test-db.php). Si vous obtenez « Connexion MySQL OK », le problème est ailleurs (tables corrompues, plugin, etc.). Si mysqli_connect_error() retourne un message, vous avez trouvé la cause. Supprimez ce fichier immédiatement après le test : il expose vos credentials en clair. Pour aller plus loin sur la sécurisation de votre configuration WordPress, consultez notre guide sur la sécurité WordPress (WAF, headers CSP).

Redémarrer MySQL et vérifier son statut

Si vous avez accès SSH à votre serveur (VPS, serveur dédié), vérifiez d’abord que MySQL tourne :

# Sur systemes systemd (Ubuntu 20+, Debian 11+)
sudo systemctl status mysql

# Si arrete, redemarrer
sudo systemctl restart mysql

# Sur cPanel/WHM, verifier via le gestionnaire de services
# ou utiliser la commande :
sudo /scripts/restartsrv_mysql

Si MySQL redémarre mais retombe rapidement, inspectez les logs :

# Logs MySQL systemd
sudo journalctl -u mysql -n 100

# Log erreur MySQL classique
sudo tail -100 /var/log/mysql/error.log

Les causes fréquentes d’un MySQL qui ne démarre pas : espace disque épuisé (df -h pour vérifier), corruption du répertoire de données (/var/lib/mysql/), ou paramètre innodb_buffer_pool_size trop élevé pour la RAM disponible.

Sur hébergement mutualisé (o2switch, OVH Perso/Pro), vous n’avez pas accès SSH à MySQL. Ouvrez un ticket support : le service MySQL est géré côté hébergeur.

Réparer les tables MySQL corrompues

Si WordPress affiche l’erreur uniquement sur le backend (l’url /wp-admin/) mais pas sur le frontend, des tables sont probablement corrompues. WordPress propose un outil intégré : ajoutez la ligne suivante dans wp-config.php juste avant la ligne /* C'est tout, ne touchez pas à ce qui suit ! */ :

define( 'WP_ALLOW_REPAIR', true );

Puis accédez à https://monsite.com/wp-admin/maint/repair.php. WordPress propose deux options : réparer uniquement, ou réparer et optimiser. Choisissez « Repair and Optimize Database ». Une fois terminé, supprimez obligatoirement la ligne WP_ALLOW_REPAIR de wp-config.php (cette URL est accessible sans authentification).

En WP-CLI, la commande équivalente est plus complète :

# Verifier l'etat de toutes les tables
wp db check

# Reparer les tables endommagees
wp db repair

# Optimiser la base pour liberer l'espace fragmente
wp db optimize

Si wp db repair échoue sur certaines tables InnoDB, passez par phpMyAdmin : sélectionnez la table défaillante, onglet « Opérations », puis « Réparer la table ».

Résoudre l’erreur de connexion après une migration WordPress

La migration est la situation la plus classique. Quand vous déplacez un site d’un serveur vers un autre (ou d’un hébergeur vers un autre), deux informations changent quasi systématiquement : le nom de la base de données et le mot de passe MySQL. Le fichier wp-config.php copié depuis l’ancien serveur conserve les anciennes valeurs.

Procédure de correction après migration :

  1. Connectez-vous à cPanel du nouvel hébergeur, ouvrez « Bases de données MySQL ».
  2. Notez le nom exact de la base créée (souvent sous la forme cpaneluser_nombase).
  3. Vérifiez l’utilisateur MySQL assigné à cette base et son mot de passe.
  4. Ouvrez wp-config.php et mettez à jour DB_NAME, DB_USER, DB_PASSWORD.
  5. Vérifiez DB_HOST : sur o2switch et OVH Perso, localhost fonctionne. Sur certains hébergeurs Cloud, l’hôte est une IP privée (ex. 127.0.0.1 ou db.monhebergeur.internal) indiquée dans la documentation ou le panneau de contrôle.

Un cas particulier : si vous avez migré avec un plugin comme Duplicator ou All-in-One WP Migration et que l’erreur persiste après correction de wp-config.php, vérifiez que la table wp_options contient bien les bonnes valeurs siteurl et home :

SELECT option_name, option_value
FROM wp_options
WHERE option_name IN ('siteurl', 'home')
LIMIT 2;

Si ces URLs pointent toujours vers l’ancien domaine, corrigez-les directement dans phpMyAdmin ou via WP-CLI :

wp option update siteurl 'https://nouveau-domaine.com'
wp option update home 'https://nouveau-domaine.com'

Pour une migration propre, notre générateur .htaccess WordPress permet de préparer les règles de redirection avant le transfert.

Erreur de connexion avec Docker ou WP-CLI en local

En environnement de développement local (Docker Compose, XAMPP, Local by Flywheel), l’erreur de connexion est souvent liée à un DB_HOST mal configuré. Dans Docker Compose, les conteneurs ne se joignent pas via localhost : ils s’atteignent via le nom du service défini dans docker-compose.yml.

# docker-compose.yml exemple
services:
  wordpress:
    image: wordpress:latest
    environment:
      WORDPRESS_DB_HOST: db          # <- nom du service, PAS localhost
      WORDPRESS_DB_USER: wpuser
      WORDPRESS_DB_PASSWORD: wppass
      WORDPRESS_DB_NAME: wpdb
  db:
    image: mysql:8.0
    environment:
      MYSQL_DATABASE: wpdb
      MYSQL_USER: wpuser
      MYSQL_PASSWORD: wppass
      MYSQL_ROOT_PASSWORD: rootpass

Si vous avez copié un wp-config.php de production dans votre conteneur, changez DB_HOST en db (ou le nom de votre service MySQL). Relancez ensuite les conteneurs avec docker compose down && docker compose up -d.

En cas d’erreur persistante même avec le bon host, vérifiez que le conteneur MySQL est bien démarré :

# Verifier les conteneurs actifs
docker compose ps

# Voir les logs du conteneur db
docker compose logs db

# Tester la connexion MySQL depuis le conteneur wordpress
docker compose exec wordpress bash -c 
  "php -r "mysqli_connect('db','wpuser','wppass','wpdb') or die(mysqli_connect_error());" && echo OK"

Erreur de connexion en wp-admin uniquement : boucle et tableau de bord inaccessible

Quand le frontend affiche le site normalement mais que /wp-admin/ retourne l’erreur de base de données, le problème vient presque toujours des tables de sessions ou d’un plugin d’administration. Voici le diagnostic en trois étapes :

Étape 1 : activer le mode réparation. Comme décrit dans la section précédente, ajoutez WP_ALLOW_REPAIR dans wp-config.php et accédez à /wp-admin/maint/repair.php.

Étape 2 : désactiver tous les plugins. Renommez le dossier wp-content/plugins/ en wp-content/plugins-disabled/ via FTP. Si wp-admin redevient accessible, réactivez les plugins un par un pour identifier le fautif. Cette méthode est identique au diagnostic d’une erreur critique WordPress sur votre site.

Étape 3 : vérifier les connexions simultanées. Sur un site à fort trafic, la table wp_options peut être verrouillée par des opérations concurrentes (transients, révisions automatiques). Solution rapide via WP-CLI :

# Supprimer les transients expires qui saturent wp_options
wp transient delete --expired

# Nettoyer les auto-drafts et les revisisions (libere des verrous)
wp post delete $(wp post list --post_type=revision --format=ids) --force 2>/dev/null
wp post delete $(wp post list --post_status=auto-draft --format=ids) --force 2>/dev/null

Pour aller plus loin sur le cache et les performances, notre guide vider le cache WordPress sans plugin couvre les différentes couches de mise en cache qui peuvent aggraver ce type d’erreur.

Quand contacter votre hébergeur

Certaines situations dépassent ce que vous pouvez régler seul. Ouvrez un ticket support dans ces cas :

  • MySQL est arrêté et vous n’avez pas d’accès SSH (hébergement mutualisé).
  • Le log MySQL indique InnoDB: Database page corruption : une restauration depuis une sauvegarde propre est souvent nécessaire.
  • L’erreur est intermittente et disparaît seule : saturation du max_connections côté hébergeur, qui doit augmenter le quota ou optimiser la configuration MySQL.
  • Le quota de stockage est épuisé : MySQL ne peut plus écrire ses fichiers de journal, ce qui provoque des crashes aléatoires.

Avant d’appeler le support, notez : le nom de la base (DB_NAME), l’heure exacte du premier incident, et si l’erreur est reproductible ou intermittente. Ces informations réduisent de moitié le temps de résolution.

À titre indicatif, selon les données de WordPress Developer Resources, plus de 60 % des erreurs de connexion à la base de données sur les hébergements partagés proviennent d’identifiants incorrects après une migration ou un changement de mot de passe MySQL imposé par l’hébergeur.

Prévenir l’erreur : bonnes pratiques

Une fois l’erreur résolue, quelques mesures réduisent le risque de récidive :

  • Sauvegardes automatiques : configurez une sauvegarde quotidienne de la base de données via cPanel (Sauvegardes > Sauvegarde de base de données) ou via un script WP-CLI planifié en cron.
  • Monitoring de disponibilité : un outil comme UptimeRobot (plan gratuit) vous alerte en moins de 5 minutes si votre site tombe, avant vos visiteurs.
  • Limiter le nombre de révisions : ajoutez define( 'WP_POST_REVISIONS', 5 ); dans wp-config.php pour éviter la croissance incontrôlée de la table wp_posts, qui peut provoquer des timeouts MySQL sur les sites anciens.
  • Utiliser des connexions persistantes avec parcimonie : define( 'DB_HOST', 'localhost:p' ); (connexions persistantes PHP) peut améliorer les performances mais augmente le risque de saturation du pool MySQL. Évitez sur mutualisé.
# Exemple de sauvegarde BDD quotidienne via WP-CLI + cron
# Ajouter dans le crontab de l'hebergeur
0 3 * * * /usr/local/bin/wp db export /home/user/backups/backup-$(date +%Y%m%d).sql --path=/home/user/public_html/ --allow-root

Foire aux questions

Pourquoi l’erreur de connexion à la base de données apparaît soudainement sans que j’aie rien changé ?

Les causes les plus probables sans intervention récente sont : un serveur MySQL redémarré automatiquement après une mise à jour système de l’hébergeur, une saturation temporaire du nombre de connexions simultanées à fort trafic, ou un quota d’espace disque atteint qui empêche MySQL d’écrire ses fichiers de journal. Vérifiez le statut de MySQL et l’espace disque disponible en premier.

L’erreur de connexion à la base de données apparaît uniquement sur wp-admin, que faire ?

Quand le frontend fonctionne mais pas le backend, le problème est généralement une table corrompue (souvent wp_options ou wp_usermeta). Activez WP_ALLOW_REPAIR dans wp-config.php, accédez à /wp-admin/maint/repair.php, lancez la réparation, puis supprimez la constante. Si le problème persiste, désactivez les plugins en renommant le dossier plugins/ via FTP.

Comment trouver le bon DB_HOST pour mon hébergeur ?

Sur la majorité des hébergements mutualisés français (o2switch, OVH Perso/Pro, PlanetHoster), DB_HOST doit être localhost. Sur les hébergements Cloud ou VPS avec base de données séparée (AWS RDS, Azure Database, PlanetScale), l’hôte est une URL ou IP fournie dans le panneau de gestion. Sur Docker Compose, l’hôte est le nom du service MySQL défini dans docker-compose.yml. En cas de doute, créez un ticket support : c’est l’information la plus rapide à obtenir.

Peut-on corriger l’erreur de connexion sans accès FTP ni wp-admin ?

Oui, via le gestionnaire de fichiers intégré à cPanel ou Plesk, qui permet d’éditer wp-config.php directement depuis le navigateur. Alternativement, si vous avez SSH, WP-CLI permet de vérifier et corriger la configuration (wp config get DB_HOST, wp config set DB_HOST nouvelle-valeur) sans accès FTP ni wp-admin.

L’erreur revient régulièrement, même après réparation. Quelle est la cause ?

Des erreurs récurrentes signalent presque toujours un problème structurel : quota d’espace disque trop juste (MySQL crash dès que le disque est plein), mémoire RAM insuffisante qui fait crasher MySQL sous charge, ou un plugin mal codé qui ouvre et ne ferme pas ses connexions à la base de données (identifiable en activant le log de requêtes MySQL lentes via slow_query_log). Analysez le log d’erreurs MySQL entre deux incidents pour identifier le pattern.

Sources :

G
WP Admin Lab

Architecte web full-stack. WordPress, performance, data et sécurité. Notes de terrain, tests reproductibles et retours d'expérience.