Error de conexión a base de datos en PrestaShop: Solución cPanel

¡Hola! Soy tu técnico de soporte amigable. Si estás aquí, es porque tu tienda PrestaShop ha dejado de funcionar y ves un mensaje de error similar a "Error de conexión a la base de datos", "No se puede conectar con la base de datos" o "MySQL error". No te preocupes, es uno de los problemas más comunes y, con esta guía paso a paso, lo resolveremos juntos. Vamos a desglosar las causas y soluciones para que vuelvas a vender en minutos.

¿Por qué ocurre el error de conexión a la base de datos en PrestaShop?

El error conexión PrestaShop es como si tu tienda intentara abrir la puerta de su almacén de productos, clientes y pedidos (la base de datos), pero la llave no funciona o la puerta está cerrada con llave desde dentro. Las causas más frecuentes son:

Credenciales incorrectas: El archivo de configuración de PrestaShop (settings.inc.php) tiene usuario, contraseña o nombre de base de datos equivocados.
Servidor MySQL caído o sobrecargado: El motor de base de datos se ha detenido o está saturado.
Problemas de permisos: El usuario de la base de datos no tiene acceso a la base de datos correcta.
Cambios en cPanel: Al migrar, restaurar o actualizar, las credenciales pueden cambiar.
Firewall o IP bloqueada: Tu servidor puede estar bloqueando la conexión desde el script de PrestaShop.

Vamos a solucionarlo. Te guiaré usando PrestaShop cPanel, que es el panel de control más común en hosting compartido.

Paso 1: Identificar el error exacto (antes de tocar nada)

Antes de modificar archivos, necesitas saber qué tipo de error de MySQL estás viendo. Activa el modo debug de PrestaShop para obtener más detalles.

### Activar modo debug en PrestaShop

Accede a tu cPanel y busca el Administrador de archivos (File Manager).
Navega hasta la carpeta raíz de tu tienda (normalmente public_html o el nombre de tu dominio).
Busca el archivo config/defines.inc.php. Ábrelo con el editor de texto.
Localiza la línea que dice: define('_PS_MODE_DEV_', false);
Cámbiala a: define('_PS_MODE_DEV_', true);
Guarda los cambios. Ahora, al recargar tu tienda, verás un mensaje de error más detallado, como:
- SQLSTATE[HY000] [1045] Access denied for user (credenciales incorrectas)
- SQLSTATE[HY000] [2002] Connection refused (MySQL no está corriendo)
- SQLSTATE[HY000] [1049] Unknown database (la base de datos no existe)

Anota ese código de error. Te servirá para saber qué solución aplicar.

[TIP] Si no ves el error detallado, revisa que hayas guardado bien el archivo. Si el error persiste, vuelve a poner false después de solucionarlo por seguridad.

Paso 2: Soluciones según el código de error

### Error 1045: Acceso denegado (credenciales incorrectas)

Este es el más común. Significa que el usuario o contraseña que PrestaShop está usando no coincide con lo que tiene MySQL.

Solución: Verificar y actualizar credenciales en settings.inc.php

En el Administrador de archivos de cPanel, ve a app/config/parameters.php (PrestaShop 1.7+) o config/settings.inc.php (PrestaShop 1.6).

Abre el archivo con el editor de texto. Busca estas líneas (en 1.7):

'database_host' => 'localhost',
'database_port' => '',
'database_name' => 'tu_base_de_datos',
'database_user' => 'tu_usuario',
'database_password' => 'tu_contraseña',

O en 1.6:

define('_DB_SERVER_', 'localhost');
define('_DB_NAME_', 'tu_base_de_datos');
define('_DB_USER_', 'tu_usuario');
define('_DB_PASS_', 'tu_contraseña');

Ahora ve a cPanel y busca Bases de datos MySQL (o MySQL Databases).
Allí verás la lista de bases de datos y usuarios. Anota el nombre exacto de tu base de datos y el usuario asignado.
Si no recuerdas la contraseña, puedes cambiar la contraseña del usuario desde el mismo cPanel (opción "Change Password").
Copia esos datos exactamente en el archivo de configuración. Cuidado con mayúsculas, minúsculas y espacios.
Guarda el archivo y recarga tu tienda.

[WARNING] Si usas contraseñas con caracteres especiales como $, & o ', escápalos con una barra invertida (\) o cámbiala por una más simple temporalmente.

### Error 2002: Conexión rechazada (MySQL no responde)

Este error indica que el servidor MySQL no está funcionando o no acepta conexiones.

Solución: Reiniciar MySQL desde cPanel

En cPanel, busca la sección Servicios o MySQL. A veces está en "Advanced" o "Software".
Busca la opción "Restart MySQL" o "Start/Stop MySQL". Si no la ves, contacta a tu proveedor de hosting (hosting compartido a veces no permite reiniciar).
Si tienes acceso SSH (o tu hosting lo permite), puedes ejecutar:
```
sudo systemctl restart mysql
```
(o mariadb si usas MariaDB).
Espera 10 segundos y recarga tu tienda.

[INFO] Si el error persiste, puede ser que el servidor esté sobrecargado. En ese caso, contacta a soporte técnico de tu hosting.

### Error 1049: Base de datos desconocida

La base de datos que PrestaShop intenta usar no existe. Esto suele pasar después de una migración o restauración.

Solución: Crear o renombrar la base de datos

Ve a Bases de datos MySQL en cPanel.
Si la base de datos que necesitas no aparece en la lista, créala con el nombre exacto que aparece en settings.inc.php o parameters.php.
Luego, asigna el usuario correcto a esa base de datos (marcando todos los permisos).
Si la base de datos existe pero con otro nombre, puedes:
- Opción A: Cambiar el nombre en el archivo de configuración para que coincida.
- Opción B: Usar phpMyAdmin para exportar la base de datos antigua e importarla a la nueva con el nombre correcto.

### Error de permisos: "Access denied for user" a pesar de credenciales correctas

A veces el usuario existe y la contraseña es correcta, pero no tiene permisos sobre la base de datos.

Solución: Verificar y otorgar permisos

En Bases de datos MySQL de cPanel, busca la sección "Add User to Database".
Asegúrate de que el usuario esté añadido a la base de datos correcta.
Marca "ALL PRIVILEGES" (todos los privilegios) y guarda.
También puedes hacerlo desde phpMyAdmin: selecciona la base de datos, ve a la pestaña "Privilegios" y edita el usuario para darle todos los permisos.

Paso 3: Verificar el archivo de configuración de PrestaShop (el corazón del problema)

A veces, el error conexión PrestaShop se debe a que el archivo de configuración está dañado o tiene saltos de línea extraños.

### Revisar sintaxis del archivo

Abre app/config/parameters.php (1.7) o config/settings.inc.php (1.6) con un editor de texto plano (no Word).
Busca comillas simples o dobles sin cerrar, o puntos y comas faltantes.
Si ves algo como 'database_password' => 'mi_clave', asegúrate de que no haya un ' extra.
Si el archivo está muy dañado, puedes descargar una copia limpia de PrestaShop (misma versión) y reemplazar solo ese archivo, luego editar las credenciales.

[WARNING] Nunca uses un editor de texto enriquecido (como WordPad o Word) para editar estos archivos, ya que pueden añadir caracteres ocultos.

Paso 4: Comprobar la configuración de MySQL en cPanel (host y puerto)

Aunque la mayoría de los hosting usan localhost como servidor de base de datos, algunos usan una IP o un nombre de host específico. Además, el puerto puede ser diferente (por ejemplo, 3306 o 3307).

### Dónde encontrar el host y puerto correctos

En cPanel, busca Bases de datos MySQL y en la parte superior verás algo como: "El servidor MySQL es: localhost" o "mysql.tudominio.com".
Si no aparece, contacta a tu proveedor.
En tu archivo de configuración, asegúrate de que database_host coincida. Si es localhost, déjalo así. Si es una IP, pónla.
El puerto suele estar vacío (usa el predeterminado 3306). Si tu hosting usa otro, agrégalo: 'database_port' => '3307'.

Paso 5: Probar la conexión manualmente (diagnóstico avanzado)

Si aún no funciona, podemos probar la conexión directamente desde el servidor.

### Usar un script de prueba

Crea un archivo llamado testdb.php en la raíz de tu tienda (por FTP o File Manager).

Pega este código:

<?php
$host = 'localhost'; // Cámbialo si es necesario
$user = 'tu_usuario';
$pass = 'tu_contraseña';
$db = 'tu_base_de_datos';
$conn = new mysqli($host, $user, $pass, $db);
if ($conn->connect_error) {
    die("Error de conexión: " . $conn->connect_error);
} else {
    echo "Conexión exitosa a la base de datos.";
}
$conn->close();
?>

Ejecuta el archivo desde tu navegador: tudominio.com/testdb.php.
Si ves "Conexión exitosa", el problema está en PrestaShop (archivo de configuración mal escrito). Si ves otro error, el problema es de MySQL o cPanel.
Borra este archivo después de la prueba por seguridad.

Paso 6: Soluciones adicionales para casos especiales

### Después de migrar o restaurar una copia de seguridad

Si acabas de migrar tu tienda a un nuevo hosting, es muy común que las credenciales hayan cambiado. Asegúrate de:

Actualizar parameters.php o settings.inc.php con los nuevos datos de la base de datos del nuevo hosting.
Verificar que la base de datos esté importada correctamente (desde phpMyAdmin).
Limpiar la caché de PrestaShop: elimina la carpeta var/cache/ (1.7) o cache/ (1.6) a través de FTP.

### Error de versión de PHP incompatible

PrestaShop requiere una versión específica de PHP. Si tu hosting actualizó PHP y tu PrestaShop es antiguo, puede dar error de conexión.

En cPanel, busca Select PHP Version (o MultiPHP Manager).
Cambia la versión de PHP a una compatible con tu PrestaShop (por ejemplo, 7.4 para PrestaShop 1.7, o 5.6 para versiones muy antiguas).
Guarda y prueba.

[INFO] Consulta la documentación de PrestaShop para saber qué versión de PHP necesitas.

Preguntas frecuentes (FAQ) sobre el error de conexión a base de datos en PrestaShop

P: ¿Qué hago si no tengo acceso a cPanel?
R: Contacta a tu proveedor de hosting. Ellos pueden verificar las credenciales y reiniciar MySQL por ti. También puedes pedirles que te den acceso temporal a cPanel.

P: ¿Puedo perder datos si cambio las credenciales?
R: No, cambiar el usuario y contraseña en el archivo de configuración solo afecta la conexión. Tus productos, clientes y pedidos están seguros en la base de datos.

P: ¿Por qué mi hosting cambió la contraseña de la base de datos sin avisar?
R: Algunos hosting rotan contraseñas por seguridad. Revisa tu correo o el panel de control para ver si hay cambios recientes.

P: El error aparece después de instalar un módulo. ¿Qué hago?
R: Desactiva el módulo desde la base de datos (phpMyAdmin, tabla ps_module) o elimínalo por FTP. Luego limpia la caché.

P: ¿Debo usar localhost o 127.0.0.1?
R: Generalmente localhost funciona. Si no, prueba 127.0.0.1. En algunos hosting con configuraciones especiales, puede ser necesario usar la IP del servidor.

Resumen: checklist rápida para solucionar el error

✅ Activar modo debug para ver el código exacto.
✅ Verificar credenciales en parameters.php o settings.inc.php.
✅ Comprobar que MySQL esté corriendo (reiniciar si es necesario).
✅ Asegurar que el usuario tenga permisos sobre la base de datos.
✅ Probar conexión con script manual.
✅ Limpiar caché de PrestaShop.
✅ Contactar a soporte si nada funciona.

Si has seguido todos los pasos y el error persiste, probablemente sea un problema del servidor (firewall, recursos, etc.). En ese caso, tu hosting debe intervenir. Pero no te desanimes: el 90% de los casos se resuelven con los pasos 1 al 4.

Espero que esta guía te haya sido de gran ayuda. Recuerda que siempre puedes consultar la documentación oficial de PrestaShop o preguntar en foros especializados. ¡Tu tienda online volverá a funcionar en poco tiempo!