Comment corriger une clé primaire manquante dans la table WordPress wp_options

En résumé : L’absence de clé primaire sur la table wp_options signifie que MySQL cesse d’auto-incrémenter option_id, si bien que les nouvelles lignes sont écrites avec option_id = 0. WordPress continue de fonctionner, mais chaque export, migration ou déploiement de staging échoue avec une erreur de clé dupliquée, et les requêtes sur la table deviennent plus lentes parce que MySQL ne peut plus utiliser la clé. Le correctif le plus rapide : sauvegarder la base de données, renuméroter les valeurs option_id dupliquées pour que chacune soit unique, puis exécuter ALTER TABLE wp_options ADD PRIMARY KEY (option_id) et restaurer l’AUTO_INCREMENT. Tu peux faire toute la réparation dans phpMyAdmin ou en SQL brut, et aucun plugin n’est nécessaire.

Parfois, dans certaines circonstances, la table wp_options (ou n’importe quelle autre table) peut perdre son index de clé primaire. Le déclencheur exact est rarement évident. Dans les tickets de support WP STAGING, nous voyons ce problème le plus souvent sur des bases de données migrées manuellement d’un serveur à un autre, ou déplacées avec un outil qui ne tenait pas compte de tous les cas, comme un changement entre versions de MySQL ou entre les moteurs de stockage InnoDB et MyISAM.

Soyons clairs : WP STAGING n’est pas la cause de cette erreur. WP STAGING t’aide seulement à la détecter, en affichant un avertissement bien visible dans ton tableau de bord d’administration WordPress lorsqu’il trouve une table principale sans clé primaire. Nous la signalons tôt parce que c’est un problème critique et insidieux. Ton site continue de se charger comme si tout allait bien, donc tu ne le remarqueras pas tant qu’une migration ou une sauvegarde n’échouera pas, et à ce moment-là la table peut déjà contenir des centaines de lignes cassées. Plus le problème reste sans correction, plus les lignes dupliquées s’accumulent et plus la réparation devient laborieuse.

Ce qu’est une clé primaire et pourquoi wp_options en a besoin

Une clé primaire est une colonne (ou un ensemble de colonnes) qui identifie de manière unique chaque ligne d’une table. Dans une installation WordPress standard, la table wp_options utilise option_id comme clé primaire. option_id est défini comme bigint(20) unsigned NOT NULL auto_increment, ce qui signifie que la base de données attribue automatiquement à chaque nouvelle ligne le prochain numéro inutilisé et garantit que deux lignes ne partagent jamais la même valeur.

Deux choses se cassent quand cette clé disparaît :

• L’auto-incrémentation s’arrête. Sans la clé primaire, MySQL n’incrémente plus option_id. Chaque nouvelle ligne est insérée avec la valeur par défaut 0. L’exemple original ci-dessous montre à quoi ressemble une séquence saine :Et voici à quoi ressemble la même colonne une fois la clé disparue et que les nouvelles lignes s’accumulent avec option_id = 0 :
• Les exports et les migrations échouent. Une colonne de clé primaire doit contenir des valeurs uniques. À l’instant où tu exportes ces lignes et les importes dans une autre base de données, MySQL rejette les doublons avec une erreur du type Cannot insert duplicate key, et l’import s’arrête en cours de route. C’est pourquoi WP STAGING et tout autre plugin de migration ne peuvent pas terminer un transfert de base de données quand la clé est manquante. Le déploiement d’un site de staging vers la production échoue exactement à l’endroit où les lignes 0 dupliquées sont écrites.

Il y a aussi un coût plus discret. wp_options est l’une des tables les plus lues dans WordPress, car les options en autoload sont récupérées à presque chaque requête. Lors de nos tests, une clé primaire manquante force MySQL à se rabattre sur un balayage complet de la table pour des recherches qui utiliseraient sinon la clé, ce qui ajoute une surcharge mesurable au chargement ordinaire des pages. Si tu veux comprendre comment wp_options s’intègre dans le schéma plus large, consulte notre guide sur les tables essentielles de la base de données WordPress.

Comment confirmer que la clé primaire est réellement manquante

Avant de changer quoi que ce soit, confirme que c’est bien ton problème. Ouvre un outil de base de données comme phpMyAdmin ou Adminer, sélectionne ta base de données WordPress, et exécute :

SHOW CREATE TABLE wp_options;

Dans une table saine, la sortie contient une ligne comme PRIMARY KEY (option_id) et la colonne option_id est marquée AUTO_INCREMENT. Si les deux manquent, la clé a disparu. Tu peux aussi lister directement les index :

SHOW INDEX FROM wp_options;

Une table avec une clé intacte renvoie une ligne où Key_name vaut PRIMARY. Si cette ligne est absente, il n’y a pas de clé primaire.

Cette capture d’écran montre une table wp_options ordinaire avec une clé primaire définie sur la colonne option_id :

Cette deuxième capture d’écran montre la même table avec la clé primaire manquante :

Pour voir combien de lignes sont déjà touchées, compte les doublons :

SELECT option_id, COUNT(*) AS copies
FROM wp_options
GROUP BY option_id
HAVING copies > 1;

Tout groupe avec option_id = 0 et un décompte supérieur à un confirme les lignes cassées que tu dois renuméroter avant de pouvoir restaurer la clé.

Remplace partout wp_options par le vrai nom de ta table si ton installation utilise un préfixe de table personnalisé (par exemple wp_xyz_options).

Avant de commencer : sauvegarde la base de données

Chaque étape ci-dessous modifie directement la base de données, alors fais d’abord une sauvegarde complète et télécharge-la hors du serveur. Si quelque chose tourne mal, tu veux disposer d’une copie propre à restaurer. Une sauvegarde WP STAGING, un export phpMyAdmin ou un mysqldump conviennent tous. C’est aussi un bon moment pour faire le travail sur une copie de staging plutôt que sur la production : clone le site, répare la table là-bas, vérifie le résultat, et applique seulement ensuite le même correctif à la base de données en production.

Corriger la clé primaire manquante dans phpMyAdmin

Si tu préfères une interface graphique au SQL brut, phpMyAdmin gère toute la réparation depuis l’onglet Structure.

1. Ouvre phpMyAdmin ou Adminer et navigue vers la table wp_options.
2. Traite d’abord les ID dupliqués. Prends la plus grande valeur existante dans la colonne option_id et renuméroter chaque ligne 0 une par une pour que chaque valeur redevienne unique. Ce screencast montre la renumérotation :
3. Ouvre l’éditeur des index de la table :
4. Définis option_id comme clé primaire :
5. Si tu vois l’erreur Duplicate entry '0' for key 'PRIMARY', c’est que certains ID dupliqués sont encore dans la table :
6. Trouve les doublons restants et incrémente leurs valeurs pour qu’aucune ne se répète, puis ajoute de nouveau la clé primaire. Une fois l’opération réussie, réactive l’auto-incrémentation sur option_id pour que les futures lignes se numérotent correctement.

Corriger la clé primaire manquante avec SQL

La même réparation prend trois instructions si tu es à l’aise avec la console SQL. Exécute-les dans l’ordre sur ta base de données WordPress.

D’abord, donne à chaque ligne 0 cassée un nouveau numéro unique en continuant à partir de l’option_id maximum actuel :

SET @next := (SELECT MAX(option_id) FROM wp_options);
UPDATE wp_options
SET option_id = (@next := @next + 1)
WHERE option_id = 0;

Ensuite, ajoute la clé primaire maintenant que chaque valeur est unique :

ALTER TABLE wp_options ADD PRIMARY KEY (option_id);

Enfin, restaure l’auto-incrémentation pour que WordPress numérote de nouveau automatiquement les nouvelles options :

ALTER TABLE wp_options MODIFY option_id BIGINT(20) UNSIGNED NOT NULL AUTO_INCREMENT;

La syntaxe officielle de ces instructions est documentée dans le manuel MySQL sous ALTER TABLE. Pour la définition canonique des colonnes de wp_options, la description de la base de données WordPress liste les types de colonnes exacts attendus par le cœur de WordPress.

Vérifier le correctif

Confirme que la réparation a tenu avant de faire confiance à la table :

SHOW CREATE TABLE wp_options;

La sortie devrait maintenant inclure PRIMARY KEY (option_id) et afficher AUTO_INCREMENT sur la colonne option_id. Comme dernière vérification, insère et supprime une option jetable, ou enregistre simplement un réglage dans WordPress, et confirme que la nouvelle ligne reçoit un option_id unique et incrémenté plutôt qu’un nouveau 0.

Avec la clé remise en place, tu peux lancer la migration ou le déploiement de staging qui échouait auparavant. Malgré tout, fais une nouvelle sauvegarde avant le déploiement afin d’avoir un point de récupération qui inclut la table réparée.

Que faire si ALTER TABLE échoue

Le scénario nominal couvre la plupart des installations, mais quelques environnements demandent un traitement supplémentaire. Parcours ces points dans l’ordre :

• Duplicate entry '0' for key 'PRIMARY'. Tous les doublons n’ont pas été renumérotés. Relance la requête de comptage des doublons de la section diagnostic, renumérote les lignes restantes, puis ajoute de nouveau la clé. C’est la raison de loin la plus fréquente pour laquelle l’étape ALTER TABLE refuse de s’exécuter.
• Délai d’attente de verrou sur une grande table. ALTER TABLE réécrit la table et maintient un verrou pendant son exécution. Sur une grande table wp_options, ou sur un serveur de production chargé, l’instruction peut expirer. Effectue la réparation pendant les heures creuses, sur un clone de staging, ou utilise un outil de modification de schéma en ligne comme pt-online-schema-change si ton hébergeur le fournit.
• MyISAM au lieu d’InnoDB. Les étapes fonctionnent sur les deux moteurs, mais WordPress tourne le mieux sur InnoDB. Si SHOW CREATE TABLE wp_options indique ENGINE=MyISAM, envisage une conversion après la mise en place de la clé avec ALTER TABLE wp_options ENGINE=InnoDB. Fais d’abord une sauvegarde, car la conversion réécrit elle aussi la table.
• L’hébergement bloque les modifications de schéma. Certains hébergeurs managés restreignent les instructions DDL directes ou exécutent la base de données sous un utilisateur sans le privilège ALTER. Si l’instruction échoue avec une erreur de permissions, demande à ton hébergeur d’exécuter les trois instructions à ta place, ou de t’accorder le privilège temporairement.

Un ALTER TABLE qui échoue relève presque toujours de l’un de ces quatre cas. Un lecteur qui suit l’erreur SQL sous-jacente dans le journal du serveur peut la trouver remontée aussi dans la sortie de débogage de WordPress ; notre guide sur la manière de repérer un problème dans les tables de la base de données WordPress explique comment activer cette journalisation.

Pourquoi cela compte pour les migrations et les déploiements

Une clé primaire manquante est l’une des raisons les plus discrètes pour lesquelles un déplacement de site cale. Si un déploiement du staging vers le site live expire ou s’interrompt en cours de transfert, la table wp_options est un suspect de premier plan, surtout lorsque des valeurs d’options sérialisées sont en jeu et que le nombre de lignes est élevé. La même chose s’applique quand tu changes d’hébergeur : les lecteurs aux prises avec siteurl et des boucles de redirection après un déplacement, sujet couvert dans notre guide sur la migration de siteurl dans wp_options, sont exactement le public qui peut aussi traîner une clé primaire cassée héritée de l’ancien serveur. Corriger la clé en premier élimine toute une catégorie d’échecs de migration avant même qu’ils ne commencent.

Articles connexes

• La structure de la base de données WordPress
• Déployer les modifications du staging vers la production
• Comment migrer ton site WordPress vers un nouvel hébergeur
• Ignorer les commandes et produits WooCommerce
• Comment trouver le numéro de version WordPress de ton site