Logo
WP Fix by Blimx

Anatomía del 'Error Establishing a Database Connection' en WordPress

Actualizado:
DatabaseDiagnostics

El error que todos temen

Refrescas tu sitio WordPress y en lugar de tu home page, ves esto:

Error establishing a database connection

Nada más. Sin stack trace, sin línea de log, sin pista sobre qué está mal. Este es el mensaje de error más temido en WordPress — y el más malentendido. Casi siempre tiene una de cinco causas específicas, y una vez que sabes cómo mirar, encuentras la causa en menos de 5 minutos.

Este artículo recorre lo que el error realmente significa, las cinco causas técnicas, el flujo diagnóstico que usamos, y cómo prevenir que vuelva a ocurrir.

Lo que el error realmente significa

Cuando WordPress arranca, lo primerísimo que intenta hacer es conectarse a MySQL. La conexión usa cuatro piezas de información de tu archivo wp-config.php:

define('DB_HOST', 'localhost');
define('DB_USER', 'wp_user');
define('DB_PASSWORD', 'pass123');
define('DB_NAME', 'wordpress_db');

WordPress las pasa a la extensión MySQLi de PHP. Si algo falla — credenciales equivocadas, MySQL no corriendo, red inalcanzable, demasiadas conexiones existentes — PHP devuelve un error y WordPress lo atrapa y muestra el mensaje genérico "Error establishing a database connection".

La generalidad es deliberada. Filtrar el error real a los visitantes ayudaría a los atacantes. El error real está en el log del servidor; los visitantes solo ven el genérico.

Causa 1 — Credenciales equivocadas

La causa más común por mucho. Uno de DB_HOST, DB_USER, DB_PASSWORD o DB_NAME ya no coincide con lo que MySQL acepta.

Cuándo pasa

  • Alguien rotó la contraseña MySQL pero olvidó actualizar wp-config.php
  • Una migración a un hosting nuevo donde las credenciales son diferentes
  • Un panel de hosting auto-rotó credenciales por seguridad
  • Un typo introducido durante una edición manual de wp-config.php
  • Restauración de archivos desde un backup tomado cuando las credenciales eran diferentes

Cómo verificar

Conéctate a MySQL directamente con las mismas credenciales desde el mismo servidor:

mysql -h $DB_HOST -u $DB_USER -p$DB_PASSWORD -D $DB_NAME

Si este comando tiene éxito, las credenciales son correctas y el problema es otro. Si falla, sabes cuál credencial está mal por el mensaje (Access denied for user..., Unknown database...).

Arreglo

Actualiza wp-config.php con los valores correctos. Si no sabes los valores correctos, consíguelos del panel del hosting (cPanel → Bases de datos MySQL) o de tu password manager.

Causa 2 — MySQL no está corriendo

El servicio MySQL en sí está caído. Menos común que problemas de credenciales, pero más dramático.

Cuándo pasa

  • Servidor sin memoria y el OOM killer de Linux terminó MySQL
  • Un crash de MySQL causado por un tablespace InnoDB corrupto
  • systemctl stop mysql manual seguido de olvido de reiniciar
  • Una condición de disco lleno impidiendo que MySQL escriba
  • Reinicio del servidor donde MySQL no está configurado para auto-arrancar

Cómo verificar

En el servidor:

systemctl status mysql       # o mariadb, o mysqld
ps aux | grep -i mysql
ss -tlnp | grep 3306         # ¿hay algo escuchando en el puerto MySQL?

Arreglo

systemctl start mysql
journalctl -u mysql -n 50    # revisa por qué se detuvo

Si MySQL no arranca, el log del journal te dice por qué. Razones comunes: tabla corrupta requiriendo --innodb-force-recovery, se quedó sin espacio en disco, archivo mysql.sock faltante.

Causa 3 — Demasiadas conexiones

MySQL tiene un tope duro en conexiones simultáneas (max_connections, default 151). Cuando se alcanza el tope, los nuevos intentos de conexión fallan.

Cuándo pasa

  • Un pico de tráfico donde muchos visitantes concurrentes necesitan conexiones DB
  • Un plugin fugando conexiones (fallando en cerrar tras uso)
  • Múltiples sitios WordPress en el mismo servidor MySQL, compartiendo el límite
  • Queries de larga duración manteniendo conexiones abiertas mientras nuevas hacen cola
  • Un deploy fallido que dejó procesos worker huérfanos

Cómo verificar

mysql -e "SHOW STATUS LIKE 'Threads_connected';"
mysql -e "SHOW VARIABLES LIKE 'max_connections';"
mysql -e "SHOW PROCESSLIST;"

Si Threads_connected está cerca de max_connections, tienes un problema de saturación.

Arreglo

Corto plazo: incrementa max_connections en my.cnf:

[mysqld]
max_connections = 300

Luego reinicia MySQL. Nota: incrementar esto consume más memoria. Cada conexión cuesta aproximadamente 1MB mínimo, a veces más.

Largo plazo: encuentra qué está fugando. SHOW PROCESSLIST muestra queries actuales; busca queries en estado Sleep por períodos largos — eso es una fuga.

Causa 4 — Usuario bloqueado por MySQL

MySQL puede bloquear una cuenta de usuario si su contraseña falla demasiadas veces (cuando password_history y password_reuse_interval están configurados) o si el usuario está explícitamente suspendido.

Cuándo pasa

  • Un intento de fuerza bruta contra la cuenta de base de datos
  • Un script de backup mal configurado usando credenciales equivocadas y fallando repetidamente
  • Un plugin de seguridad rotando contraseñas y no actualizando el usuario DB
  • La respuesta automatizada de seguridad de un hosting

Cómo verificar

mysql -e "SELECT user, host, account_locked FROM mysql.user WHERE user='wp_user';"

Arreglo

ALTER USER 'wp_user'@'localhost' ACCOUNT UNLOCK;

Más identificar y arreglar qué estaba disparando el bloqueo en primer lugar.

Causa 5 — Problema de red o socket

DB_HOST de localhost usa un Unix socket; 127.0.0.1 usa TCP. Si el archivo socket está faltante o el puerto TCP es inalcanzable, la conexión falla aunque MySQL esté corriendo.

Cuándo pasa

  • MySQL fue reinstalado con una ruta de socket diferente
  • El archivo socket se borró (script de limpieza salió mal)
  • Una regla de firewall está bloqueando el puerto 3306 en TCP
  • El host MySQL remoto es inalcanzable (caída de red)
  • DB_HOST configurado a un hostname que no resuelve

Cómo verificar

# Encuentra el socket MySQL real
mysql -e "SHOW VARIABLES LIKE 'socket';"

# Revisa si existe
ls -la /var/run/mysqld/mysqld.sock

# Test de conectividad TCP
nc -zv $DB_HOST 3306

Arreglo

Para problemas de Unix socket: actualiza DB_HOST en wp-config.php a la ruta de socket explícita:

define('DB_HOST', 'localhost:/var/run/mysqld/mysqld.sock');

O cambia a TCP:

define('DB_HOST', '127.0.0.1:3306');

Para problemas TCP: arregla firewall, arregla DNS, o mueve la base de datos a un host alcanzable.

El flujo diagnóstico de 5 minutos

Cuando aparece el error, corre esta secuencia:

# Paso 1 — ¿Se puede alcanzar MySQL?
mysql -e "SELECT 1;" 2>&1

# Si el paso 1 falla con "Access denied":
#   → Problema de credenciales (Causa 1) o usuario bloqueado (Causa 4)

# Si el paso 1 falla con "Can't connect":
#   → MySQL caído (Causa 2) o problema de socket/red (Causa 5)

# Si el paso 1 falla con "Too many connections":
#   → saturación de max_connections (Causa 3)

# Paso 2 — Confirma que las credenciales WP funcionan
mysql -h "$DB_HOST" -u "$DB_USER" -p"$DB_PASSWORD" -D "$DB_NAME" -e "SELECT 1;"

# Paso 3 — Revisa WP-CLI desde el directorio WordPress
cd /var/www/yoursite && wp db check

Estos tres pasos acotan la causa cada vez.

Checklist de prevención

Una vez que arreglaste el problema inmediato, endurece contra recurrencia:

  • Documenta las credenciales de base de datos en tu password manager, no solo en wp-config.php
  • Configura auto-restart para MySQL: systemctl enable mysql
  • Configura max_connections de MySQL basado en carga real + 50% de margen
  • Añade monitoreo en la variable MySQL Threads_connected; alerta al 80% del max
  • Bloquea acceso saliente al puerto 3306 (solo tu servidor WordPress, no el internet público)
  • Programa backups diarios de wp-config.php separado del resto (contiene las credenciales necesarias para restaurar todo lo demás)

Errores comunes al diagnosticar

  • Asumir que el problema es WordPress cuando es MySQL — WordPress está reportando el error, pero la causa está del lado de la base de datos
  • Reiniciar MySQL sin revisar por qué se detuvo — enmascara el problema subyacente, volverá a pasar
  • Incrementar `max_connections` a 1000 — resuelve el síntoma, deja la fuga de conexiones
  • Editar `wp-config.php` sin hacer backup primero — un typo y pierdes acceso a todos los backups también
  • Resetear la contraseña MySQL para arreglar "Access denied" — solo válido si confirmaste que las credenciales están mal; de otra forma rompes más cosas

Cuándo llamar a un especialista

El mensaje "Error establishing a database connection" es resoluble en 5 minutos para alguien que ha visto las cinco causas. Es resoluble en 5 horas para alguien viéndolo por primera vez. Para sitios de negocio, la diferencia entre 5 minutos y 5 horas es la diferencia entre pérdida negligible y pérdida significativa de ingresos.

¿Emergencia de conexión a base de datos? Estamos online en minutos. Para reparación más profunda, ve fallo de conexión a base de datos y recuperación de tabla corrupta.