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

O que este erro significa e como reconhecê-lo

• O site exibe apenas “Erro ao estabelecer uma conexão com o banco de dados”, geralmente em todas as páginas públicas.
• /wp-admin/ também fica indisponível porque usa a mesma conexão com o banco de dados.
• O erro pode começar após uma migração, mudança de hospedagem, restauração do banco de dados, edição manual de wp-config.php, redefinição de senha ou reinicialização do servidor de banco de dados.
• Se apenas algumas páginas falham enquanto outras páginas que usam o banco de dados funcionam, o problema pode ser específico da página, do plugin, do tema ou da consulta, e não uma falha completa de conexão com o banco de dados.

Causas principais, por probabilidade

1. Credenciais incorretas em wp-config.php — DB_NAME, DB_USER, DB_PASSWORD ou DB_HOST não correspondem mais à configuração atual do banco de dados. Isso é especialmente comum após uma migração, restauração, alteração de senha ou edição manual.
2. Servidor MySQL ou MariaDB indisponível — o serviço pode ter sido interrompido, travado ou ficado indisponível devido a um problema de recursos da hospedagem.
3. Host de banco de dados incorreto — localhost pode estar incorreto quando o banco de dados é executado em outro servidor ou contêiner, enquanto um valor de host remoto pode não corresponder mais ao ambiente atual.
4. Permissões ausentes para o usuário do banco de dados — o usuário pode existir, mas não estar associado ao banco de dados do WordPress ou não ter as permissões necessárias para usá-lo.
5. Tabelas do banco de dados corrompidas — uma gravação interrompida, um desligamento incorreto ou um problema no disco pode danificar as tabelas, mas isso geralmente é menos provável do que um problema de configuração ou disponibilidade.

Como corrigir

1. Confirme o escopo da falha

Abra o site público e /wp-admin/. Se ambos exibirem o erro de conexão, continue com as verificações do banco de dados abaixo. Se apenas uma página ou função falhar, investigue o plugin, tema, consulta ou erro da aplicação específico em vez de presumir que toda a conexão com o banco de dados está indisponível.

2. Verifique se o MySQL ou MariaDB está em execução

Em um VPS ou servidor dedicado pelo qual você é responsável, verifique o status do serviço correspondente. Estes comandos são somente de leitura e exigem acesso ao shell:

systemctl status mysql

Se o servidor usar MariaDB, verifique:

systemctl status mariadb

Em hospedagens compartilhadas ou gerenciadas, consulte as informações de status do banco de dados no painel de hospedagem ou peça ao provedor para verificar o serviço e os limites de recursos. Reinicie um serviço de banco de dados somente quando você administrar o servidor, tiver autorização adequada e confirmar que o impacto operacional é aceitável; uma reinicialização pode interromper conexões ativas com o banco de dados.

3. Verifique as quatro configurações do banco de dados em wp-config.php

Use SFTP ou o gerenciador de arquivos da hospedagem para abrir wp-config.php. Compare estes valores com os dados atuais do banco de dados no painel de hospedagem ou nos registros da migração:

• DB_NAME — o banco de dados que o WordPress deve usar
• DB_USER — o nome de usuário do banco de dados
• DB_PASSWORD — a senha atual desse usuário
• DB_HOST — o endereço ou a configuração do host do servidor de banco de dados

Verifique se há um nome de banco de dados desatualizado, uma senha antiga, um host incorreto ou alterações acidentais de espaços em branco e aspas. Não presuma que os valores anteriores continuam válidos após uma migração, mudança de hospedagem, restauração do banco de dados ou redefinição de senha.

4. Teste a mesma conexão fora do WordPress

Use o phpMyAdmin ou a linha de comando do MySQL com o nome do banco de dados, nome de usuário, senha e host exatos de wp-config.php. Esse teste deve usar o mesmo ambiente e as mesmas credenciais que o WordPress usa.

• Se a conexão direta falhar, investigue as credenciais, o host do banco de dados, a disponibilidade do servidor ou o acesso à rede antes de alterar os arquivos do WordPress.
• Se a conexão direta funcionar, o caminho básico entre servidor e credenciais está funcionando; continue verificando a associação do usuário ao banco de dados, as permissões e a integridade das tabelas.

Nunca publique a senha nem o arquivo wp-config.php completo ao solicitar ajuda.

5. Confirme o acesso e as permissões do usuário do banco de dados

Na seção de usuários do banco de dados no painel de hospedagem, verifique se o usuário de wp-config.php está associado ao banco de dados correto do WordPress e tem permissão para ler e modificar suas tabelas. Essa verificação é especialmente importante após restaurar um banco de dados em uma nova conta ou criar um usuário substituto.

Se você administrar o MySQL diretamente, um administrador autorizado poderá inspecionar as permissões da conta com SHOW GRANTS. Corrija a associação do usuário ao banco de dados ou as permissões somente depois de confirmar o banco de dados e a conta pretendidos. Em seguida, repita o teste de conexão direta e recarregue o site.

6. Verifique problemas nas tabelas somente depois que a conexão funcionar

Se o servidor de banco de dados estiver disponível, as credenciais exatas funcionarem em um teste direto e o usuário tiver acesso, inspecione as tabelas do WordPress no phpMyAdmin ou por meio de uma ferramenta de banco de dados autorizada. CHECK TABLE pode informar problemas nas tabelas.

Crie ou confirme um backup atual do banco de dados antes de tentar qualquer reparo. REPAIR TABLE é principalmente relevante para tabelas MyISAM compatíveis e não é um método universal de reparo. Não execute comandos de reparo repetidamente quando as verificações não indicarem corrupção; volte a investigar o host, a configuração, as permissões e os logs do servidor.

7. Verifique o site completo após a correção

Carregue várias páginas públicas e /wp-admin/. Se ambos funcionarem, limpe somente as camadas de cache relevantes caso o conteúdo desatualizado continue sendo exibido. Se alguma das áreas ainda falhar, registre a mensagem exata atual e consulte os logs do servidor ou da hospedagem em vez de presumir que o problema de conexão original permanece inalterado.

Prevenção e como verificar a correção

• Armazene os dados atuais do nome do banco de dados, usuário, host e senha em um gerenciador de senhas protegido ou em outro registro seguro equivalente.
• Após cada migração ou mudança de hospedagem, teste o site público e /wp-admin/ antes de concluir a mudança.
• Mantenha backups regulares do banco de dados e confirme periodicamente que é possível fazer uma restauração.
• Registre qual usuário do banco de dados está associado a cada banco de dados do WordPress para que uma restauração ou substituição de usuário não remova o acesso silenciosamente.
• Consulte os alertas de recursos da hospedagem e os eventos do serviço de banco de dados quando disponíveis, especialmente após reinicializações inesperadas ou falhas recorrentes de conexão.
• Limite o acesso a wp-config.php e evite compartilhar seu conteúdo ou suas credenciais em solicitações de suporte.

Perguntas frequentes