Cómo Solucionar el Error SQLSTATE[HY000] [2002] en PHP Paso a Paso

Introducción al Error SQLSTATE[HY000] [2002]

Durante el desarrollo web con PHP y bases de datos MySQL o MariaDB, es muy común encontrarse con excepciones inesperadas que detienen por completo la ejecución de la aplicación. Uno de los problemas más frustrantes es el código SQLSTATE[HY000] [2002]: Connection refused o No such file or directory. Este fallo interrumpe la comunicación entre tu script PHP y el servidor de base de datos, impidiendo que la web cargue correctamente.

¿Cuáles son las causas principales de este error?

Este problema de conexión suele estar provocado por una configuración incorrecta en los parámetros de acceso o por fallos en el servicio del gestor de base de datos. Entre las causas más frecuentes destacan:

• El servidor MySQL o MariaDB no está en ejecución en la máquina local o remota.
• La dirección IP o el puerto especificado en la cadena de conexión de PHP son erróneos (por ejemplo, usar localhost en lugar de 127.0.0.1).
• Problemas con los permisos de acceso del usuario de la base de datos o restricciones en el archivo my.cnf.

Método 1: Verificar y reiniciar el servicio de MySQL o MariaDB

El primer paso y el más sencillo consiste en comprobar si el servidor de base de datos se encuentra activo. Muchas veces, tras un reinicio del sistema o un fallo inesperado, el servicio se detiene.

1. Abre tu terminal de comandos (en Linux o macOS) o la consola de administración en Windows.
2. Ejecuta el comando para verificar el estado del servicio: sudo systemctl status mysql (o mariadb).
3. Si el servicio aparece detenido, inícialo ejecutando: sudo systemctl start mysql.
4. Habilita el inicio automático para evitar futuros inconvenientes: sudo systemctl enable mysql.

Método 2: Cambiar de 'localhost' a '127.0.0.1' en tu cadena de conexión

Un error clásico en entornos de desarrollo local (como XAMPP, WAMP o Docker) ocurre al definir el host. PHP suele interpretar localhost intentando conectarse a través de un socket Unix, lo cual falla si el servicio escucha en un puerto TCP específico.

1. Localiza el archivo de configuración de tu conexión a la base de datos (por ejemplo, database.php, config.php o el archivo .env).
2. Busca la variable encargada de definir el host, normalmente llamada DB_HOST o $servername.
3. Modifica el valor de localhost por la dirección IP de bucle local 127.0.0.1.
4. Guarda los cambios y recarga tu aplicación web en el navegador para comprobar si la conexión se ha restablecido exitosamente.

Método 3: Comprobar el puerto de escucha y el archivo de configuración

Si el problema persiste, es probable que MySQL no esté operando en el puerto predeterminado (3306) o que exista un bloqueo por parte de un firewall.

1. Abre el archivo de configuración de MySQL, ubicado habitualmente en /etc/mysql/my.cnf o en la ruta de tu entorno local.
2. Verifica la directiva port = 3306 y asegúrate de que coincida con el puerto configurado en tu script PHP.
3. Si has realizado modificaciones, reinicia nuevamente el servicio de la base de datos para aplicar los cambios de configuración.