Cómo Solucionar el Error 'Please upgrade your database' en Magento 2

¿Qué es el error 'Please upgrade your database' en Magento 2?

El error 'Please upgrade your database: Run bin/magento setup:upgrade from the Magento root directory' es uno de los fallos más comunes en Magento 2. Este problema suele presentarse en el frontend o en el panel de administración (admin backend) después de haber instalado un nuevo módulo, actualizado la tienda mediante Composer o realizado una migración de base de datos. Magento detecta que la versión del esquema o de los datos de un módulo declarada en los archivos de configuración no coincide con el registro actual en la base de datos.

Causas comunes del error

• Instalación de nuevos módulos: El módulo se ha descargado pero el sistema aún no ha creado sus tablas en la base de datos.
• Actualización de extensiones: Se ha modificado el archivo de versión del módulo pero la base de datos no se ha actualizado para reflejar este cambio.
• Caché corrupta o desactualizada: Magento sigue leyendo la configuración antigua debido a la caché de configuración o a sistemas como Redis y Varnish.

Método 1: Ejecutar los comandos de actualización por SSH

La solución estándar y más efectiva para resolver este problema es ejecutar la suite de comandos de despliegue de Magento a través de una terminal SSH. Sigue estos pasos detallados:

1. Conéctate a tu servidor web mediante SSH y navega hasta el directorio raíz de tu instalación de Magento 2.
2. Ejecuta el comando de actualización para sincronizar el esquema de la base de datos: bin/magento setup:upgrade
3. Compila las dependencias de código para asegurar que las clases de los nuevos módulos se generen correctamente: bin/magento setup:di:compile
4. Despliega los archivos estáticos necesarios para el correcto funcionamiento de la interfaz visual: bin/magento setup:static-content:deploy -f
5. Limpia la caché del sistema para aplicar todos los cambios de inmediato: bin/magento cache:clean y bin/magento cache:flush

Método 2: Verificar y corregir registros en la base de datos

Si el comando anterior no soluciona el problema, es posible que exista una inconsistencia manual en la base de datos, especialmente en la tabla de registro de módulos instalados. Puedes verificarlo siguiendo estos pasos:

1. Accede al gestor de bases de datos de tu servidor (como phpMyAdmin) y localiza la base de datos de tu tienda Magento.
2. Busca la tabla llamada setup_module. Esta tabla registra el nombre del módulo y su versión instalada.
3. Compara la versión del módulo problemático registrada en la columna schema_version con la versión definida en el archivo etc/module.xml del propio módulo en el código fuente de tu tienda.
4. Si existe una discrepancia, puedes actualizar manualmente el campo de la versión en la tabla para que coincida con el archivo XML, o bien eliminar el registro del módulo en la tabla setup_module para forzar a Magento a reinstalarlo cuando vuelvas a ejecutar el comando bin/magento setup:upgrade.

Método 3: Limpieza profunda de la caché externa (Redis / Varnish)

En entornos de producción optimizados, es muy común que la caché de configuración persista en servicios externos de almacenamiento en caché, impidiendo que Magento reconozca la actualización de la base de datos.

• Si utilizas Redis: Conéctate a tu terminal y vacía la caché de Redis ejecutando el comando: redis-cli flushall
• Si utilizas Varnish: Reinicia el servicio de Varnish en tu servidor para limpiar toda la caché de páginas: sudo systemctl restart varnish