Aprende a diagnosticar y resolver errores de conexi\u00f3n a la base de datos en WP-CLI con comprobaciones, permisos, credenciales y ejemplos pr\u00e1cticos.<\/p>\n
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\u00e1sico error de conexi\u00f3n a la base de datos.<\/p>\n
Este problema suele aparecer en momentos poco oportunos, justo cuando necesitas ejecutar una actualizaci\u00f3n, importar contenido o lanzar un comando de mantenimiento. La buena noticia es que, en la mayor\u00eda de casos, no se trata de un fallo \u201cmisterioso\u201d, sino de una cadena de causas bastante acotadas.<\/p>\n
En este art\u00edculo veremos c\u00f3mo diagnosticar y corregir esos errores de conexi\u00f3n en WP-CLI sin repetir los fundamentos ya cubiertos en nuestra gu\u00eda b\u00e1sica de gesti\u00f3n de WordPress con WP-CLI<\/a> ni los pasos previos para comprobar si WP-CLI est\u00e1 instalado correctamente<\/a>.<\/p>\n WP-CLI necesita leer la configuraci\u00f3n de WordPress para conectarse a MySQL o MariaDB. Si no puede hacerlo, mostrar\u00e1 mensajes que suelen apuntar a una de estas situaciones: credenciales incorrectas, host mal definido, permisos insuficientes o una base de datos no disponible.<\/p>\n En algunos servidores, el recurso est\u00e1 ah\u00ed, pero el proceso de consola no tiene el mismo contexto que PHP-FPM o Apache. Eso explica por qu\u00e9 un sitio puede funcionar en el navegador y fallar desde WP-CLI.<\/p>\n Tambi\u00e9n conviene recordar que ciertos comandos, como los relacionados con exportaci\u00f3n, importaci\u00f3n o b\u00fasqueda y reemplazo, dependen directamente de que la conexi\u00f3n est\u00e9 operativa. Si trabajas frecuentemente con estos flujos, te interesar\u00e1 revisar tambi\u00e9n nuestros art\u00edculos sobre exportar e importar la base de datos con WP-CLI<\/a> y buscar y reemplazar URLs en WordPress con WP-CLI<\/a>.<\/p>\n 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\u00f3n b\u00e1sica con salida detallada.<\/p>\n El par\u00e1metro –debug<\/strong> suele ayudar a distinguir entre un fallo de credenciales, un problema de carga del archivo de configuraci\u00f3n o una incidencia del lado del servidor de base de datos.<\/p>\n No todos los errores \u201cde conexi\u00f3n\u201d significan lo mismo. Un texto como \u201cAccess denied\u201d apunta a usuario o contrase\u00f1a. Un \u201cUnknown database\u201d suele indicar nombre de base de datos err\u00f3neo. Y un \u201cConnection refused\u201d puede significar que el servicio no responde o que el host\/puerto est\u00e1n mal configurados.<\/p>\n Esa diferencia es importante porque cambia por completo la soluci\u00f3n.<\/p>\n El archivo wp-config.php<\/strong> es el punto m\u00e1s habitual de incidencia. WP-CLI lo usa para obtener constantes como DB_NAME<\/strong>, DB_USER<\/strong>, DB_PASSWORD<\/strong> y DB_HOST<\/strong>.<\/p>\n Si esos datos no coinciden con la realidad del servidor, la conexi\u00f3n fallar\u00e1 aunque WordPress siga cargando parcialmente en el navegador por cach\u00e9 u otros componentes.<\/p>\n Comprueba especialmente DB_HOST<\/strong>. En hosting compartido o entornos gestionados, \u201clocalhost\u201d no siempre es correcto. A veces se usa una IP interna, un socket Unix o un host remoto espec\u00edfico.<\/p>\n Algunos proyectos modifican el contenido de wp-config.php<\/strong> en funci\u00f3n del entorno, por ejemplo desarrollo, staging o producci\u00f3n. Si WP-CLI se ejecuta en un contexto distinto, puede estar leyendo credenciales diferentes de las que esperas.<\/p>\n Esto es frecuente en despliegues autom\u00e1ticos, por lo que conviene revisar la configuraci\u00f3n si ya utilizas flujos descritos en despliegues autom\u00e1ticos de WordPress con WP-CLI<\/a>.<\/p>\n 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.<\/p>\n En servidores Linux, revisa el servicio con herramientas del sistema. Si administras varios entornos, esta comprobaci\u00f3n es especialmente \u00fatil antes de pensar en un problema de WordPress.<\/p>\n Si el acceso manual falla, el problema no est\u00e1 en WP-CLI, sino en el servicio o en la red entre aplicaci\u00f3n y base de datos.<\/p>\n Otro origen muy com\u00fan son los privilegios insuficientes. El usuario de MySQL puede existir, pero no tener permisos sobre la base de datos concreta o sobre determinadas operaciones.<\/p>\n Esto se nota m\u00e1s al ejecutar comandos que escriben informaci\u00f3n, como importaciones, optimizaci\u00f3n de tablas o cambios masivos. Si ya has detectado incidencias similares en servidor, quiz\u00e1 te ayude nuestro art\u00edculo sobre problemas de permisos con WP-CLI en Linux<\/a>, porque muchas veces el s\u00edntoma de consola es parecido aunque la causa sea distinta.<\/p>\n 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\u00e9n es recomendable verificar permisos sobre acciones administrativas asociadas a exportaci\u00f3n, importaci\u00f3n y alteraci\u00f3n de tablas.<\/p>\n Si sospechas de permisos rotos, revisa la concesi\u00f3n de privilegios en MySQL\/MariaDB con el administrador del servidor o con el proveedor de hosting.<\/p>\n 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\u00f3n, otro archivo de configuraci\u00f3n o incluso otra base de datos.<\/p>\n Este punto es especialmente importante en m\u00e1quinas con m\u00faltiples sitios, alias o despliegues por SSH. Si gestionas varios entornos, te conviene revisar tambi\u00e9n c\u00f3mo gestionar m\u00faltiples instalaciones de WordPress con WP-CLI<\/a> y c\u00f3mo ejecutar WP-CLI remotamente por SSH<\/a>.<\/p>\n Estos comandos ayudan a validar qu\u00e9 valores est\u00e1 usando realmente WP-CLI, sin depender de la memoria ni de suposiciones.<\/p>\n Un caso t\u00edpico 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\u00f3n del sistema.<\/p>\n En otros casos, el problema est\u00e1 en el puerto. Aunque MySQL suele usar el 3306 por defecto, no hay garant\u00eda de que sea as\u00ed en tu entorno.<\/p>\n Si el servidor usa un host remoto, una instancia administrada o un contenedor, revisa el valor de DB_HOST<\/strong> y confirma si requiere un puerto expl\u00edcito, como 127.0.0.1:3306<\/strong> o una direcci\u00f3n distinta a \u201clocalhost\u201d.<\/p>\n Algunos plugins o capas de cach\u00e9 pueden interferir con la forma en que WordPress resuelve valores de configuraci\u00f3n. Aunque WP-CLI no depende del navegador, s\u00ed puede verse afectado por elementos que alteran el arranque del entorno.<\/p>\n Si sospechas de una configuraci\u00f3n inconsistente, conviene vaciar cach\u00e9s y transients desde consola. Ya explicamos este proceso en c\u00f3mo limpiar la cach\u00e9 y transients con WP-CLI<\/a>.<\/p>\n Tambi\u00e9n es recomendable desactivar temporalmente plugins de seguridad, cach\u00e9 o administraci\u00f3n de base de datos si el sitio los usa y el entorno lo permite. Una extensi\u00f3n defectuosa puede provocar comportamientos extra\u00f1os durante el bootstrap de WordPress.<\/p>\n Si el problema persiste, activa un enfoque m\u00e1s met\u00f3dico. La depuraci\u00f3n ayuda a aislar si el fallo ocurre al cargar WordPress, al leer la configuraci\u00f3n o al abrir la conexi\u00f3n SQL.<\/p>\n WP-CLI es muy \u00fatil para eso porque permite ejecutar pruebas r\u00e1pidas sin pasar por la interfaz web. Si quieres profundizar en ese enfoque, puedes apoyarte en nuestra gu\u00eda sobre c\u00f3mo depurar WordPress con WP-CLI<\/a>.<\/p>\n En entornos reales, esta combinaci\u00f3n de diagn\u00f3stico con consola y revisi\u00f3n del entorno suele ser m\u00e1s eficaz que cambiar credenciales a ciegas.<\/p>\n Si necesitas ir al grano, sigue este orden:<\/p>\n 1.<\/strong> Verifica el mensaje del error con –debug<\/strong>.<\/p>\n 2.<\/strong> Comprueba wp-config.php<\/strong> y especialmente DB_HOST<\/strong>.<\/p>\n 3.<\/strong> Confirma que MySQL o MariaDB est\u00e1n activos.<\/p>\n 4.<\/strong> Revisa permisos del usuario de base de datos.<\/p>\n 5.<\/strong> Valida que WP-CLI apunta a la instalaci\u00f3n correcta.<\/p>\n 6.<\/strong> Descarta conflictos con cach\u00e9, plugins o configuraciones condicionales.<\/p>\n Los errores de conexi\u00f3n a la base de datos en WP-CLI suelen parecer m\u00e1s graves de lo que son. En realidad, la mayor\u00eda se resuelven revisando credenciales, host, permisos, servicio de base de datos y contexto de ejecuci\u00f3n.<\/p>\n La clave est\u00e1 en no asumir que el problema es de WP-CLI por defecto. La consola solo est\u00e1 revelando un fallo que puede estar en WordPress, en el servidor o en la infraestructura que los conecta.<\/p>\n Si ya dominas tareas como actualizaci\u00f3n, copia de seguridad o automatizaci\u00f3n, resolver este tipo de incidencias te permitir\u00e1 trabajar con m\u00e1s seguridad y menos interrupciones desde la terminal.<\/p>\n Documentaci\u00f3n oficial de WP-CLI<\/a><\/p>\nQu\u00e9 significa realmente el error<\/h2>\n
Primer paso: localizar el origen del fallo<\/h2>\n
# Ejecuta WP-CLI con informaci\u00f3n adicional\nwp db check --debug\n\n# Verifica si WordPress resuelve la instalaci\u00f3n correctamente\nwp core is-installed --debug\n<\/code><\/pre>\nRevisa el mensaje exacto<\/h3>\n
Verifica wp-config.php<\/h2>\n
\/\/ Ejemplo t\u00edpico de credenciales en wp-config.php\ndefine('DB_NAME', 'nombre_de_la_base_de_datos');\ndefine('DB_USER', 'usuario_bd');\ndefine('DB_PASSWORD', 'contrase\u00f1a_segura');\ndefine('DB_HOST', 'localhost');\n<\/code><\/pre>\nOjo con configuraciones condicionales<\/h3>\n
Comprueba la disponibilidad del servidor de base de datos<\/h2>\n
# Ejemplos gen\u00e9ricos en Linux\nsudo systemctl status mysql\nsudo systemctl status mariadb\n\n# Comprobar conexi\u00f3n manual desde consola\nmysql -u usuario_bd -p -h localhost nombre_de_la_base_de_datos\n<\/code><\/pre>\nRevisa permisos del usuario de base de datos<\/h2>\n
Qu\u00e9 permisos suele necesitar WordPress<\/h3>\n
Confirma que wp-cli est\u00e1 leyendo el entorno correcto<\/h2>\n
# Ver la informaci\u00f3n del entorno de WordPress\nwp eval 'echo DB_HOST . PHP_EOL;'\nwp config get DB_NAME\nwp config get DB_USER\n<\/code><\/pre>\nCorrige problemas de socket, host o puerto<\/h2>\n
Limpia cach\u00e9s de configuraci\u00f3n y revisa plugins que alteren la conexi\u00f3n<\/h2>\n
Usa modo depuraci\u00f3n para acelerar el diagn\u00f3stico<\/h2>\n
Checklist r\u00e1pido de soluci\u00f3n<\/h2>\n
Conclusi\u00f3n<\/h2>\n
Fuentes y lecturas recomendadas<\/h3>\n