Erro ao estabelecer uma conexão com o banco de dados: o que significa

O que a mensagem diz

A cada página exibida, o WordPress abre uma conexão com o banco de dados MySQL ou MariaDB usando quatro informações escritas no wp-config.php, na raiz do site:

define( 'DB_NAME', 'nome_do_banco' );
define( 'DB_USER', 'usuario' );
define( 'DB_PASSWORD', 'senha' );
define( 'DB_HOST', 'localhost' );

“Erro ao estabelecer uma conexão com o banco de dados” quer dizer que essa conexão falhou. Quatro causas produzem a mensagem: dados de acesso que não correspondem mais, um servidor de banco de dados parado ou inacessível, um servidor sobrecarregado ou um banco de dados danificado. As seções a seguir percorrem essas causas da mais simples de verificar à mais rara.

1. O servidor de banco de dados responde?

• A página de status da hospedagem: uma pane ou uma manutenção do servidor MySQL é anunciada ali.
• Os outros sites da mesma conta: se eles mostram o mesmo erro no mesmo momento, a causa está do lado do servidor, e a correção cabe à hospedagem.
• O phpMyAdmin, pelo painel da hospedagem: se ele abre o banco de dados e mostra as tabelas, o servidor funciona e o banco existe.

Se o servidor for a causa, abra um chamado na hospedagem informando o horário do início da pane e a mensagem exata. Não há nada a alterar no site enquanto isso.

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

É a causa mais frequente depois de uma mudança de hospedagem, de uma troca da senha do banco no painel da hospedagem ou de uma restauração. Compare os quatro valores do wp-config.php com a seção de bancos de dados da hospedagem:

• DB_NAME e DB_USER: muitas hospedagens colocam antes deles o nome da conta (conta_wordpress). O prefixo faz parte do nome.
• DB_PASSWORD: na dúvida, defina uma nova senha para o usuário no painel, e copie-a no arquivo.
• DB_HOST: localhost em muitas hospedagens, mas não em todas. Algumas indicam um nome de servidor ou um endereço, às vezes seguido de uma porta (:3306). O valor exato aparece no painel.
• O usuário precisa ter permissões no banco: no painel, verifique se o usuário está associado ao banco de dados, com todos os privilégios.

Uma senha que contém um apóstrofo (') corta a string PHP que a envolve no wp-config.php. Coloque uma barra invertida antes dele (\'), ou escolha uma senha sem apóstrofo.

Testar os dados de acesso fora do WordPress

O WordPress exibe uma mensagem genérica. O MySQL, por sua vez, diz exatamente o que está errado. Duas formas de consultá-lo com os valores do wp-config.php:

Na linha de comando, se você tem acesso SSH

mysql -h localhost -u usuario -p nome_do_banco

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

Com um arquivo PHP temporário

Coloque este arquivo na raiz do site com um nome difícil de adivinhar, abra-o no navegador e depois exclua-o imediatamente: ele contém a senha do banco de dados.

<?php
mysqli_report(MYSQLI_REPORT_OFF);
$conexao = @mysqli_connect('localhost', 'usuario', 'senha', 'nome_do_banco');
echo $conexao ? 'Conexão bem-sucedida' : 'Falha: ' . mysqli_connect_error();

A primeira linha é importante: desde o PHP 8.1, uma conexão que falha lança uma exceção por padrão, e a página ficaria branca em vez de mostrar a mensagem do MySQL.

3. Um banco de dados danificado: a ferramenta de reparo

Quando os dados de acesso estão corretos mas há tabelas danificadas, o site público mostra a mesma mensagem de erro de conexão, e o painel do WordPress uma mensagem mais precisa: “Uma ou mais tabelas de banco de dados estão indisponíveis. O banco de dados pode precisar de reparo.” O WordPress oferece uma ferramenta para isso. Acrescente esta linha ao wp-config.php:

define( 'WP_ALLOW_REPAIR', true );

Depois abra https://www.seu-site.com/wp-admin/maint/repair.php e execute “Reparar o banco de dados”. Retire a linha assim que o reparo terminar: enquanto ela estiver ali, essa página fica acessível a qualquer pessoa, sem login.

Antes de qualquer reparo, exporte o banco de dados (wp db export, ou a aba Exportar do phpMyAdmin). Se o reparo falhar, a hospedagem pode restaurar o banco a partir dos backups dela.

4. Um erro que vai e volta: a carga

Um erro que aparece em certos horários e some sozinho indica um servidor sobrecarregado, e não um ajuste errado. As causas mais comuns:

• Um pico de tráfego, muitas vezes de robôs: tentativas de login repetidas no wp-login.php ou no xmlrpc.php, visíveis nos logs de acesso da hospedagem.
• Os limites da hospedagem compartilhada: número de conexões simultâneas ou de processos limitado por conta. O painel da hospedagem em geral mostra esses limites na seção de consumo de recursos.
• Um plugin pesado: estatísticas, logs ou tarefas agendadas que gravam no banco a cada visita.

As correções: bloquear as tentativas de login abusivas, instalar um cache de páginas, desativar o xmlrpc.php se nenhum aplicativo o usa, e pedir à hospedagem os logs do período com erro.