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

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

Cuando desarrollas aplicaciones web utilizando PHP y bases de datos MySQL o MariaDB, es muy común encontrarse con excepciones molestas que interrumpen el flujo de trabajo. Uno de los problemas más frecuentes es el Fatal error: Uncaught PDOException: SQLSTATE[HY000] [2002] Connection refused. Este código de error indica que PHP ha intentado establecer comunicación con el servidor de base de datos, pero la conexión ha sido rechazada de inmediato o el servicio no está accesible en el host y puerto especificados.

Causas Principales de la Falta de Conexión

Antes de aplicar cualquier corrección, es fundamental comprender qué origina esta falla en entornos de desarrollo local (como XAMPP, WampServer, Docker) o en servidores de producción VPS:

• El servicio de MySQL o MariaDB se encuentra detenido o no se ha iniciado correctamente.
• Estás intentando conectar la aplicación a través de una dirección IP incorrecta (por ejemplo, usando localhost en lugar de 127.0.0.1, o viceversa).
• El puerto asignado por defecto para MySQL (3306) está ocupado por otra aplicación o bloqueado por un firewall.
• Configuración errónea en el archivo config.php, .env o en los parámetros de inicialización de PDO/mysqli.

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

La causa número uno de este error es que el servidor de base de datos simplemente está apagado. Sigue estos pasos para reactivarlo:

1. Si utilizas un entorno integrado como XAMPP o WampServer, abre el panel de control correspondiente.
2. Comprueba el estado del módulo MySQL. Si está detenido, haz clic en el botón Start.
3. Si trabajas en sistemas Linux (Ubuntu/Debian) mediante terminal, ejecuta el siguiente comando para verificar el estado del servicio:
   sudo systemctl status mysql
4. Si el servicio está inactivo, reinícialo utilizando:
   sudo systemctl restart mysql

Método 2: Cambiar de 'localhost' a la Dirección IP '127.0.0.1'

A veces, la resolución de nombres DNS locales de tu sistema operativo falla al interpretar la palabra clave localhost, intentando conectarse a través del protocolo IPv6 (::1) cuando MySQL solo escucha en IPv4.

1. Abre tu archivo de configuración de conexión a la base de datos (por ejemplo, database.php, conexion.php o tu archivo .env).
2. Busca la variable o constante encargada de definir el host del servidor.
3. Reemplaza el valor localhost por la IP de bucle local 127.0.0.1. Ejemplo en PHP con PDO:
   $pdo = new PDO('mysql:host=127.0.0.1;dbname=mi_base', 'usuario', 'contraseña');
4. Guarda los cambios y recarga tu aplicación en el navegador web.

Método 3: Comprobar el Puerto de Conexión y Archivos de Configuración

Si has cambiado el puerto predeterminado de MySQL o tienes múltiples instancias instaladas, la aplicación buscará en el lugar equivocado.

1. Abre el archivo de configuración global de MySQL, comúnmente llamado my.ini (en Windows) o my.cnf (en Linux).
2. Busca la directiva port y asegúrate de que esté configurada en el puerto estándar 3306 (o el puerto personalizado que estés utilizando).
3. Si especificaste un puerto personalizado en tu base de datos, asegúrate de declararlo explícitamente en tu cadena de conexión de PHP:
   $conexion = new mysqli('127.0.0.1', 'usuario', 'password', 'base', 3307);
4. Limpia la caché de tu framework (si usas Laravel, Symfony o CMS similares) ejecutando php artisan config:clear y prueba nuevamente.