Solución de Problemas Comunes de Failover y Errores de Conexión en Clústeres de Alta Disponibilidad de PostgreSQL

Los clústeres de alta disponibilidad (HA) de PostgreSQL fallan de dos maneras diferentes. A veces, el propio failover de la base de datos se rompe: no se promociona ninguna réplica, dos nodos no están de acuerdo sobre quién es el primario, o el nuevo primario no puede aceptar escrituras. Otras veces, la base de datos está bien, pero la aplicación aún no puede conectarse porque un pooler, un registro DNS, una IP virtual, una regla de firewall o un bucle de reintento del cliente no siguieron la promoción.

Cuando estás en medio de un incidente, separa esas capas rápidamente. Primero pregúntate: ¿hay exactamente un primario con capacidad de escritura? Luego pregúntate: ¿puede el pooler alcanzarlo? Luego pregúntate: ¿puede la aplicación alcanzar el pooler o el punto final del servicio? Ese orden evita perder mucho tiempo mirando los registros de la aplicación mientras el administrador del clúster todavía está atascado en la elección del líder.

Comprendiendo los Fundamentos de la Alta Disponibilidad en PostgreSQL

Antes de sumergirnos en la solución de problemas, es esencial repasar brevemente los componentes centrales de un clúster de alta disponibilidad de PostgreSQL:

• Arquitectura Primario/Réplica: Una base de datos primaria maneja todas las operaciones de escritura, mientras que una o más réplicas reciben cambios de forma asíncrona o síncrona a través de la replicación en streaming. Las réplicas son de solo lectura, pero sirven como candidatas para la promoción durante un failover.
• Administrador de Failover: Herramientas como Patroni, pg_auto_failover o Corosync/Pacemaker monitorean la salud del primario, detectan fallos, eligen un nuevo primario entre las réplicas disponibles y gestionan el proceso de promoción. También se encargan de reconfigurar otras réplicas para que sigan al nuevo primario.
• Pooling de Conexiones: Las aplicaciones a menudo se conectan a un pooler de conexiones de PostgreSQL (por ejemplo, PgBouncer, Odyssey) en lugar de directamente a la base de datos. El pooler luego enruta las consultas al primario actual, proporcionando multiplexación de conexiones, balanceo de carga y, potencialmente, abstrayendo la dirección de red real del primario de las aplicaciones. Esta abstracción es crucial durante un failover.

Problemas Comunes de Failover y Conexión y Sus Soluciones

1. Problemas de Pooling de Conexiones Durante el Failover

Uno de los problemas más frecuentes después de un failover es que las aplicaciones no se reconectan al nuevo primario promocionado, a pesar de que la base de datos en sí misma esté operativa. Esto a menudo apunta a problemas con el pooler de conexiones o el almacenamiento en caché del lado del cliente.

Síntomas del Problema:

• Las aplicaciones reportan errores de conexión a la base de datos (FATAL: database "mydb" does not exist, connection refused, server closed the connection unexpectedly).
• Las conexiones existentes a través del pooler parecen atascadas o intentan conectarse a la IP del antiguo primario.
• Las nuevas conexiones también fallan, incluso después de que el failover se haya completado.

Causas Subyacentes:

• Conexiones Obsoletas en el Pooler: El pooler de conexiones podría mantener conexiones abiertas al antiguo primario e intentar reutilizarlas, lo que genera errores cuando el antiguo primario está caído o ahora es una réplica.
• Configuración Incorrecta del Pooler: Es posible que el pooler no esté configurado para detectar y cambiar correctamente al nuevo primario, o que su server_reset_query falte o sea incorrecto.
• Caché de DNS: Si tus aplicaciones o pooler utilizan una entrada DNS para resolver la dirección del primario, las entradas obsoletas en la caché de DNS (ya sea localmente o a nivel del resolvedor de DNS) pueden hacer que sigan intentando conectarse a la IP antigua.
• Falta de Lógica de Reintento del Lado del Cliente: Es posible que las aplicaciones no estén construidas con mecanismos robustos de reintento para manejar problemas de conexión transitorios durante un failover.

Pasos de Depuración:

1. Verificar el Estado del Pooler: Accede a la consola de tu pooler (por ejemplo, psql -p 6432 pgbouncer -U pgbouncer) y verifica su salida SHOW SERVERS, SHOW CLIENTS, SHOW DATABASES para ver si es consciente del nuevo primario y si tiene conexiones activas a la dirección correcta.
2. Verificar la Conectividad de Red: Desde el host del pooler, haz ping y telnet al puerto de PostgreSQL del nuevo primario (telnet new_primary_ip 5432).
3. Inspeccionar los Registros del Pooler: Revisa los registros del pooler en busca de mensajes de error relacionados con la conexión a la base de datos o intentos de resolver nombres de host.
4. Verificar la Resolución DNS: Usa dig o nslookup en el host del pooler para asegurarte de que el registro DNS para tu punto final del servicio primario (por ejemplo, primary.mydomain.com) se resuelva a la dirección IP del nuevo primario.

Soluciones:

• Configurar server_reset_query: Asegúrate de que tu pooler tenga un server_reset_query (por ejemplo, DISCARD ALL;) para limpiar el estado de la sesión cuando una conexión se devuelve al pool y antes de que sea reutilizada por otro cliente. Esto es crucial para entornos que utilizan objetos temporales o configuraciones específicas de la sesión.
• max_db_connections y max_user_connections: Establece límites apropiados para evitar que el pooler acapare todas las conexiones al nuevo primario, lo que podría privar a otros servicios.
• Recargar/Reiniciar el Pooler: En algunos casos, puede ser necesaria una recarga o reinicio controlado del pooler de conexiones para forzarlo a recoger nuevas configuraciones o resolver DNS nuevamente. Esto debería ser un último recurso y, preferiblemente, automatizado por tu administrador de failover.
• TTL de DNS más Corto: Si usas descubrimiento de servicios basado en DNS, configura un Time-To-Live (TTL) muy corto para el registro DNS del primario (por ejemplo, 30-60 segundos) para minimizar el impacto del almacenamiento en caché de DNS.
• Reintentos del Lado del Cliente: Implementa una lógica de reintento con backoff exponencial en el código de tu aplicación. Esto hace que las aplicaciones sean más resistentes a problemas de conexión transitorios durante un failover.
• IP Virtual (VIP): Considera usar una IP Virtual gestionada por tu solución de alta disponibilidad. La VIP se mueve con el primario, por lo que las aplicaciones se conectan a una IP estática y el servidor de base de datos subyacente cambia de forma transparente.

# Ejemplo de Fragmento de Configuración de PgBouncer
[databases]
mydb = host=primary_cluster_service_ip port=5432 dbname=mydb
# O usando un nombre de host que se actualiza mediante tu administrador de failover
# mydb = host=primary.mydomain.com port=5432 dbname=mydb

[pgbouncer]
listen_addr = 0.0.0.0
listen_port = 6432
auth_type = md5
auth_file = /etc/pgbouncer/userlist.txt
pool_mode = session
server_reset_query = DISCARD ALL;
server_fast_close = 1 # Cerrar conexiones rápidamente si el servidor no responde
server_check_delay = 10 # Verificar la salud del servidor cada 10 segundos

2. Retraso Excesivo de la Réplica que Dificulta el Failover

El retraso de la réplica ocurre cuando una base de datos en espera se queda atrás respecto al primario, lo que significa que no ha reproducido todos los registros WAL (Write-Ahead Log) enviados por el primario. Durante un failover, promocionar una réplica muy retrasada puede provocar pérdida de datos o retrasar significativamente el proceso de failover si el administrador de alta disponibilidad espera a que se ponga al día.

Síntomas del Problema:

• Las alertas de monitoreo indican un alto retraso de la réplica (por ejemplo, en bytes o tiempo).
• Los administradores de failover se niegan a promocionar una réplica debido a que se supera un umbral de retraso configurado.
• Después del failover, las aplicaciones observan datos faltantes que estaban presentes en el antiguo primario.

Causas Subyacentes:

• Alta Carga de Escritura en el Primario: Un volumen sostenido alto de operaciones de escritura en el primario puede abrumar la capacidad de la réplica para mantenerse al día, especialmente si el hardware de la réplica (E/S, CPU) es inferior.
• Latencia/Ancho de Banda de la Red: Los enlaces de red lentos o congestionados entre el primario y la réplica pueden retrasar el envío de WAL.
• E/S Lenta en la Réplica: El subsistema de disco de la réplica podría no ser lo suficientemente rápido para escribir y reproducir los registros WAL de manera eficiente.
• Configuración de wal_level: Si wal_level no está configurado en replica o superior, no se generará la información necesaria para la replicación en streaming.
• max_wal_senders: Un max_wal_senders insuficiente en el primario puede limitar el número de slots de replicación activos o conexiones de replicación concurrentes, lo que afecta el rendimiento.
• Problemas con archive_command / restore_command: Si se utiliza archivado y recuperación de WAL, los problemas con estos comandos (por ejemplo, almacenamiento de archivos lento) pueden causar retrasos.

Pasos de Depuración:

1. Monitorear pg_stat_replication: Esta vista proporciona información en tiempo real sobre el estado de la replicación, incluyendo write_lag, flush_lag y replay_lag.
2. Comparar LSNs: Compara manualmente el LSN de WAL actual en el primario con el último LSN reproducido en la réplica.
3. Verificar Recursos del Sistema: Usa iostat, vmstat, top tanto en el primario como en la réplica para identificar cuellos de botella de E/S, saturación de CPU o presión de memoria.
4. Diagnóstico de Red: Prueba el rendimiento de la red entre el primario y la réplica usando iperf.

Soluciones:

• Aumentar max_wal_senders: En el primario, aumenta max_wal_senders (por ejemplo, max_wal_senders = 10) para permitir más conexiones de replicación concurrentes. Se requiere reinicio.
• Mejorar el Hardware de la Réplica: Si la E/S o la CPU son un cuello de botella, considera actualizar el hardware de la réplica u optimizar su configuración de almacenamiento (por ejemplo, SSD más rápidos, disco WAL separado).
• Ajustar wal_compression: En el primario, configurar wal_compression = on puede reducir el volumen de WAL, mejorando potencialmente la velocidad de replicación en enlaces con restricciones de red, pero a costa de la CPU del primario.
• Ajustar wal_keep_size o wal_keep_segments: Asegúrate de que se retengan suficientes archivos WAL en el primario para evitar que las réplicas se desincronicen y requieran una copia de seguridad base completa.
• synchronous_commit: Mientras que synchronous_commit = on proporciona garantías más sólidas de durabilidad de datos, introduce latencia en las escrituras en el primario. Usa remote_write o remote_apply para tablas o transacciones específicas si se necesita replicación síncrona estricta, pero evalúa cuidadosamente el impacto en el rendimiento.
• Monitoreo y Alertas: Implementa un monitoreo robusto para pg_stat_replication y configura alertas para cuando el retraso supere los umbrales aceptables.

-- En el Primario: Verificar el LSN de WAL actual
SELECT pg_current_wal_lsn();

-- En el Primario: Verificar las réplicas conectadas y el retraso
SELECT
    usename, application_name, client_addr, state, sync_state,
    pg_wal_lsn_diff(pg_current_wal_lsn(), replay_lsn) AS replay_lag_bytes,
    write_lag, flush_lag, replay_lag
FROM pg_stat_replication;

En una réplica, usa:

SELECT
    pg_is_in_recovery() AS is_standby,
    pg_last_wal_receive_lsn(),
    pg_last_wal_replay_lsn(),
    now() - pg_last_xact_replay_timestamp() AS time_since_last_replay;

La consulta de marca de tiempo puede ser engañosa en un sistema inactivo porque es posible que no se haya reproducido ninguna transacción reciente. Úsala con comparaciones de LSN y contexto de carga de trabajo.

3. Transición de Primario Fallida o Bloqueada

Un failover automatizado debería promocionar una réplica de manera rápida y confiable. Cuando este proceso se estanca o falla por completo, puede provocar un tiempo de inactividad prolongado y requerir intervención manual.

Síntomas del Problema:

• No se elige ni promociona un nuevo primario después de que el antiguo primario se cae.
• El clúster entra en un estado de split-brain donde dos nodos creen que son el primario.
• Los registros del administrador de failover muestran errores relacionados con el quórum, la elección del líder o la promoción de la base de datos.
• Las aplicaciones permanecen caídas porque no hay ningún primario disponible.

Causas Subyacentes:

• Split-Brain: Ocurre cuando las particiones de red aíslan los nodos, lo que lleva a múltiples primarios o a una elección ambigua del primario. Este es el escenario más peligroso, con riesgo de divergencia de datos.
• Problemas de Quórum: Es posible que el administrador de failover no pueda alcanzar un quórum (voto mayoritario) entre sus nodos, lo que le impide tomar una decisión sobre la promoción. Esto es común en clústeres con un número par de nodos o muy pocos nodos.
• Aislamiento de Red: Los nodos del administrador de failover no pueden comunicarse entre sí ni con las instancias de PostgreSQL, lo que impide las comprobaciones de salud o la ejecución de comandos.
• Privilegios Insuficientes: El usuario del administrador de failover podría carecer de los permisos necesarios de PostgreSQL (por ejemplo, pg_promote()) o permisos a nivel de sistema (por ejemplo, para gestionar VIPs).
• Errores de Configuración: restore_command, primary_conninfo u otras configuraciones incorrectas dentro de la configuración del administrador de failover.

Pasos de Depuración:

1. Verificar los Registros del Administrador de Failover: Esta es la fuente principal de información. Para Patroni, mira sus registros específicos (a menudo journalctl -u patroni o el archivo de registro configurado en patroni.yml). Para pg_auto_failover, verifica journalctl -u pgautofailover_monitor y los registros del agente.
2. Verificar el Estado del Quórum: Para Patroni, usa patronictl list para ver el estado de todos los miembros del clúster y confirmar el líder elegido. Para pg_auto_failover, verifica pg_autoctl show state.
3. Conectividad de Red: Realiza comprobaciones de ping, traceroute y telnet entre todos los nodos de alta disponibilidad y el almacén de consenso distribuido (por ejemplo, Etcd, Consul, ZooKeeper para Patroni).
4. Registros del Sistema: Verifica journalctl -xe o /var/log/syslog en todos los nodos para detectar errores a nivel de sistema que puedan interferir con el administrador de failover (por ejemplo, disco lleno, problemas de memoria).
5. Registros de PostgreSQL: Examina los registros de PostgreSQL en la réplica candidata para la promoción para ver si informa algún problema durante el intento de promoción.

Soluciones:

• Implementar Fencing/STONITH: El fencing es crucial para evitar el split-brain al asegurar que un primario fallido no pueda seguir aceptando escrituras antes de que se promocione uno nuevo. Esto normalmente lo maneja el administrador de failover o la capa de infraestructura.
• Número Impar de Nodos para el Quórum: Siempre despliega un número impar de nodos de votación (por ejemplo, 3, 5) para el almacén de consenso distribuido de tu administrador de failover (Etcd, Consul, ZooKeeper) para asegurar que siempre se pueda alcanzar el quórum incluso si fallan uno o dos nodos.
• Configuración de Red Robusta: Asegura rutas de red redundantes, reglas de firewall adecuadas que permitan la comunicación en los puertos necesarios (PostgreSQL, almacén de consenso, API de Patroni) y resolución de nombres de host consistente.
• Verificación de Permisos: Verifica que la cuenta de usuario que ejecuta el administrador de failover tenga todos los privilegios necesarios de PostgreSQL y permisos del sistema para realizar tareas de promoción y reconfiguración.
• Revisar la Configuración del Administrador de Failover: Vuelve a verificar la configuración de patroni.yml o pg_auto_failover en busca de errores tipográficos, rutas incorrectas o restore_command mal configurado.
• Intervención Manual (con Precaución): En un failover severo y bloqueado, puede ser necesaria la promoción manual o la reconexión de nodos. Procede con extrema precaución, asegurándote de que el antiguo primario esté completamente apagado antes de promocionar uno nuevo para evitar la divergencia de datos.

# Ejemplo: Verificar el estado del clúster de Patroni
patronictl -c /etc/patroni/patroni.yml list

# Salida esperada (ejemplo):
# + Cluster: my_ha_cluster (6979219803154942080) ------+----+-----------+----+-----------+
# | Member  | Host         | Role    | State    | TL | Lag |
# +---------+--------------+---------+----------+----+-----+
# | node1   | 192.168.1.10 | Leader  | running  | 2  |     |
# | node2   | 192.168.1.11 | Replica | running  | 2  | 0   |
# | node3   | 192.168.1.12 | Replica | running  | 2  | 0   |
# +---------+--------------+---------+----------+----+-----+

4. Problemas de Conectividad de Red y Resolución DNS

En la raíz de muchos problemas de alta disponibilidad se encuentran problemas de red fundamentales que impiden que los nodos se comuniquen o que las aplicaciones encuentren el punto final correcto de la base de datos.

Síntomas del Problema:

• Errores de connection refused o no route to host desde las aplicaciones o entre los nodos del clúster.
• El administrador de failover reporta nodos como inalcanzables.
• Los servicios que dependen de DNS no pueden resolver el nombre de host del primario correctamente.

Causas Subyacentes:

• Reglas de Firewall: Reglas de firewall configuradas incorrectamente (por ejemplo, iptables, grupos de seguridad) que bloquean el puerto de PostgreSQL (5432), los puertos del administrador de failover o los puertos del almacén de consenso.
• Partición de Red: División de red física o lógica que impide la comunicación entre un subconjunto de nodos.
• Enrutamiento Incorrecto: Rutas de red mal configuradas en uno o más nodos.
• Caché de DNS/Configuración Incorrecta: Como se discutió en la Sección 1, los registros DNS obsoletos o la configuración incorrecta del servidor DNS pueden desviar el tráfico.
• Fallo en la Migración de la IP Virtual (VIP): Si se usa una VIP, podría fallar al migrar al nuevo primario, dejando el servicio inalcanzable.

Pasos de Depuración:

1. Conectividad Básica: Usa ping <target_ip> entre todos los nodos.
2. Conectividad de Puerto: Usa telnet <target_ip> <port> (por ejemplo, telnet 192.168.1.10 5432) para verificar que el puerto de PostgreSQL esté abierto y escuchando.
3. Verificación de Firewall: En cada nodo, verifica las reglas de firewall activas (sudo iptables -L, sudo ufw status o las configuraciones del grupo de seguridad del proveedor de la nube).
4. Estado de la Interfaz de Red: Usa ip addr show o ifconfig para asegurarte de que las interfaces de red estén activas y configuradas correctamente.
5. Resolución DNS: Usa dig <hostname> o nslookup <hostname> para verificar la resolución del nombre de host desde los nodos relevantes (servidores de aplicaciones, pooler, nodos de alta disponibilidad).

Soluciones:

• Revisar las Reglas de Firewall: Asegúrate de que los puertos necesarios estén abiertos para PostgreSQL (5432), el plano de control del administrador de failover (por ejemplo, 8008 para la API de Patroni, 8000/8001 para pg_auto_failover) y el almacén de consenso distribuido (por ejemplo, Etcd: 2379/2380, Consul: 8300/8301/8302).
• Red Consistente: Asegúrate de que todos los nodos estén en la misma subred o tengan el enrutamiento correcto configurado si abarcan múltiples subredes.
• Actualizaciones de DNS: Automatiza las actualizaciones de DNS como parte del proceso de failover, o usa un TTL más corto. Las VIPs a menudo se prefieren por esta razón.
• Gestión de VIP: Si usas una VIP, asegúrate de que la herramienta de gestión de VIP (por ejemplo, Keepalived, gestión de IP del proveedor de la nube) esté configurada y funcionando correctamente. Prueba la migración de la VIP explícitamente.
• Acceso Basado en Host: Para simplificar en clústeres más pequeños, asegúrate de que pg_hba.conf permita conexiones desde todas las direcciones IP potenciales de primario/réplica y la IP del pooler de conexiones.

Herramientas Esenciales para la Solución de Problemas

• psql: Para ejecutar consultas SQL como pg_stat_replication, pg_current_wal_lsn(), comandos SHOW *.
• CLI del Administrador de Failover: patronictl, pg_autoctl para consultar el estado del clúster, los registros e iniciar acciones.
• Monitoreo del Sistema: Herramientas como Prometheus + Grafana, Zabbix, Nagios o el monitoreo del proveedor de la nube para obtener información en tiempo real sobre la utilización de recursos, el retraso de la replicación y el estado del servicio.
• journalctl / tail -f: Para ver los registros del sistema y de la aplicación.
• Utilidades de Red: ping, traceroute, telnet, iperf, netstat, dig, nslookup para diagnosticar la conectividad.
• dmesg: Para errores a nivel de kernel, especialmente relacionados con E/S de disco o el asesino OOM (Out Of Memory).

Una Lista de Verificación Rápida para Incidentes

Cuando se activa una alerta de failover de alta disponibilidad, usa una lista de verificación corta antes de cambiar cualquier cosa:

1. Confirmar la vista del clúster:

patronictl -c /etc/patroni/patroni.yml list

1. Confirmar el rol de PostgreSQL en cada nodo alcanzable:

SELECT pg_is_in_recovery();

false significa que el nodo es un primario con capacidad de escritura. true significa que es una réplica. Si más de un nodo reporta false, detente y trata el incidente como un posible split-brain.

1. Confirmar el punto final de la aplicación:

dig primary-db.internal.example.com
nc -vz primary-db.internal.example.com 5432

1. Confirmar el destino del pooler, si usas PgBouncer:

SHOW SERVERS;
SHOW POOLS;

1. Verificar si los errores son antiguos o actuales. Los registros de la aplicación a menudo conservan mensajes de reintento de los primeros segundos del failover. Compara las marcas de tiempo antes de asumir que el fallo todavía está ocurriendo.

Esta lista de verificación es intencionalmente simple. Durante un failover real, el mejor comando es aquel que todos en el equipo entienden y pueden ejecutar sin adivinar.

Mejores Prácticas para Prevenir Problemas de Failover

• Pruebas de Failover Regulares: Simula regularmente fallos del primario y observa el proceso de failover. Esto genera confianza y expone configuraciones incorrectas.
• Monitoreo y Alertas Robusto: Monitorea métricas clave como el retraso de la réplica, el estado del primario, la salud del pooler de conexiones y los recursos del sistema. Configura alertas para cualquier desviación.
• Configuración Adecuada del Pooler de Conexiones: Asegúrate de que server_reset_query esté configurado, que pool_mode sea apropiado para tu aplicación y que las comprobaciones de salud estén habilitadas.
• Ajustar los Parámetros de Replicación: Configura wal_level, max_wal_senders, wal_keep_size y synchronous_commit cuidadosamente según tus requisitos de rendimiento y durabilidad.
• Documentar tu Configuración de Alta Disponibilidad: Documenta claramente tu arquitectura de alta disponibilidad, la configuración del administrador de failover, la configuración de red y los procedimientos de recuperación.
• Usar un Administrador de Failover Dedicado: Confía en soluciones probadas como Patroni o pg_auto_failover en lugar de scripts personalizados para la lógica crítica de alta disponibilidad.
• Almacén de Consenso Dedicado: Si usas un administrador como Patroni, despliega un clúster separado y de alta disponibilidad para su almacén de consenso distribuido (Etcd, Consul) para evitar un punto único de fallo.

Las pruebas de alta disponibilidad más útiles no son demostraciones limpias donde el primario se detiene cortésmente. Prueba también los casos difíciles: el antiguo primario pierde la red pero sigue funcionando, el DNS se actualiza lentamente, PgBouncer mantiene conexiones de servidor obsoletas, una réplica está 30 segundos atrasada, o el almacén de consenso pierde un miembro. Esas pruebas muestran si tus runbooks coinciden con el sistema que realmente operas.