Erro ao estabelecer uma ligação com a base de dados no WordPress

O que diz a mensagem

A cada página mostrada, o WordPress abre uma ligação à sua base de dados MySQL ou MariaDB com quatro informações escritas no wp-config.php, na raiz do site:

define( 'DB_NAME', 'nome_da_base_de_dados' );
define( 'DB_USER', 'utilizador' );
define( 'DB_PASSWORD', 'palavra_passe' );
define( 'DB_HOST', 'localhost' );

«Erro ao estabelecer uma ligação com a base de dados» quer dizer que esta ligação falhou. Quatro causas o produzem: dados de acesso que já não correspondem, um servidor de base de dados parado ou inacessível, um servidor saturado ou uma base de dados danificada. As secções seguintes percorrem-nas da mais simples de verificar à mais rara.

1. O servidor de base de dados responde?

• A página de estado do fornecedor de alojamento: uma avaria ou uma manutenção do servidor MySQL é anunciada lá.
• Os outros sites da mesma conta: se mostrarem o mesmo erro ao mesmo tempo, a causa está do lado do servidor, e a correção cabe ao fornecedor de alojamento.
• O phpMyAdmin, a partir do painel do fornecedor de alojamento: se abrir a base de dados e mostrar as tabelas, o servidor funciona e a base de dados existe.

Se o servidor estiver em causa, abra um pedido de suporte junto do fornecedor de alojamento indicando a hora de início da avaria e a mensagem exata. Não há nada a alterar no site entretanto.

2. Os dados de acesso do wp-config.php estão certos?

É a causa mais frequente depois de uma mudança de alojamento, de uma alteração da palavra-passe da base de dados no painel do fornecedor de alojamento ou de uma restauração. Compare os quatro valores do wp-config.php com a secção de bases de dados do seu fornecedor de alojamento:

• DB_NAME e DB_USER: muitos fornecedores de alojamento acrescentam-lhes como prefixo o nome da conta (conta_wordpress). O prefixo faz parte do nome.
• DB_PASSWORD: em caso de dúvida, defina uma nova palavra-passe para o utilizador no painel e copie-a para o ficheiro.
• DB_HOST: localhost em muitos fornecedores de alojamento, mas não em todos. Alguns indicam um nome de servidor ou um endereço, por vezes seguido de uma porta (:3306). O valor exato consta do painel.
• O utilizador tem de ter direitos sobre a base de dados: no painel, verifique que o utilizador está associado à base de dados, com todos os privilégios.

Uma palavra-passe que contenha um apóstrofo (') corta a cadeia PHP que a envolve no wp-config.php. Coloque antes dele uma barra invertida (\'), ou escolha uma palavra-passe sem apóstrofo.

Testar os dados de acesso fora do WordPress

O WordPress mostra uma mensagem genérica. O MySQL, esse, diz precisamente o que está mal. Duas maneiras de o interrogar com os valores do wp-config.php:

Na linha de comandos, se tiver acesso SSH

mysql -h localhost -u utilizador -p nome_da_base_de_dados

Com o WP-CLI, wp db check lê diretamente o wp-config.php e verifica as tabelas com estes dados de acesso.

Com um ficheiro PHP temporário

Coloque este ficheiro na raiz do site com um nome difícil de adivinhar, abra-o no navegador e elimine-o logo a seguir: contém a palavra-passe da base de dados.

<?php
mysqli_report(MYSQLI_REPORT_OFF);
$ligacao = @mysqli_connect('localhost', 'utilizador', 'palavra_passe', 'nome_da_base_de_dados');
echo $ligacao ? 'Ligação bem-sucedida' : 'Falha: ' . mysqli_connect_error();

A primeira linha conta: desde o PHP 8.1, uma ligação que falha lança uma exceção por predefinição, e a página ficaria em branco em vez de mostrar a mensagem do MySQL.

3. Uma base de dados danificada: a ferramenta de reparação

Quando os dados de acesso estão certos mas há tabelas danificadas, o site público mostra a mesma mensagem de erro de ligação, e a administração uma mensagem mais precisa: «Uma ou mais tabelas da base de dados não estão disponíveis. A base de dados pode estar a precisar de ser reparada.». O WordPress fornece uma ferramenta para isso. Acrescente esta linha ao wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Abra depois https://www.o-seu-site.com/wp-admin/maint/repair.php e execute «Reparar base de dados». Retire a linha assim que a reparação terminar: enquanto lá estiver, esta página fica acessível a qualquer pessoa, sem início de sessão.

Antes de qualquer reparação, exporte a base de dados (wp db export, ou o separador Exportar do phpMyAdmin). Se a reparação falhar, o fornecedor de alojamento pode restaurar a base de dados a partir das suas cópias de segurança.

4. Um erro que aparece e desaparece: a carga

Um erro que surge a certas horas e depois desaparece sozinho indica um servidor saturado, mais do que uma configuração errada. As causas mais comuns:

• Um pico de tráfego, muitas vezes robôs: tentativas repetidas de início de sessão no wp-login.php ou no xmlrpc.php, visíveis nos registos de acesso do fornecedor de alojamento.
• Os limites do alojamento partilhado: número de ligações simultâneas ou de processos limitado por conta. O painel do fornecedor de alojamento mostra-os em geral na secção de consumo de recursos.
• Um plugin pesado: estatísticas, registos ou tarefas agendadas que escrevem na base de dados a cada visita.

As correções: bloquear as tentativas abusivas de início de sessão, instalar uma cache de páginas, desativar o xmlrpc.php se nenhuma aplicação o usar, e pedir ao fornecedor de alojamento os registos do período com erro.