SQLSTATE HY000 2002: O que é: Como Resolver?

SQLSTATE HY000 2002: Como Resolver Passo a Passo.

O erro “SQLSTATE[HY000] [2002] Nenhuma conexão pôde ser feita porque a máquina de destino as recusou ativamente “é um dos mais comuns enfrentados por desenvolvedores PHP que utilizam PDO ou MySQLi para conectar ao banco de dados MySQL/MariaDB.

A mensagem completa geralmente aparece assim:

SQLSTATE[HY000] [2002] Connection refused
ou
SQLSTATE[HY000] [2002] No such file or directory
ou
SQLSTATE[HY000] [2002] Operation timed out

Esse código de erro ‘SQLSTATE HY000 2002:’ indica que o cliente PHP não conseguiu estabelecer uma conexão com o servidor MySQL na porta e host especificados.

Ou seja, não é um erro de autenticação (usuário/senha errados), mas sim de acesso físico à máquina/servidor ou à porta de comunicação.

Principais Causas do Erro SQLSTATE HY000 2002

1. Host incorreto ou inacessível

• Usar localhost quando o MySQL está configurado para ouvir apenas no socket Unix.
• Usar 127.0.0.1 quando o MySQL está escutando apenas no socket.
• Host remoto bloqueado por firewall ou não permitido no bind-address.

1. Servidor MySQL/MariaDB não está rodando

• Serviço parado ou crashado.

1. Porta errada ou bloqueada

• MySQL não está na porta padrão 3306 ou a porta está bloqueada.

1. Configuração do socket Unix (comum em macOS e Linux)

• O caminho do socket está errado ou o arquivo não existe.

1. Problemas com Docker, WAMP, XAMPP, Laragon ou MAMP

• Containers/parados ou configuração de rede incorreta.

1. Timeout de conexão (servidores remotos)

• Latência alta ou bloqueio de rede.

Soluções Passo a Passo

1. Verifique se o MySQL está rodando

# Linux/macOS
sudo systemctl status mysql
# ou
sudo service mysql status

# Windows (via Prompt como administrador)
net start mysql

2. Teste a conexão via terminal/linha de comando

mysql -u seu_usuario -p -h 127.0.0.1 -P 3306

Se funcionar no terminal mas não no PHP → problema de configuração do host.

3. Troque entre localhost e 127.0.0.1

Muitas vezes o segredo está aqui:

// Tente uma dessas opções no PDO ou MySQLi

// Opção 1 - Via TCP/IP (funciona na maioria dos casos com Docker/WAMP)
$host = '127.0.0.1:3306';

// Opção 2 - Via socket Unix (comum em Linux/macOS nativo)
$host = 'localhost';

// Opção 3 - Especificar o socket manualmente (MAMP, XAMPP)
$host = 'localhost:/Applications/MAMP/tmp/mysql/mysql.sock'; // macOS MAMP
$host = 'localhost:/opt/lampp/var/mysql/mysql.sock';         // XAMPP Linux

4. Verifique o arquivo de configuração do MySQL

Edite my.cnf ou my.ini:

[mysqld]
bind-address = 0.0.0.0    # ou 127.0.0.1
port = 3306
socket = /var/run/mysqld/mysqld.sock

Xampp

Veja se você iniciou o módulo Apache e SQL.

Se aparecer “Start” nos 2, basta clicar para ativar e tente novamente.

5. Soluções específicas por ambiente

Docker

# Use o nome do serviço como host
host: mysql_container_name
# ou
host: host.docker.internal  # macOS/Windows

Laravel (.env)

DB_HOST=127.0.0.1
DB_PORT=3306
# ou
DB_HOST=mysql  # nome do serviço no docker-compose

MAMP (macOS)

$dsn = "mysql:host=localhost;unix_socket=/Applications/MAMP/tmp/mysql/mysql.sock;dbname=seubanco";

6. Limpe o cache do Laravel (se aplicável)

php artisan config:clear
php artisan cache:clear
php artisan route:clear

Conclusão

Em conclusão desse tutorial, o erro SQLSTATE HY000 2002: quase sempre é resolvido com uma das ações acima.

A mais comum atualmente (2025) é a diferença entre localhost (socket) e 127.0.0.1 (TCP/IP), especialmente em ambientes Xampp, Docker, MAMP e novos projetos Laravel.

Dica de ouro: comece sempre testando a conexão com 127.0.0.1 em vez de localhost.

Na maioria dos casos modernos, isso resolve instantaneamente.

Se depois de tudo ainda persistir, verifique logs do MySQL:

tail -f /var/log/mysql/error.log

Com essas informações, mais de 95% dos casos desse erro são resolvidos em menos de 5 minutos.

Então, boa sorte! 🚀