WordPress : sortir de la boucle « Database Update Required »

Comprendre pourquoi les fichiers à jour ne suffisent pas

WordPress annonce que ses fichiers ont été mis à jour, puis affiche « Database Update Required » ou une demande de mise à jour de la base de données. Après validation, le même écran revient. Il arrive aussi que le bouton conduise à une erreur critique avant de revenir au début. Le problème n’est donc pas nécessairement le téléchargement des fichiers.

Le cœur compare la révision de base attendue par ses fichiers avec celle enregistrée pour le site. La mise à niveau adapte les tables et certaines données lorsque c’est nécessaire. Ce numéro de révision n’est pas le numéro public de WordPress : deux versions publiques peuvent partager un même état de schéma.

Le résultat recherché est une installation cohérente : les bons fichiers utilisent la bonne base, la procédure nécessaire s’achève et les fonctions normales restent accessibles. Masquer l’écran ou changer un numéro pour satisfaire la comparaison ne réalise pas cette mise à niveau. Si une erreur interrompt l’opération, il faut d’abord relever cette erreur plutôt que répéter indéfiniment le bouton.

Identifier le message du cœur et le bon environnement

Ce guide vise le message du cœur WordPress sur une installation auto-hébergée. Une extension peut proposer sa propre mise à jour de données : le nom du produit, l’écran et sa procédure sont alors différents. Ne lancez pas une mise à niveau du cœur pour traiter automatiquement toute notification comportant le mot « base ».

Relevez l’adresse de l’écran, le titre exact et ce qui se passe après une seule tentative déjà effectuée. Un écran de maintenance, un verrou indiquant qu’une autre mise à jour est en cours, un refus de connexion MySQL ou une erreur critique persistante relèvent de diagnostics distincts, même s’ils surviennent pendant la même intervention.

1. Confirmez le domaine, le protocole HTTPS et le site concerné avant de vous connecter.
2. Notez la version WordPress visée et le moyen utilisé pour remplacer ses fichiers.
3. Identifiez si le site appartient à un réseau multisite ou à un service qui gère les mises à jour à votre place.
4. Conservez l’heure de la tentative et le message final. Sur WordPress.com ou une plateforme gérée, utilisez le circuit de maintenance du service plutôt qu’une commande destinée à un autre environnement.

Préparer une sauvegarde qui permet un vrai retour arrière

La mise à niveau peut écrire dans la base. Avant une nouvelle tentative, préparez une sauvegarde de la base et des fichiers correspondant au même état, avec leur date et leur mode de restauration. Une archive contenant seulement les médias ne permet pas de retrouver les anciennes tables ; un export SQL seul ne conserve pas la version des extensions qui utilisera ces données.

Si les fichiers ont déjà été remplacés, préservez aussi la sauvegarde faite avant cette mise à jour. Un nouvel instantané de l’état bloqué est utile au diagnostic, mais il ne devient pas automatiquement une sauvegarde de fonctionnement. Vérifiez quels jeux de fichiers et de données peuvent être restaurés ensemble.

Choisissez un créneau de maintenance et évitez les écritures concurrentes pendant une restauration éventuelle. Pour une boutique ou un site recevant des demandes, préparez une mise en attente adaptée : une restauration ancienne peut perdre les opérations arrivées depuis. Sur une copie privée, neutralisez courriels, paiements et tâches externes. Enfin, faites confirmer le périmètre du cache d’objets par l’hébergeur avant l’exécution : une migration effective du cœur appelle son vidage. Sur une infrastructure partagée, le préfixe des clés ne suffit pas à garantir que ce vidage reste limité au site. Si cette portée n’est pas maîtrisée, faites préparer une copie isolée ou une intervention par le responsable du service.

Vérifier la cible avant de modifier la base

Une migration ou un déploiement incomplet peut faire utiliser des fichiers récents avec une ancienne base, ou une copie avec la base de production. Dans le panneau d’hébergement, relevez la racine du domaine. Consultez ensuite en privé la configuration active pour confirmer le nom de la base et le préfixe des tables, sans modifier ces valeurs pour essayer plusieurs cibles.

Si un outil de déploiement gère le site, comparez la livraison attendue à celle réellement installée sur tous les serveurs. Une requête arrivant sur un ancien serveur peut produire un résultat différent de la suivante. Le numéro indiqué par un seul fichier ne garantit pas que tout le cœur a été remplacé correctement.

Avec WP-CLI déjà disponible, le contrôle ci-dessous compare les fichiers du cœur aux empreintes officielles. Remplacez le chemin, VERSION_CIBLE et LOCALE par la version et la langue de la livraison vérifiée, par exemple la locale réellement utilisée et non celle du navigateur. Cette commande consulte WordPress.org ; un échec réseau n’établit pas une corruption. Elle ne répare pas les fichiers et ne contrôle pas vos contenus. Si des écarts sont confirmés, faites achever la livraison cohérente avant d’exécuter sa mise à niveau de base.

wp core verify-checksums --path="/chemin/vers/wordpress" --version=VERSION_CIBLE --locale=LOCALE

Achever la mise à niveau depuis l’écran natif

Cette voie convient au responsable disposant de l’accès de maintenance du site, lorsque les fichiers et la cible sont confirmés et que la sauvegarde est prête. Accédez au chemin wp-admin/upgrade.php de l’installation concernée, sans paramètre ajouté après le nom du fichier. Ne réutilisez pas une adresse contenant ?step=1 : cette étape déclenche la mise à niveau, au lieu d’afficher seulement la proposition. Si le cœur se trouve dans un sous-dossier, conservez ce chemin réel ; l’adresse de l’accueil peut être différente de celle des fichiers WordPress.

L’écran peut annoncer qu’aucune mise à jour n’est nécessaire. Dans ce cas, ne forcez rien : poursuivez vers la validation de l’administration et l’examen d’un affichage périmé. S’il demande la mise à jour, le bouton lance une opération d’écriture ; ce n’est pas un simple contrôle en lecture.

1. Ouvrez l’adresse de mise à niveau sur le domaine confirmé, dans un seul onglet de travail.
2. Si la demande est présente, cliquez une fois sur le bouton de mise à jour de la base WordPress.
3. Laissez la requête se terminer sans lancer une seconde opération dans un autre onglet.
4. En cas de confirmation, utilisez Continuer puis ouvrez directement l’administration.
5. Si une erreur, une page blanche ou un délai dépassé apparaît, notez l’heure et cessez les relances. Le journal et le contrôle de version doivent guider la suite.

Comparer les révisions avec WP-CLI

L’alternative en terminal convient si WP-CLI est déjà installé et si vous maîtrisez l’accès au bon environnement. Les trois commandes ci-dessous se lancent séparément, avec le même chemin réel. La première affiche des informations sur les fichiers, la deuxième lit l’option telle que WordPress la voit, éventuellement depuis le cache d’objets, et la troisième compare la valeur lue directement en base avec la révision attendue, sans exécuter la mise à niveau demandée.

Le mode --dry-run est une comparaison, pas une répétition complète de toutes les requêtes SQL futures. Son résultat ne prouve donc pas que les droits ou les ressources permettront la véritable opération. Les commandes qui chargent WordPress peuvent aussi charger les extensions et leur code ; utilisez une copie maîtrisée pour une investigation, et n’ajoutez pas de contournement global au premier message d’erreur.

Comparez la révision attendue dans les informations supplémentaires aux valeurs annoncées par les deux autres commandes. Si la lecture d’option et la comparaison directe divergent sur la même cible, faites examiner le cache d’objets. Si la comparaison directe ne prévoit aucune évolution mais que le navigateur boucle, vérifiez la cible web et les couches de cache avant toute écriture.

Si la révision stockée est supérieure à celle attendue par les fichiers, arrêtez-vous : une ancienne livraison peut avoir été remise sur une base déjà migrée. La commande de mise à niveau n’est pas une procédure de retour à un ancien schéma. Si la base est en retard, conservez les deux révisions et préparez l’exécution seulement lorsque la cible, les sauvegardes et la livraison sont confirmées.

wp core version --extra --path="/chemin/vers/wordpress"
wp option get db_version --path="/chemin/vers/wordpress"
wp core update-db --dry-run --path="/chemin/vers/wordpress"

Exécuter la procédure en terminal sur un site simple

Pour un site simple, la commande ci-dessous exécute la procédure de mise à niveau du cœur déjà présent. Elle ne télécharge pas une nouvelle version de WordPress et ne remplace pas une livraison incomplète. Remplacez le chemin d’exemple par celui que vous avez contrôlé et utilisez le compte technique prévu, sans mot de passe dans la commande.

Ne lancez pas simultanément cette opération avec le bouton du navigateur. Si un terminal se déconnecte, vérifiez l’état de l’opération et de la base avant de relancer. Un message de succès est un indice à conserver, mais il ne certifie pas chaque transformation SQL : WP-CLI peut masquer l’affichage des erreurs de base pendant cet appel. Le contrôle des journaux et des fonctions du site reste nécessaire, même si la révision finale paraît correcte.

1. Confirmez la disponibilité de la sauvegarde et le créneau de maintenance.
2. Lancez la commande une fois et conservez sa sortie dans un emplacement privé.
3. Relancez ensuite uniquement la comparaison --dry-run de la section précédente pour vérifier qu’aucune mise à niveau n’est annoncée.
4. Ouvrez l’administration dans le navigateur et effectuez les contrôles fonctionnels prévus.
5. Si l’écran revient ou qu’une erreur apparaît, passez au diagnostic ciblé sans modifier manuellement le numéro de révision.

wp core update-db --path="/chemin/vers/wordpress"

Lire l’erreur qui empêche l’opération de se terminer

Dans le panneau de l’hébergement, ouvrez le journal PHP ou le journal d’erreurs du domaine et recherchez l’heure précise de l’échec. Conservez quelques lignes autour du premier message significatif. Une erreur fatale citant un fichier d’extension, une limite mémoire et un refus SQL ne demandent pas la même correction.

Pour une erreur SQL, relevez l’opération refusée et le nom de la table en les expurgeant si nécessaire. La mise à niveau peut créer ou modifier des structures de tables : le fait de pouvoir publier un article ne prouve pas que le compte MySQL dispose des droits requis pour cette opération. Le responsable de base doit vérifier le privilège manquant sur la bonne base ; accorder tous les droits sur tout le serveur ne constitue pas une correction ciblée.

Si aucun journal n’est accessible, demandez celui du domaine et du créneau concernés. Un diagnostic WordPress temporaire peut être préparé par le mainteneur avec un journal privé, sans afficher les erreurs aux visiteurs, puis retiré après collecte. Ne rendez pas un fichier de journal publiquement téléchargeable. Corrigez la cause établie sur une copie avant une nouvelle tentative : désactiver toutes les extensions ou augmenter toutes les limites effacerait la précision du diagnostic.

Distinguer une lecture périmée d’une migration inachevée

Si le terminal considère la base à jour mais que l’écran web la réclame encore, vérifiez d’abord que les deux parcours utilisent le même chemin, la même configuration et la même base. Une commande exécutée sur la copie de validation ne décrit pas la production. Avec plusieurs serveurs, contrôlez également que tous utilisent les fichiers de la même livraison.

Le cache d’objets conserve des données utilisées par WordPress ; le cache de pages conserve une réponse HTML. Ce sont deux couches différentes. Une ancienne réponse de l’écran d’administration ne doit pas être servie comme une page publique, et une lecture de métadonnées périmée ne se corrige pas en supprimant les cookies de tous les visiteurs.

Faites comparer par le mainteneur la révision stockée dans la bonne base avec celle lue par le parcours web, puis vérifiez le périmètre du cache qui intervient réellement. Si une invalidation est nécessaire, utilisez le mécanisme documenté pour cette installation. N’exécutez pas une purge globale du service de cache sur une infrastructure partagée. Lorsque la migration est nécessaire, le cœur appelle lui-même le vidage du cache d’objets. En revanche, il peut retourner immédiatement si sa lecture directe de la base indique déjà la bonne révision : ce passage ne garantit alors aucun vidage. Faites donc corriger la lecture périmée avec le mécanisme prévu pour ce site, sans répéter la migration ni purger tout le service partagé.

Un autre cache conserve le code PHP compilé : OPcache. Après une livraison, si le processus web utilise encore un ancien code, le résultat du navigateur peut différer de celui du terminal. Demandez à l’hébergeur de vérifier la prise en compte des fichiers par le processus du domaine. Une invalidation ou un rechargement doit suivre sa procédure et son périmètre ; n’ajoutez pas un script public de remise à zéro.

Définir le périmètre avant une mise à niveau multisite

Un réseau partage des fichiers du cœur, mais chaque sous-site possède des données et une révision à prendre en compte. La version supplémentaire affichée par wp core version --extra décrit la révision attendue par les fichiers ; elle ne remplace pas la lecture de l’option propre à chaque sous-site.

L’option --network de wp core update-db étend l’opération aux sites du réseau. Ne l’ajoutez pas pour réparer plus vite le seul site dont vous voyez l’écran : son périmètre est plus large et demande une préparation correspondante. Dans une installation comportant plusieurs réseaux, le contexte d’URL doit également être défini selon la procédure du responsable.

Pour examiner un sous-site, le mainteneur peut utiliser wp option get db_version --url=https://sous-site.example --path="/chemin/vers/wordpress", en remplaçant l’adresse par sa vraie cible. Cette lecture ne met pas ses tables à niveau. Préparez ensuite un inventaire des sites concernés, une sauvegarde du réseau et une fenêtre adaptée avant toute exécution étendue. Conservez le bilan par site, car un résultat global ne dispense pas d’identifier un sous-site en échec.

Ne pas remplacer la migration par un numéro ou une réparation

Ne modifiez ni la valeur db_version en base ni la variable attendue dans wp-includes/version.php pour faire disparaître la demande. La comparaison pourrait alors sembler satisfaite sans que les transformations nécessaires aient eu lieu. Lors d’une intervention suivante, le diagnostic serait aussi brouillé par un état déclaré différent de l’état réel.

La réparation de tables et la mise à niveau du schéma ont des objectifs distincts. Une option de réparation ne remplace pas la procédure de migration du cœur. N’activez pas WP_ALLOW_REPAIR simplement parce que l’écran revient ; recherchez un message attestant une corruption avant de choisir un parcours de réparation adapté.

Une nouvelle extension ne résout pas directement cette étape préalable à l’administration. Installer un outil à ce moment peut être impossible et ajoute des fichiers sans corriger le schéma. Le cœur et WP-CLI fournissent les deux voies nécessaires ici. Les migrations propres à une extension restent ensuite à traiter selon sa documentation, une fois l’accès rétabli, avec une sauvegarde adaptée à leurs effets.

Valider la fin de l’intervention

L’absence de l’écran est nécessaire mais ne suffit pas. Revenez au même compte, au même domaine et aux mêmes fonctions que ceux utilisés avant la mise à jour. Les pages publiques peuvent encore s’afficher depuis un cache alors qu’une partie de l’administration échoue. Contrôlez donc les deux parcours.

Sur une copie, un enregistrement de contenu de test permet de vérifier une écriture sans créer une publication réelle. En production, utilisez une opération interne convenue avec le responsable et évitez de déclencher un paiement ou un courriel pour ce seul contrôle. La vérification doit porter sur les fonctions affectées, pas sur une série d’actions sans lien.

1. Rouvrez wp-admin/upgrade.php sans paramètres sur l’installation contrôlée et vérifiez qu’aucune évolution n’est demandée.
2. Confirmez, si WP-CLI est utilisé, que la comparaison ne prévoit plus de mise à niveau.
3. Ouvrez le tableau de bord, une liste de contenus, l’éditeur et les pages publiques importantes.
4. Relisez le journal sur ce créneau et vérifiez l’absence de nouvel échec SQL ou PHP lié à l’intervention.
5. Consignez les versions, la sauvegarde conservée et les résultats avant de lever la maintenance.

Restaurer un ensemble cohérent si la reprise échoue

Si la mise à niveau reste impossible après identification de la cause, préparez le retour au dernier état utilisable avec le responsable du site. Une simple copie d’anciens fichiers sur une base déjà modifiée n’est pas un retour arrière complet. Il faut déterminer quels fichiers et quel instantané de base appartiennent au même état et ce qui s’est produit depuis.

Avant la restauration, conservez un instantané privé de l’état courant et recensez les nouvelles écritures utiles : contenus, inscriptions ou commandes selon le site. Le choix entre restauration, correction et récupération de ces données doit être explicite. Ne réimportez pas une ancienne base sur la production en supposant que personne n’a travaillé pendant la panne.

Restaurez l’ensemble prévu selon la procédure de sauvegarde, contrôlez le domaine et les connexions puis reprenez les vérifications fonctionnelles. Consignez la cause de l’échec, le premier message d’erreur et la livraison concernée. Pour la prochaine tentative, validez la même évolution sur une copie représentative, vérifiez les privilèges nécessaires et prévoyez la fin de migration dans le déploiement. Cela évite de considérer le remplacement des fichiers comme la dernière étape alors que la base attend encore son évolution.