Solución al Error 'Link to database cannot be established' en PrestaShop

Introducción al fallo de enlace con la base de datos en PrestaShop

El mensaje Link to database cannot be established es una de las pantallas de error más críticas que un administrador de PrestaShop (tanto en ramas 1.7 como en PrestaShop 8) puede enfrentar. A diferencia de un error 500 estándar con seguimiento de pila (stack trace) de Symfony, este mensaje es emitido directamente por el núcleo de la clase abstracta de abstracción de bases de datos de PrestaShop (DbMySQLi o DbPDO) antes de que la aplicación pueda siquiera inicializar su contenedor de inyección de dependencias o cargar el frontal.

Cuando este incidente ocurre, la tienda queda completamente fuera de línea, afectando tanto al front-office como al back-office administrativo. A nivel técnico, la función connect() falla al intentar abrir un socket de red o un descriptor Unix hacia el daemon de MySQL o MariaDB. Para solucionar este problema con precisión quirúrgica y evitar tiempos de inactividad prolongados, es imperativo realizar un diagnóstico sistemático que abarque desde los ficheros de configuración del CMS hasta los recursos y privilegios del motor de base de datos en el servidor Linux.

Análisis profundo de las causas raíz del error

Para determinar la solución adecuada, primero debemos categorizar las causas habituales que provocan que PrestaShop pierda el enlace con la base de datos:

• Inconsistencias en las credenciales de conexión: Errores tipográficos en el usuario, contraseña, nombre de la base de datos o prefijo de tabla dentro del archivo de configuración compilado de Symfony.
• Caída o bloqueo del proceso MySQL/MariaDB: El demonio de la base de datos se ha detenido forzosamente debido a falta de memoria RAM (OOM Killer de Linux), agotamiento de espacio en disco en /var/lib/mysql o un bloqueo crítico de tablas.
• Agotamiento de conexiones máximas (Max Connections Reached): El parámetro max_connections de MySQL se ha saturado por peticiones concurrentes, conexiones durmientes (sleep queries) o scripts cron concurrentes que no liberaron sus descriptores.
• Problemas de resolución de host y sockets: Confusión entre conexiones TCP/IP (mediante 127.0.0.1) y sockets locales Unix (mediante localhost), especialmente tras cambios en la configuración de MariaDB o actualizaciones de PHP-FPM.
• Corrupción de tablas InnoDB/MyISAM: Sectores dañados en disco o cierres forzados del sistema que impiden que el motor de almacenamiento monte el espacio de tablas (tablespace).

Método 1: Verificación y ajuste del archivo parameters.php

En PrestaShop 1.7 y 8.x, los parámetros de conexión ya no residen en el antiguo settings.inc.php, sino en la configuración gestionada por Symfony. Debes verificar la integridad de este archivo mediante una conexión SSH o gestor SFTP.

1. Accede al directorio raíz de tu tienda PrestaShop.
2. Navega hasta la ruta app/config/parameters.php y abre el archivo con un editor de texto plano (como nano o vim).
3. Examina detenidamente el array de configuración retornado:

<?php
return array (
  'parameters' => 
  array (
    'database_host' => '127.0.0.1',
    'database_port' => '3306',
    'database_name' => 'prestashop_db',
    'database_user' => 'prestashop_user',
    'database_password' => 'TuPasswordSeguro123!',
    'database_prefix' => 'ps_',
    'database_engine' => 'InnoDB',
    // ... resto de parámetros
  );
);

Ajuste crítico de localhost vs 127.0.0.1

Si el parámetro database_host está definido como 'localhost', el cliente PHP intentará conectarse mediante un socket Unix (normalmente ubicado en /var/run/mysqld/mysqld.sock). Si la ruta del socket en php.ini no coincide exactamente con la directiva socket de MariaDB/MySQL, la conexión fallará. Cambiar 'database_host' => 'localhost' por 'database_host' => '127.0.0.1' fuerza al sistema a utilizar la pila TCP/IP, resolviendo de inmediato discrepancias en descriptores de socket.

Método 2: Diagnóstico del estado del servicio y recursos del servidor

Si la configuración es correcta pero el error persiste, es momento de comprobar si el servicio MySQL está en ejecución o si ha sufrido un colapso.

1. Ejecuta el siguiente comando para revisar el estado del servicio:

systemctl status mariadb
# O en su defecto:
systemctl status mysql

Si el servicio figura como inactive (dead) o failed, inicia el servicio y revisa los logs de inicio:

sudo systemctl start mariadb
journalctl -xeu mariadb.service

Comprobación del OOM Killer y espacio en disco

Un escenario sumamente frecuente en servidores VPS con recursos ajustados es que el Out-Of-Memory Killer de Linux haya terminado el proceso de base de datos para salvar el núcleo del sistema. Puedes verificar si esto ha sucedido inspeccionando el buffer de mensajes del kernel:

dmesg -T | grep -i -E 'killed process|oom_reaper|mysql'

Asimismo, comprueba que el almacenamiento del servidor no esté al 100% de su capacidad. MySQL se bloquea automáticamente en modo de solo lectura o detiene sus procesos si no puede escribir en los ficheros temporales o binlogs:

df -h

Método 3: Prueba directa de conexión CLI y auditoría de privilegios

Para aislar si el problema radica en PrestaShop o en el propio motor de bases de datos, emula la conexión de la tienda desde la línea de comandos utilizando las mismas credenciales extraídas de parameters.php:

mysql -u prestashop_user -p -h 127.0.0.1 -P 3306 prestashop_db

Si la consola rechaza la conexión con un error Access denied for user, los permisos del usuario han sido revocados o alterados. Conéctate como superusuario (root) a MySQL y restaura los privilegios:

mysql -u root -p

-- Dentro del prompt de MySQL:
GRANT ALL PRIVILEGES ON prestashop_db.* TO 'prestashop_user'@'127.0.0.1' IDENTIFIED BY 'TuPasswordSeguro123!';
GRANT ALL PRIVILEGES ON prestashop_db.* TO 'prestashop_user'@'localhost' IDENTIFIED BY 'TuPasswordSeguro123!';
FLUSH PRIVILEGES;
EXIT;

Método 4: Reparación de tablas y purga de caché de Symfony

En ocasiones, un fallo imprevisto del suministro eléctrico o un reinicio no sincronizado del servidor causa la corrupción de tablas transaccionales o bloqueos a nivel de caché interna que retienen estados de conexión erróneos.

Reparación y chequeo de consistencia de la base de datos

Ejecuta la utilidad de mantenimiento para todas las tablas de tu esquema PrestaShop:

mysqlcheck -u root -p --auto-repair --check --optimize prestashop_db

Eliminación de la caché residual del contenedor de PrestaShop

PrestaShop almacena en caché las credenciales y el estado de los servicios en su directorio de compilación de Symfony. Si has corregido la base de datos pero el error sigue visible en el navegador, debes purgar manualmente la caché desde la terminal:

cd /var/www/html/prestashop
rm -rf var/cache/prod/*
rm -rf var/cache/dev/*

Activación del Modo Debug para diagnósticos en profundidad

Si tras implementar las soluciones anteriores el mensaje sigue mostrándose, habilita el modo depuración de PrestaShop para obtener la traza de excepción exacta de PDO. Abre el archivo config/defines.inc.php y localiza la siguiente línea:

/* Define el modo de depuración */
if (!defined('_PS_MODE_DEV_')) {
    define('_PS_MODE_DEV_', false);
}

Modifica el valor booleano a true:

if (!defined('_PS_MODE_DEV_')) {
    define('_PS_MODE_DEV_', true);
}

Al recargar la página, PrestaShop reemplazará el mensaje genérico por un informe detallado indicando el código de error SQL exacto (como SQLSTATE[HY000] [2002] Connection refused o Too many connections), lo que te permitirá aplicar la corrección definitiva según el fallo particular de infraestructura reportado.