Guia: Laravel não conecta ao MySQL no Debian 12

17 min de leitura  ·  Guia técnico

Laravel não conecta ao MySQL no Debian 12 quando há divergência entre as configurações do arquivo .env, o estado do serviço MySQL ou as permissões de usuário no banco de dados. O erro mais comum é SQLSTATE[HY000] [2002], que indica falha ao abrir o socket ou a conexão TCP. Siga a sequência de diagnóstico abaixo para identificar e corrigir a causa raiz:

1. Verificar se o serviço MySQL está ativo com systemctl status mysql
2. Confirmar o caminho do socket e o bind-address em mysqld.cnf
3. Checar se a porta 3306 está escutando com ss -tlnp | grep 3306
4. Validar as variáveis DB_* no arquivo .env do Laravel
5. Conceder as permissões corretas ao usuário MySQL
6. Limpar o cache de configuração do Laravel com php artisan config:clear

Pré-requisitos para diagnosticar a conexão Laravel e MySQL no Debian 12

• Acesso SSH ao servidor com privilégios sudo ou como root
• Debian 12 (Bookworm) instalado e atualizado
• MySQL 8.0 ou MariaDB 10.11+ instalado e configurado
• Laravel 10 ou 11 com PHP 8.2 ou 8.3 e extensão pdo_mysql habilitada
• PHP-FPM configurado (geralmente rodando como usuário www-data)
• Acesso ao arquivo .env do projeto Laravel
• Conhecimento básico de linha de comando Linux

Passo 1 — Verificar o estado do serviço MySQL no Debian 12

O primeiro passo no diagnóstico de conexão entre Laravel e MySQL é confirmar que o daemon do banco de dados está de fato em execução. Um serviço parado ou com falha de inicialização é a causa mais simples e frequentemente ignorada do erro SQLSTATE[HY000] [2002].

Execute o comando abaixo para verificar o estado atual:

systemctl status mysql

● mysql.service - MySQL Community Server
     Loaded: loaded (/lib/systemd/system/mysql.service; enabled; preset: enabled)
     Active: active (running) since Mon 2024-06-10 14:22:31 UTC; 2h 15min ago
    Process: 812 ExecStartPre=/usr/share/mysql/mysql-systemd-start pre (code=exited, status=0/SUCCESS)
   Main PID: 901 (mysqld)
     Status: "Server is operational"

Se o serviço estiver parado (inactive (dead)), inicie-o e habilite a inicialização automática:

systemctl start mysql
systemctl enable mysql

Caso o serviço falhe ao iniciar, verifique os logs de erro para identificar a causa:

journalctl -u mysql -n 50 --no-pager

Erros comuns nos logs incluem permissões incorretas no diretório de dados (/var/lib/mysql), arquivos de configuração com sintaxe inválida ou conflito de porta. Se você usa MariaDB no lugar do MySQL, substitua mysql por mariadb nos comandos acima.

Passo 2 — Confirmar o socket Unix e o bind-address do MySQL

A configuração de rede do MySQL determina como o Laravel pode se conectar ao banco de dados. O parâmetro bind-address e o caminho do socket Unix são os dois pontos mais críticos a verificar quando a conexão falha mesmo com o serviço ativo.

Abra o arquivo de configuração principal do MySQL no Debian 12:

cat /etc/mysql/mysql.conf.d/mysqld.cnf | grep -E "bind-address|socket"

bind-address            = 127.0.0.1
socket                  = /var/run/mysqld/mysqld.sock

Anote o caminho exato do socket — você precisará dele se o Laravel estiver configurado para usar conexão via socket Unix. Agora confirme se a porta 3306 está escutando conexões TCP:

ss -tlnp | grep 3306

LISTEN 0      70           127.0.0.1:3306       0.0.0.0:*    users:(("mysqld",pid=901,fd=24))

Se o output mostrar 127.0.0.1:3306, o MySQL aceita conexões TCP apenas do próprio servidor — o que é suficiente para o Laravel rodando localmente. Se o output estiver vazio, o MySQL está configurado para usar apenas socket Unix; nesse caso, ajuste o .env do Laravel para usar o socket diretamente.

Para verificar o socket ativo:

ss -xlnp | grep mysql

u_str LISTEN 0      70     /var/run/mysqld/mysqld.sock 18432            * 0

Passo 3 — Validar e corrigir o arquivo .env do Laravel

O arquivo .env é o ponto central de configuração da conexão com o banco de dados no Laravel. Erros sutis neste arquivo — como espaços extras, valores incorretos ou cache desatualizado — são responsáveis por uma parcela significativa das falhas de conexão mesmo quando o MySQL está funcionando corretamente.

Abra o arquivo .env do seu projeto:

nano /var/www/seu-projeto/.env

Verifique as variáveis de banco de dados. Para conexão via TCP (mais comum):

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nome_do_banco
DB_USERNAME=usuario_laravel
DB_PASSWORD=senha_segura

Para conexão via socket Unix (quando o MySQL não escuta na porta TCP):

DB_CONNECTION=mysql
DB_HOST=localhost
DB_PORT=3306
DB_DATABASE=nome_do_banco
DB_USERNAME=usuario_laravel
DB_PASSWORD=senha_segura
DB_SOCKET=/var/run/mysqld/mysqld.sock

Atenção: no Laravel, usar DB_HOST=127.0.0.1 força conexão TCP, enquanto DB_HOST=localhost pode usar socket Unix dependendo da configuração do PHP. Se o MySQL só escuta no socket, use localhost ou especifique o DB_SOCKET explicitamente.

Após qualquer alteração no .env, limpe obrigatoriamente o cache de configuração:

cd /var/www/seu-projeto
php artisan config:clear
php artisan cache:clear

Configuration cache cleared successfully.
Application cache cleared successfully.

Verifique também se o arquivo .env tem permissão de leitura pelo usuário do PHP-FPM:

ls -la /var/www/seu-projeto/.env

-rw-r--r-- 1 www-data www-data 892 Jun 10 14:00 .env

Se o proprietário não for www-data, corrija:

chown www-data:www-data /var/www/seu-projeto/.env

Passo 4 — Verificar e conceder permissões ao usuário MySQL

Mesmo com o serviço ativo e o .env correto, a conexão falhará se o usuário MySQL não tiver as permissões adequadas para o banco de dados ou para o host de origem. Este é um dos erros mais comuns em ambientes recém-configurados no Debian 12.

Acesse o MySQL como root para verificar os usuários existentes:

mysql -u root -p

Dentro do console MySQL, liste os usuários e seus hosts:

SELECT user, host FROM mysql.user WHERE user = 'usuario_laravel';

+-----------------+-----------+
| user            | host      |
+-----------------+-----------+
| usuario_laravel | localhost |
+-----------------+-----------+

Se o usuário existe apenas para localhost mas o Laravel conecta via 127.0.0.1 (TCP), você precisa criar a permissão para o IP também. No MySQL 8.0, use:

CREATE USER IF NOT EXISTS 'usuario_laravel'@'127.0.0.1' IDENTIFIED BY 'senha_segura';
GRANT ALL PRIVILEGES ON nome_do_banco.* TO 'usuario_laravel'@'127.0.0.1';
FLUSH PRIVILEGES;

Se preferir consolidar em um único usuário que aceite ambos os métodos de conexão:

GRANT ALL PRIVILEGES ON nome_do_banco.* TO 'usuario_laravel'@'localhost';
GRANT ALL PRIVILEGES ON nome_do_banco.* TO 'usuario_laravel'@'127.0.0.1';
FLUSH PRIVILEGES;

Para confirmar que as permissões foram aplicadas corretamente:

SHOW GRANTS FOR 'usuario_laravel'@'127.0.0.1';

+----------------------------------------------------------------------+
| Grants for [email protected]                                 |
+----------------------------------------------------------------------+
| GRANT USAGE ON *.* TO `usuario_laravel`@`127.0.0.1`                 |
| GRANT ALL PRIVILEGES ON `nome_do_banco`.* TO `usuario_laravel`@`127.0.0.1` |
+----------------------------------------------------------------------+

Para mais detalhes sobre conexões remotas ao MySQL, consulte o artigo Conectando remotamente ao MySQL - cPanel da base de conhecimento da AviraHost.

Passo 5 — Verificar a extensão PDO MySQL no PHP 8.2/8.3

O Laravel utiliza a extensão pdo_mysql do PHP para se comunicar com o banco de dados. Se essa extensão não estiver instalada ou habilitada, a conexão falhará independentemente de qualquer outra configuração estar correta.

Verifique se a extensão está carregada:

php -m | grep -i pdo

PDO
pdo_mysql

Se pdo_mysql não aparecer no output, instale o pacote correspondente à sua versão do PHP:

apt update
apt install php8.3-mysql

Após a instalação, reinicie o PHP-FPM:

systemctl restart php8.3-fpm

Confirme que o PHP-FPM também enxerga a extensão (não apenas o PHP CLI):

php-fpm8.3 -m | grep pdo_mysql

pdo_mysql

Se você usa Nginx como servidor web com PHP-FPM, verifique também se o pool do PHP-FPM está configurado corretamente e rodando. Para dicas adicionais de otimização do ambiente Linux, veja o artigo Dicas de Otimização de Servidores Linux.

Passo 6 — Testar a conexão diretamente pelo PHP e pelo Artisan

Após ajustar as configurações, valide a conexão de forma isolada antes de testar a aplicação completa. Isso ajuda a confirmar se o problema está na camada de banco de dados ou em outra parte do Laravel.

Teste a conexão via Artisan Tinker:

cd /var/www/seu-projeto
php artisan tinker

Dentro do Tinker, execute:

DB::connection()->getPdo();

=> PDO {#3456
     inTransaction: false,
     attributes: {
       CASE: NATURAL,
       ERRMODE: EXCEPTION,
       AUTOCOMMIT: 1,
       ...
     },
   }

Se retornar um objeto PDO sem erros, a conexão está funcionando. Se lançar uma exceção, o erro exibido indicará exatamente qual parâmetro está incorreto.

Você também pode testar a conexão diretamente pelo PHP CLI, sem o Laravel:

php -r "
\$pdo = new PDO(
    'mysql:host=127.0.0.1;port=3306;dbname=nome_do_banco',
    'usuario_laravel',
    'senha_segura'
);
echo 'Conexão bem-sucedida: ' . \$pdo->getAttribute(PDO::ATTR_SERVER_VERSION) . PHP_EOL;
"

Conexão bem-sucedida: 8.0.36

Problemas comuns e como resolver

Sintoma: erro "Access denied for user" ao conectar

Causa: O usuário MySQL existe, mas não tem permissão para o banco de dados especificado ou para o host de origem usado na conexão. Isso ocorre frequentemente quando o usuário foi criado apenas para localhost mas o Laravel conecta via 127.0.0.1.
Solução: Acesse o MySQL como root e execute SHOW GRANTS FOR 'usuario'@'127.0.0.1'; para verificar as permissões. Se necessário, conceda acesso com GRANT ALL PRIVILEGES ON banco.* TO 'usuario'@'127.0.0.1'; seguido de FLUSH PRIVILEGES;.

Sintoma: conexão funciona no terminal mas falha na aplicação web

Causa: O PHP CLI e o PHP-FPM podem usar configurações diferentes. O PHP-FPM pode estar rodando com um usuário diferente (www-data), sem acesso ao arquivo .env, ou com uma versão diferente do PHP que não tem a extensão pdo_mysql habilitada.
Solução: Verifique as permissões do arquivo .env com ls -la .env e confirme que o proprietário é www-data. Reinicie o PHP-FPM com systemctl restart php8.3-fpm e verifique os logs do PHP-FPM em /var/log/php8.3-fpm.log.

Sintoma: SQLSTATE[HY000] [2002] No such file or directory

Causa: O Laravel está tentando conectar via socket Unix, mas o caminho do socket configurado não existe ou está incorreto. Isso acontece quando DB_HOST=localhost está definido no .env mas o socket do MySQL está em um caminho diferente do padrão.
Solução: Confirme o caminho real do socket com mysqladmin -u root -p variables | grep socket. Adicione a variável DB_SOCKET=/var/run/mysqld/mysqld.sock ao .env com o caminho correto e execute php artisan config:clear.

Sintoma: timeout na conexão — "Connection timed out" na porta 3306

Causa: Uma regra de firewall (UFW, iptables ou nftables) está bloqueando a porta 3306, ou o bind-address do MySQL está configurado para um IP que não é acessível pelo Laravel.
Solução: Verifique as regras de firewall com ufw status ou iptables -L -n | grep 3306. Para conexões locais, o firewall não deveria bloquear a porta 3306 em loopback. Se o Laravel e o MySQL estão no mesmo servidor, prefira sempre a conexão via socket Unix para evitar overhead de rede e problemas de firewall.

Sintoma: .env alterado mas o erro persiste

Causa: O Laravel armazena em cache as configurações do .env no arquivo bootstrap/cache/config.php. Alterar o .env sem limpar o cache faz com que o framework continue usando os valores antigos.
Solução: Execute obrigatoriamente php artisan config:clear após qualquer alteração no .env. Se o ambiente de produção usa php artisan config:cache, execute-o novamente após a limpeza para regenerar o cache com os novos valores.

Perguntas frequentes sobre Laravel não conecta ao MySQL no Debian 12

Por que o Laravel retorna SQLSTATE[HY000] [2002] no Debian 12?

Esse erro indica que o PHP não conseguiu abrir o socket Unix ou a conexão TCP com o MySQL. As causas mais comuns são: o serviço MySQL parado, o caminho do socket incorreto no .env, ou o host configurado como 127.0.0.1 quando o MySQL só escuta no socket local. Verifique se o MySQL está ativo com systemctl status mysql e confirme o caminho do socket em /etc/mysql/mysql.conf.d/mysqld.cnf. Após corrigir qualquer parâmetro, sempre execute php artisan config:clear para garantir que o Laravel use as novas configurações.

Como verificar se o MySQL está aceitando conexões no Debian 12?

Execute ss -tlnp | grep 3306 para confirmar se o daemon mysqld está escutando na porta 3306. Se o comando não retornar nada, o MySQL não está ouvindo via TCP — verifique se bind-address está configurado corretamente em mysqld.cnf. Também execute systemctl status mysql para confirmar que o serviço está ativo e sem erros de inicialização. Para conexões via socket, use ss -xlnp | grep mysql para verificar se o socket Unix está disponível.

O Laravel conecta localmente mas não via IP do servidor — o que pode ser?

Quando a conexão funciona pelo socket local mas falha via IP, o problema geralmente é o bind-address do MySQL configurado como 127.0.0.1 (que bloqueia conexões externas) ou uma regra de firewall bloqueando a porta 3306. Além disso, o usuário MySQL precisa ter permissão concedida para o IP de origem específico — não apenas para localhost. Verifique as permissões com SHOW GRANTS FOR 'usuario'@'ip_origem'; dentro do console MySQL.

Como conceder permissão ao usuário MySQL para o Laravel conectar?

Acesse o MySQL como root e execute: GRANT ALL PRIVILEGES ON nome_banco.* TO 'usuario'@'127.0.0.1' IDENTIFIED BY 'senha'; FLUSH PRIVILEGES; Use 127.0.0.1 quando o Laravel conecta via TCP, ou localhost quando usa socket Unix. Se o Laravel rodar em container Docker, substitua pelo IP da rede interna do container. No MySQL 8.0, o comando IDENTIFIED BY dentro do GRANT foi descontinuado — crie o usuário separadamente com CREATE USER antes de executar o GRANT.

O arquivo .env do Laravel está correto mas a conexão ainda falha — o que checar?

Após alterar o .env, execute php artisan config:clear e php artisan cache:clear para invalidar o cache de configuração do Laravel — sem isso, o framework continua usando os valores antigos em cache. Verifique também se o arquivo .env tem permissão de leitura pelo usuário do PHP-FPM (geralmente www-data no Debian) e se não há espaços extras ao redor do sinal de igual nas variáveis DB_*. Use cat -A .env | grep DB_ para visualizar caracteres ocultos que possam estar causando problemas de parsing.

Conclusão

A sequência de diagnóstico para resolver a falha de conexão entre Laravel e MySQL no Debian 12 cobre as causas mais frequentes de forma sistemática. Seguindo os passos deste guia, você consegue identificar e corrigir o problema sem tentativa e erro.

• Sempre verifique o serviço primeiro: confirme com systemctl status mysql antes de qualquer outra investigação — um serviço parado é a causa mais simples e mais ignorada.
• Limpe o cache após cada alteração no .env: execute php artisan config:clear obrigatoriamente para garantir que o Laravel use as configurações atualizadas.
• Alinhe host e permissões: se usar DB_HOST=127.0.0.1, o usuário MySQL deve ter permissão para 127.0.0.1; se usar localhost, a permissão deve ser para localhost — esses dois não são intercambiáveis no MySQL.

Leia também

• Solucionar lentidão no MySQL 8.0 antes que derrube sua aplicação
• Otimizar PHP 8.3 no Debian 12: OPcache, JIT e pool FPM
• Configurar Servidor LAMP no Ubuntu/Debian 2026: Passo a Passo

Precisa de ajuda com Laravel e MySQL no seu servidor?

Configurar e manter um ambiente Laravel com MySQL no Debian 12 exige atenção a detalhes de rede, permissões e configuração do PHP. Um VPS Linux com suporte técnico especializado pode facilitar esse processo, oferecendo ambiente isolado, acesso root completo e recursos dedicados para suas aplicações.

Conheça os planos de VPS da AviraHost e hospede seu projeto Laravel com desempenho e controle total