Cuando trabajas con WordPress desde consola, WP-CLI se convierte en una herramienta muy potente para mantener sitios, automatizar tareas y depurar incidencias. Sin embargo, hay un fallo especialmente frustrante: el clásico error de conexión a la base de datos.
Este problema suele aparecer en momentos poco oportunos, justo cuando necesitas ejecutar una actualización, importar contenido o lanzar un comando de mantenimiento. La buena noticia es que, en la mayoría de casos, no se trata de un fallo “misterioso”, sino de una cadena de causas bastante acotadas.
En este artículo veremos cómo diagnosticar y corregir esos errores de conexión en WP-CLI sin repetir los fundamentos ya cubiertos en nuestra guía básica de gestión de WordPress con WP-CLI ni los pasos previos para comprobar si WP-CLI está instalado correctamente.
Qué significa realmente el error
WP-CLI necesita leer la configuración de WordPress para conectarse a MySQL o MariaDB. Si no puede hacerlo, mostrará mensajes que suelen apuntar a una de estas situaciones: credenciales incorrectas, host mal definido, permisos insuficientes o una base de datos no disponible.
En algunos servidores, el recurso está ahí, pero el proceso de consola no tiene el mismo contexto que PHP-FPM o Apache. Eso explica por qué un sitio puede funcionar en el navegador y fallar desde WP-CLI.
También conviene recordar que ciertos comandos, como los relacionados con exportación, importación o búsqueda y reemplazo, dependen directamente de que la conexión esté operativa. Si trabajas frecuentemente con estos flujos, te interesará revisar también nuestros artículos sobre exportar e importar la base de datos con WP-CLI y buscar y reemplazar URLs en WordPress con WP-CLI.
Primer paso: localizar el origen del fallo
Antes de tocar nada, comprueba si el problema es global o solo afecta a un comando concreto. Prueba a ejecutar una consulta sencilla o un comando de información básica con salida detallada.
# Ejecuta WP-CLI con información adicional
wp db check --debug
# Verifica si WordPress resuelve la instalación correctamente
wp core is-installed --debug
El parámetro –debug suele ayudar a distinguir entre un fallo de credenciales, un problema de carga del archivo de configuración o una incidencia del lado del servidor de base de datos.
Revisa el mensaje exacto
No todos los errores “de conexión” significan lo mismo. Un texto como “Access denied” apunta a usuario o contraseña. Un “Unknown database” suele indicar nombre de base de datos erróneo. Y un “Connection refused” puede significar que el servicio no responde o que el host/puerto están mal configurados.
Esa diferencia es importante porque cambia por completo la solución.
Verifica wp-config.php
El archivo wp-config.php es el punto más habitual de incidencia. WP-CLI lo usa para obtener constantes como DB_NAME, DB_USER, DB_PASSWORD y DB_HOST.
Si esos datos no coinciden con la realidad del servidor, la conexión fallará aunque WordPress siga cargando parcialmente en el navegador por caché u otros componentes.
// Ejemplo típico de credenciales en wp-config.php
define('DB_NAME', 'nombre_de_la_base_de_datos');
define('DB_USER', 'usuario_bd');
define('DB_PASSWORD', 'contraseña_segura');
define('DB_HOST', 'localhost');
Comprueba especialmente DB_HOST. En hosting compartido o entornos gestionados, “localhost” no siempre es correcto. A veces se usa una IP interna, un socket Unix o un host remoto específico.
Ojo con configuraciones condicionales
Algunos proyectos modifican el contenido de wp-config.php en función del entorno, por ejemplo desarrollo, staging o producción. Si WP-CLI se ejecuta en un contexto distinto, puede estar leyendo credenciales diferentes de las que esperas.
Esto es frecuente en despliegues automáticos, por lo que conviene revisar la configuración si ya utilizas flujos descritos en despliegues automáticos de WordPress con WP-CLI.
Comprueba la disponibilidad del servidor de base de datos
Si las credenciales son correctas, el siguiente sospechoso es el propio motor de base de datos. MySQL o MariaDB puede estar detenido, saturado o inaccesible desde la shell donde se ejecuta WP-CLI.
En servidores Linux, revisa el servicio con herramientas del sistema. Si administras varios entornos, esta comprobación es especialmente útil antes de pensar en un problema de WordPress.
# Ejemplos genéricos en Linux
sudo systemctl status mysql
sudo systemctl status mariadb
# Comprobar conexión manual desde consola
mysql -u usuario_bd -p -h localhost nombre_de_la_base_de_datos
Si el acceso manual falla, el problema no está en WP-CLI, sino en el servicio o en la red entre aplicación y base de datos.
Revisa permisos del usuario de base de datos
Otro origen muy común son los privilegios insuficientes. El usuario de MySQL puede existir, pero no tener permisos sobre la base de datos concreta o sobre determinadas operaciones.
Esto se nota más al ejecutar comandos que escriben información, como importaciones, optimización de tablas o cambios masivos. Si ya has detectado incidencias similares en servidor, quizá te ayude nuestro artículo sobre problemas de permisos con WP-CLI en Linux, porque muchas veces el síntoma de consola es parecido aunque la causa sea distinta.
Qué permisos suele necesitar WordPress
De forma general, el usuario de la base de datos debe poder leer y escribir en las tablas del sitio. Si trabajas con operaciones de mantenimiento, también es recomendable verificar permisos sobre acciones administrativas asociadas a exportación, importación y alteración de tablas.
Si sospechas de permisos rotos, revisa la concesión de privilegios en MySQL/MariaDB con el administrador del servidor o con el proveedor de hosting.
Confirma que wp-cli está leyendo el entorno correcto
En instalaciones complejas, WP-CLI no siempre se ejecuta desde la misma ruta o usuario que el sitio web. Eso puede hacer que cargue otra instalación, otro archivo de configuración o incluso otra base de datos.
Este punto es especialmente importante en máquinas con múltiples sitios, alias o despliegues por SSH. Si gestionas varios entornos, te conviene revisar también cómo gestionar múltiples instalaciones de WordPress con WP-CLI y cómo ejecutar WP-CLI remotamente por SSH.
# Ver la información del entorno de WordPress
wp eval 'echo DB_HOST . PHP_EOL;'
wp config get DB_NAME
wp config get DB_USER
Estos comandos ayudan a validar qué valores está usando realmente WP-CLI, sin depender de la memoria ni de suposiciones.
Corrige problemas de socket, host o puerto
Un caso típico es el fallo por socket Unix. En algunos servidores, la base de datos escucha por socket local, pero WP-CLI no puede encontrarlo porque la ruta no coincide con la configuración del sistema.
En otros casos, el problema está en el puerto. Aunque MySQL suele usar el 3306 por defecto, no hay garantía de que sea así en tu entorno.
Si el servidor usa un host remoto, una instancia administrada o un contenedor, revisa el valor de DB_HOST y confirma si requiere un puerto explícito, como 127.0.0.1:3306 o una dirección distinta a “localhost”.
Limpia cachés de configuración y revisa plugins que alteren la conexión
Algunos plugins o capas de caché pueden interferir con la forma en que WordPress resuelve valores de configuración. Aunque WP-CLI no depende del navegador, sí puede verse afectado por elementos que alteran el arranque del entorno.
Si sospechas de una configuración inconsistente, conviene vaciar cachés y transients desde consola. Ya explicamos este proceso en cómo limpiar la caché y transients con WP-CLI.
También es recomendable desactivar temporalmente plugins de seguridad, caché o administración de base de datos si el sitio los usa y el entorno lo permite. Una extensión defectuosa puede provocar comportamientos extraños durante el bootstrap de WordPress.
Usa modo depuración para acelerar el diagnóstico
Si el problema persiste, activa un enfoque más metódico. La depuración ayuda a aislar si el fallo ocurre al cargar WordPress, al leer la configuración o al abrir la conexión SQL.
WP-CLI es muy útil para eso porque permite ejecutar pruebas rápidas sin pasar por la interfaz web. Si quieres profundizar en ese enfoque, puedes apoyarte en nuestra guía sobre cómo depurar WordPress con WP-CLI.
En entornos reales, esta combinación de diagnóstico con consola y revisión del entorno suele ser más eficaz que cambiar credenciales a ciegas.
Checklist rápido de solución
Si necesitas ir al grano, sigue este orden:
1. Verifica el mensaje del error con –debug.
2. Comprueba wp-config.php y especialmente DB_HOST.
3. Confirma que MySQL o MariaDB están activos.
4. Revisa permisos del usuario de base de datos.
5. Valida que WP-CLI apunta a la instalación correcta.
6. Descarta conflictos con caché, plugins o configuraciones condicionales.
Conclusión
Los errores de conexión a la base de datos en WP-CLI suelen parecer más graves de lo que son. En realidad, la mayoría se resuelven revisando credenciales, host, permisos, servicio de base de datos y contexto de ejecución.
La clave está en no asumir que el problema es de WP-CLI por defecto. La consola solo está revelando un fallo que puede estar en WordPress, en el servidor o en la infraestructura que los conecta.
Si ya dominas tareas como actualización, copia de seguridad o automatización, resolver este tipo de incidencias te permitirá trabajar con más seguridad y menos interrupciones desde la terminal.
Fuentes y lecturas recomendadas
Documentación oficial de WP-CLI
Comandos de base de datos en WP-CLI
Documentación oficial de MySQL
Deja una respuesta