Como corrigir uma chave primária em falta na tabela WordPress wp_options

TL;DR: A ausência de uma chave primária na tabela wp_options faz com que o MySQL deixe de incrementar automaticamente o option_id, por isso as novas linhas são gravadas com option_id = 0. O WordPress continua a funcionar, mas qualquer exportação, migração ou push de staging falha com um erro de chave duplicada, e as consultas à tabela tornam-se mais lentas porque o MySQL já não consegue usar a chave. A correção mais rápida: faz backup da base de dados, renumera os valores option_id duplicados para que cada um seja único, depois executa ALTER TABLE wp_options ADD PRIMARY KEY (option_id) e restaura o AUTO_INCREMENT. Podes fazer toda a reparação no phpMyAdmin ou com SQL direto, e não é necessário qualquer plugin.

Às vezes, em determinadas circunstâncias, a tabela wp_options (ou qualquer outra tabela) pode perder o seu índice de chave primária. O gatilho exato raramente é óbvio. Nos tickets de suporte do WP STAGING, vemos isto com mais frequência em bases de dados que foram migradas manualmente de um servidor para outro, ou movidas com uma ferramenta que não cobriu todos os casos, como uma mudança entre versões do MySQL ou entre os motores de armazenamento InnoDB e MyISAM.

Para que fique claro: o WP STAGING não é a causa deste erro. O WP STAGING apenas te ajuda a detetá-lo, mostrando um aviso destacado no painel de administração do WordPress quando encontra uma tabela do core sem chave primária. Damos-lhe destaque cedo porque este é um problema crítico e traiçoeiro. O teu site continua a carregar como se nada estivesse errado, por isso não vais reparar nele até que uma migração ou um backup falhe, e nessa altura a tabela pode já conter centenas de linhas corrompidas. Quanto mais tempo permanecer por corrigir, mais linhas duplicadas se acumulam e mais trabalhosa se torna a reparação.

O que é uma chave primária e por que razão a wp_options precisa de uma

Uma chave primária é uma coluna (ou um conjunto de colunas) que identifica de forma única cada linha de uma tabela. Numa instalação padrão do WordPress, a tabela wp_options usa option_id como chave primária. O option_id é definido como bigint(20) unsigned NOT NULL auto_increment, o que significa que a base de dados atribui automaticamente a cada nova linha o próximo número não utilizado e garante que não há duas linhas a partilhar o mesmo valor.

Duas coisas deixam de funcionar quando essa chave desaparece:

• O auto incremento para. Sem a chave primária, o MySQL deixa de incrementar o option_id. Cada nova linha é inserida com o valor por defeito 0. O exemplo original abaixo mostra o aspeto de uma sequência saudável:E aqui está o aspeto da mesma coluna quando a chave desaparece e as novas linhas se acumulam com option_id = 0:
• As exportações e migrações falham. Uma coluna de chave primária tem de conter valores únicos. No momento em que exportas estas linhas e as importas para outra base de dados, o MySQL rejeita os duplicados com um erro como Cannot insert duplicate key, e a importação para a meio. É por isto que o WP STAGING e qualquer outro plugin de migração não conseguem concluir uma transferência de base de dados quando a chave está em falta. O push de um site de staging para produção falha exatamente no ponto em que as linhas 0 duplicadas são gravadas.

Há também um custo mais silencioso. A wp_options é uma das tabelas mais lidas do WordPress porque as opções com autoload são obtidas em quase todos os pedidos. Nos nossos testes, uma chave primária em falta obriga o MySQL a recorrer a uma varredura completa da tabela para pesquisas que de outro modo usariam a chave, o que acrescenta uma sobrecarga mensurável a carregamentos de página normais. Se quiseres contexto sobre como a wp_options se enquadra no esquema mais amplo, consulta o nosso guia sobre as tabelas essenciais da base de dados do WordPress.

Como confirmar que a chave primária está mesmo em falta

Antes de alterares fosse o que for, confirma que este é realmente o teu problema. Abre uma ferramenta de base de dados como o phpMyAdmin ou o Adminer, seleciona a tua base de dados do WordPress e executa:

SHOW CREATE TABLE wp_options;

Numa tabela saudável, o resultado contém uma linha como PRIMARY KEY (option_id) e a coluna option_id está marcada como AUTO_INCREMENT. Se ambos estiverem em falta, a chave desapareceu. Também podes listar os índices diretamente:

SHOW INDEX FROM wp_options;

Uma tabela com a chave intacta devolve uma linha em que Key_name é PRIMARY. Se essa linha estiver ausente, não existe chave primária.

Este screenshot mostra uma tabela wp_options normal, com a chave primária definida na coluna option_id:

Este segundo screenshot mostra a mesma tabela com a chave primária em falta:

Para veres quantas linhas já estão afetadas, conta os duplicados:

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

Qualquer grupo com option_id = 0 e uma contagem acima de um confirma as linhas corrompidas que precisas de renumerar antes de a chave poder ser restaurada.

Substitui wp_options pelo nome real da tua tabela em todo o processo, caso a tua instalação use um prefixo de tabela personalizado (por exemplo wp_xyz_options).

Antes de começar: faz backup da base de dados

Cada passo abaixo modifica a base de dados diretamente, por isso faz primeiro um backup completo e transfere-o para fora do servidor. Se algo correr mal, vais querer uma cópia limpa para restaurar. Um backup do WP STAGING, uma exportação do phpMyAdmin ou um mysqldump servem todos. Este é também um bom momento para fazer o trabalho numa cópia de staging em vez de produção: clona o site, repara a tabela aí, confirma o resultado e só depois aplica a mesma correção à base de dados ao vivo.

Corrigir a chave primária em falta no phpMyAdmin

Se preferes uma interface gráfica em vez de SQL direto, o phpMyAdmin trata de toda a reparação a partir do separador Estrutura.

1. Abre o phpMyAdmin ou o Adminer e navega até à tabela wp_options.
2. Trata primeiro dos IDs duplicados. Pega no maior valor existente na coluna option_id e renumera cada linha 0 uma a uma, para que cada valor seja novamente único. Este screencast mostra a renumeração:
3. Abre o editor de índices da tabela:
4. Define option_id como chave primária:
5. Se vires o erro Duplicate entry '0' for key 'PRIMARY', ainda há alguns IDs duplicados na tabela:
6. Encontra os duplicados que restam e incrementa os seus valores para que nenhum se repita, depois volta a adicionar a chave primária. Assim que for bem-sucedido, reativa o auto incremento no option_id para que as linhas futuras se numerem corretamente.

Corrigir a chave primária em falta com SQL

A mesma reparação leva três instruções se te sentires à vontade com a consola SQL. Executa-as por ordem contra a tua base de dados do WordPress.

Primeiro, dá a cada linha 0 corrompida um número único novo, continuando a partir do option_id máximo atual:

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

A seguir, adiciona a chave primária agora que todos os valores são únicos:

ALTER TABLE wp_options ADD PRIMARY KEY (option_id);

Por fim, restaura o auto incremento para que o WordPress volte a numerar automaticamente as novas opções:

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

A sintaxe oficial destas instruções está documentada no manual do MySQL, em ALTER TABLE. Para a definição canónica das colunas da wp_options, a descrição da base de dados do WordPress lista os tipos de coluna exatos que o core do WordPress espera.

Verificar a correção

Confirma que a reparação se manteve antes de confiares na tabela:

SHOW CREATE TABLE wp_options;

O resultado deve agora incluir PRIMARY KEY (option_id) e mostrar AUTO_INCREMENT na coluna option_id. Como verificação final, insere e elimina uma opção descartável, ou simplesmente guarda uma definição no WordPress, e confirma que a nova linha recebe um option_id único e incrementado, em vez de outro 0.

Com a chave de volta no lugar, podes executar a migração ou o push de staging que antes falhava. Ainda assim, faz um novo backup antes do push, para teres um ponto de recuperação que inclua a tabela reparada.

O que fazer se o ALTER TABLE falhar

O caminho ideal cobre a maioria das instalações, mas alguns ambientes precisam de tratamento adicional. Trabalha estes casos por ordem:

• Duplicate entry '0' for key 'PRIMARY'. Nem todos os duplicados foram renumerados. Volta a executar a consulta de contagem de duplicados da secção de diagnóstico, renumera as linhas que restam, depois volta a adicionar a chave. Esta é, de longe, a razão mais comum para o passo ALTER TABLE se recusar a executar.
• Lock wait timeout numa tabela grande. O ALTER TABLE reescreve a tabela e mantém um bloqueio enquanto corre. Numa tabela wp_options grande, ou num servidor de produção movimentado, a instrução pode esgotar o tempo. Executa a reparação em períodos de pouco tráfego, num clone de staging, ou usa uma ferramenta de alteração de esquema online como o pt-online-schema-change, se o teu alojamento a disponibilizar.
• MyISAM em vez de InnoDB. Os passos funcionam em ambos os motores, mas o WordPress corre melhor em InnoDB. Se o SHOW CREATE TABLE wp_options indicar ENGINE=MyISAM, considera converter depois de a chave estar no lugar, com ALTER TABLE wp_options ENGINE=InnoDB. Faz primeiro um backup, porque a conversão também reescreve a tabela.
• O alojamento bloqueia alterações de esquema. Alguns alojamentos geridos restringem instruções DDL diretas ou correm a base de dados sob um utilizador sem o privilégio ALTER. Se a instrução falhar com um erro de permissões, pede ao teu alojamento que execute as três instruções por ti, ou que conceda o privilégio temporariamente.

Um ALTER TABLE falhado é, quase sempre, um destes quatro casos. Quem estiver a acompanhar o erro SQL subjacente no log do servidor pode encontrá-lo também na saída de depuração do WordPress; o nosso guia sobre como detetar um problema nas tabelas da base de dados do WordPress explica como ativar esse registo.

Por que razão isto é importante para migrações e pushes

Uma chave primária em falta é uma das razões mais silenciosas para uma mudança de site empacar. Se um push de staging para o site ao vivo esgotar o tempo ou abortar a meio da transferência, a tabela wp_options é uma das principais suspeitas, sobretudo quando estão envolvidos valores de opção serializados e a contagem de linhas é grande. O mesmo se aplica quando mudas de alojamento: quem estiver a lutar com siteurl e loops de redirecionamento após uma mudança, tema abordado no nosso guia sobre migrar o siteurl na wp_options, é exatamente o público que pode também estar a arrastar uma chave primária corrompida do servidor antigo. Corrigir a chave primeiro elimina toda uma classe de falhas de migração antes de elas começarem.

Artigos relacionados

• A estrutura da base de dados do WordPress
• Fazer push de alterações de staging para produção
• Como migrar o teu site WordPress para um novo alojamento
• Saltar encomendas e produtos WooCommerce
• Como descobrir o número de versão WordPress do teu site