Come correggere una chiave primaria mancante nella tabella WordPress wp_options

In breve: una chiave primaria mancante sulla tabella wp_options significa che MySQL smette di incrementare automaticamente option_id, quindi le nuove righe vengono scritte con option_id = 0. WordPress continua a funzionare, ma ogni esportazione, migrazione o push di staging fallisce con un errore di chiave duplicata, e le query sulla tabella diventano più lente perché MySQL non può più usare la chiave. La soluzione più rapida: fai il backup del database, rinumera i valori option_id duplicati in modo che ciascuno sia univoco, poi esegui ALTER TABLE wp_options ADD PRIMARY KEY (option_id) e ripristina AUTO_INCREMENT. Puoi eseguire l’intera riparazione in phpMyAdmin o con SQL grezzo, e non serve alcun plugin.

A volte, in determinate circostanze, la tabella wp_options (o qualsiasi altra tabella) può perdere il suo indice di chiave primaria. La causa esatta è raramente ovvia. Nei ticket di supporto WP STAGING, lo vediamo più spesso su database che sono stati migrati manualmente da un server a un altro, o spostati con uno strumento che non ha tenuto conto di ogni caso, come un passaggio tra versioni MySQL o tra i motori di archiviazione InnoDB e MyISAM.

Per essere chiari: WP STAGING non è la causa di questo errore. WP STAGING ti aiuta solo a rilevarlo, mostrando un avviso evidente nella dashboard di amministrazione di WordPress quando trova una tabella core senza chiave primaria. Lo segnaliamo presto perché si tratta di un problema critico e insidioso. Il tuo sito continua a caricarsi come se nulla fosse, quindi non te ne accorgerai finché una migrazione o un backup non falliscono, e a quel punto la tabella potrebbe contenere centinaia di righe danneggiate. Più a lungo resta irrisolto, più righe duplicate si accumulano e più lavoro richiede la riparazione.

Cos’è una chiave primaria e perché wp_options ne ha bisogno

Una chiave primaria è una colonna (o un insieme di colonne) che identifica in modo univoco ogni riga di una tabella. In un’installazione WordPress standard, la tabella wp_options usa option_id come chiave primaria. option_id è definito come bigint(20) unsigned NOT NULL auto_increment, il che significa che il database assegna automaticamente a ogni nuova riga il successivo numero non utilizzato e garantisce che nessuna due righe condividano lo stesso valore.

Due cose si rompono quando questa chiave scompare:

• L’incremento automatico si ferma. Senza la chiave primaria, MySQL non incrementa più option_id. Ogni nuova riga viene inserita con il valore predefinito 0. L’esempio originale qui sotto mostra l’aspetto di una sequenza corretta:Ed ecco come appare la stessa colonna una volta che la chiave è andata persa e le nuove righe si accumulano con option_id = 0:
• Esportazioni e migrazioni falliscono. Una colonna di chiave primaria deve contenere valori univoci. Nel momento in cui esporti queste righe e le importi in un altro database, MySQL rifiuta i duplicati con un errore come Cannot insert duplicate key, e l’importazione si interrompe a metà. Questo è il motivo per cui WP STAGING e qualsiasi altro plugin di migrazione non riescono a completare un trasferimento di database quando la chiave manca. Il push da un sito di staging alla produzione fallisce esattamente nel punto in cui vengono scritte le righe duplicate 0.

C’è anche un costo più silenzioso. wp_options è una delle tabelle più lette in WordPress perché le opzioni con autoload vengono recuperate a quasi ogni richiesta. Nei nostri test, una chiave primaria mancante costringe MySQL a ripiegare su una scansione completa della tabella per ricerche che altrimenti userebbero la chiave, il che aggiunge un sovraccarico misurabile ai normali caricamenti delle pagine. Se vuoi approfondire come wp_options si inserisce nello schema più ampio, consulta la nostra guida alle tabelle essenziali del database WordPress.

Come confermare che la chiave primaria manchi davvero

Prima di cambiare qualcosa, conferma che sia davvero questo il tuo problema. Apri uno strumento di database come phpMyAdmin o Adminer, seleziona il tuo database WordPress ed esegui:

SHOW CREATE TABLE wp_options;

In una tabella corretta l’output contiene una riga come PRIMARY KEY (option_id) e la colonna option_id è contrassegnata come AUTO_INCREMENT. Se entrambe mancano, la chiave è andata persa. Puoi anche elencare direttamente gli indici:

SHOW INDEX FROM wp_options;

Una tabella con una chiave intatta restituisce una riga in cui Key_name è PRIMARY. Se quella riga è assente, non c’è alcuna chiave primaria.

Questo screenshot mostra una normale tabella wp_options con una chiave primaria impostata sulla colonna option_id:

Questo secondo screenshot mostra la stessa tabella con la chiave primaria mancante:

Per vedere quante righe sono già interessate, conta i duplicati:

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

Qualsiasi gruppo con option_id = 0 e un conteggio superiore a uno conferma le righe danneggiate che devi rinumerare prima di poter ripristinare la chiave.

Sostituisci ovunque wp_options con il nome reale della tua tabella se la tua installazione usa un prefisso di tabella personalizzato (per esempio wp_xyz_options).

Prima di iniziare: fai il backup del database

Ogni passaggio qui sotto modifica direttamente il database, quindi fai prima un backup completo e scaricalo dal server. Se qualcosa va storto, ti serve una copia pulita da ripristinare. Vanno bene un backup WP STAGING, un’esportazione phpMyAdmin o un mysqldump. Questo è anche un buon momento per svolgere il lavoro su una copia di staging anziché in produzione: clona il sito, ripara la tabella lì, conferma il risultato e solo allora applica la stessa correzione al database live.

Correggere la chiave primaria mancante in phpMyAdmin

Se preferisci un’interfaccia grafica all’SQL grezzo, phpMyAdmin gestisce l’intera riparazione dalla scheda Struttura.

1. Apri phpMyAdmin o Adminer e vai alla tabella wp_options.
2. Affronta prima gli ID duplicati. Prendi il valore più alto esistente nella colonna option_id e rinumera ogni riga 0 una per una, in modo che ogni valore sia di nuovo univoco. Questo screencast mostra la rinumerazione:
3. Apri l’editor degli indici della tabella:
4. Imposta option_id come chiave primaria:
5. Se vedi l’errore Duplicate entry '0' for key 'PRIMARY', alcuni ID duplicati sono ancora nella tabella:
6. Trova i duplicati rimasti e incrementane i valori in modo che nessuno si ripeta, poi aggiungi di nuovo la chiave primaria. Una volta riuscito, riabilita l’incremento automatico su option_id in modo che le righe future si numerino correttamente.

Correggere la chiave primaria mancante con SQL

La stessa riparazione richiede tre istruzioni se hai dimestichezza con la console SQL. Eseguile in ordine sul tuo database WordPress.

Innanzitutto, assegna a ogni riga danneggiata 0 un nuovo numero univoco continuando dal valore massimo attuale di option_id:

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

Poi, aggiungi la chiave primaria ora che ogni valore è univoco:

ALTER TABLE wp_options ADD PRIMARY KEY (option_id);

Infine, ripristina l’incremento automatico in modo che WordPress numeri di nuovo automaticamente le nuove opzioni:

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

La sintassi ufficiale di queste istruzioni è documentata nel manuale MySQL alla voce ALTER TABLE. Per la definizione canonica delle colonne di wp_options, la descrizione del database WordPress elenca i tipi di colonna esatti che WordPress core si aspetta.

Verificare la correzione

Conferma che la riparazione abbia tenuto prima di fidarti della tabella:

SHOW CREATE TABLE wp_options;

L’output dovrebbe ora includere PRIMARY KEY (option_id) e mostrare AUTO_INCREMENT sulla colonna option_id. Come verifica finale, inserisci ed elimina un’opzione usa e getta, oppure semplicemente salva un’impostazione in WordPress, e conferma che la nuova riga riceva un option_id univoco e incrementale anziché un altro 0.

Con la chiave di nuovo al suo posto puoi eseguire la migrazione o il push di staging che prima falliva. Anche così, fai un nuovo backup prima del push in modo da avere un punto di ripristino che includa la tabella riparata.

Cosa fare se ALTER TABLE fallisce

Il percorso ideale copre la maggior parte delle installazioni, ma alcuni ambienti richiedono una gestione aggiuntiva. Procedi in ordine:

• Duplicate entry '0' for key 'PRIMARY'. Non tutti i duplicati sono stati rinumerati. Riesegui la query di conteggio dei duplicati dalla sezione diagnostica, rinumera le righe rimanenti, poi aggiungi di nuovo la chiave. Questo è il motivo singolo più comune per cui il passaggio ALTER TABLE si rifiuta di eseguire.
• Lock wait timeout su una tabella grande. ALTER TABLE riscrive la tabella e mantiene un blocco mentre è in esecuzione. Su una tabella wp_options grande, o su un server di produzione molto trafficato, l’istruzione può andare in timeout. Esegui la riparazione durante il basso traffico, su un clone di staging, oppure usa uno strumento di modifica dello schema online come pt-online-schema-change se il tuo host lo fornisce.
• MyISAM invece di InnoDB. I passaggi funzionano su entrambi i motori, ma WordPress rende al meglio con InnoDB. Se SHOW CREATE TABLE wp_options riporta ENGINE=MyISAM, valuta la conversione dopo che la chiave è a posto con ALTER TABLE wp_options ENGINE=InnoDB. Fai prima un backup, perché anche la conversione riscrive la tabella.
• L’hosting blocca le modifiche dello schema. Alcuni host gestiti limitano le istruzioni DDL dirette o eseguono il database sotto un utente senza i privilegi ALTER. Se l’istruzione fallisce con un errore di permessi, chiedi al tuo host di eseguire le tre istruzioni per te, oppure di concedere temporaneamente il privilegio.

Un ALTER TABLE fallito rientra quasi sempre in uno di questi quattro casi. Un lettore che traccia l’errore SQL sottostante nel log del server potrebbe trovarlo riportato anche nell’output di debug di WordPress; la nostra guida su come individuare un problema nelle tabelle del database WordPress spiega come attivare quella registrazione.

Perché questo è importante per migrazioni e push

Una chiave primaria mancante è uno dei motivi più silenziosi per cui lo spostamento di un sito si blocca. Se un push da staging a live va in timeout o si interrompe a metà trasferimento, la tabella wp_options è un sospetto principale, specialmente quando sono coinvolti valori di opzione serializzati e il numero di righe è grande. Lo stesso vale quando cambi host: i lettori alle prese con siteurl e loop di reindirizzamento dopo uno spostamento, trattati nella nostra guida alla migrazione di siteurl in wp_options, sono esattamente il pubblico che potrebbe anche portarsi dietro una chiave primaria rotta dal vecchio server. Correggere prima la chiave elimina un’intera categoria di errori di migrazione prima che inizino.

Articoli correlati

• La struttura del database WordPress
• Pubblicare le modifiche da staging a produzione
• Come migrare il tuo sito WordPress su un nuovo host
• Saltare ordini e prodotti WooCommerce
• Come scoprire il numero di versione WordPress del tuo sito