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

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

Uno de los problemas más frustrantes con los que se encuentran los desarrolladores web al trabajar con PHP y bases de datos relacionales es el error SQLSTATE[HY000] [2002]: Connection refused o No such file or directory. Este código de error indica que PHP está intentando establecer una comunicación con el servidor MySQL, pero la conexión es rechazada de inmediato por el sistema.

Causas Principales del Error de Conexión

• El servicio de MySQL o MariaDB se encuentra detenido o no se ha iniciado correctamente.
• La dirección IP o el puerto de conexión configurados en el archivo de credenciales de PHP son incorrectos.
• Se intenta conectar mediante un socket local (localhost) en lugar de una dirección de red (127.0.0.1), o viceversa.
• Restricciones de seguridad en el archivo de configuración de MySQL (my.cnf o my.ini).

Método 1: Verificar y Reiniciar el Servicio de MySQL

Lo primero que debes comprobar es si el servidor de base de datos está realmente activo en tu máquina local o servidor remoto.

1. Abre tu terminal o consola de comandos con privilegios de administrador.
2. Ejecuta el siguiente comando para verificar el estado de MySQL (en sistemas Linux basados en Ubuntu/Debian): sudo systemctl status mysql
3. Si el servicio está detenido, inicia o reinicia el servidor ejecutando: sudo systemctl restart mysql
4. Intenta cargar tu página o script PHP nuevamente para comprobar si el error ha desaparecido.

Método 2: Cambiar de 'localhost' a '127.0.0.1' en la Cadena de Conexión

A menudo, este error ocurre debido a la forma en que el controlador de PHP (PDO o MySQLi) intenta resolver el host local.

Abre el archivo de configuración de tu conexión (por ejemplo, config.php, database.php o tu archivo .env) y busca la variable correspondiente al host:

// Cambiar esto:
$host = 'localhost';

// Por esto:
$host = '127.0.0.1';

Guardar los cambios y limpiar la caché de tu aplicación resolverá el problema si se trataba de un conflicto en la resolución de sockets UNIX.

Método 3: Comprobar el Puerto de Escucha en la Configuración de MySQL

Si tu servidor MySQL está configurado para escuchar en un puerto distinto al predeterminado (3306), PHP fallará al intentar la conexión estándar.

1. Localiza el archivo de configuración de MySQL (suele estar en /etc/mysql/mysql.conf.d/mysqld.cnf en Linux o en la carpeta de instalación de XAMPP/WAMP en Windows).
2. Busca la directiva port y asegúrate de que esté configurada correctamente: port = 3306
3. Asegúrate de especificar explícitamente este puerto en tu código de conexión de PHP con PDO:

try {
    $pdo = new PDO('mysql:host=127.0.0.1;port=3306;dbname=mi_base_datos', 'usuario', 'contraseña');
} catch (PDOException $e) {
    echo 'Error de conexión: ' . $e->getMessage();
}