Guía Paso a Paso para Configurar la Replicación por Streaming de PostgreSQL

La replicación por streaming es el mecanismo fundamental para lograr alta disponibilidad (HA) y escalabilidad de lectura en entornos de PostgreSQL. Al configurar un servidor primario (maestro) para que transmita continuamente registros del Write-Ahead Log (WAL) a uno o más servidores en espera (réplica), usted asegura la sincronización de los datos con un retraso mínimo.

Esta guía completa lo guiará a través de los pasos esenciales necesarios para establecer una replicación por streaming asíncrona y robusta. Cubrimos los cambios de configuración necesarios tanto en el servidor primario como en el de espera, utilizando características modernas de PostgreSQL como pg_basebackup y archivos de señal para una configuración simplificada. Seguir este tutorial lo equipará con una base confiable para una operación robusta de PostgreSQL.

Requisitos Previos y Configuración del Entorno

Antes de comenzar, asegúrese de que se cumplan los siguientes requisitos previos. Esta guía asume dos servidores, Primario y En espera (Standby), que ejecutan la misma versión principal de PostgreSQL (se recomienda la versión 12 o posterior).

Servidor	Rol	Dirección IP (Ejemplo)
Primario	Fuente de verdad	192.168.1.10
En espera	Réplica	192.168.1.11

• Usuario: Debe tener acceso administrativo (por ejemplo, sudo o el usuario de sistema postgres) en ambos servidores.
• Red: El servidor en espera debe poder conectarse al servidor primario a través del puerto de PostgreSQL (por defecto, 5432).

Paso 1: Configurar el Servidor Primario

El servidor primario debe configurarse para generar y servir archivos WAL para la replicación.

1.1 Modificar postgresql.conf

Edite el archivo de configuración principal, generalmente ubicado en el directorio de datos (por ejemplo, /etc/postgresql/14/main/postgresql.conf), y establezca los siguientes parámetros:

# Permitir conexiones desde otros hosts
listen_addresses = '*'

# Establecer el nivel de WAL a 'replica' o superior
wal_level = replica

# Número máximo de conexiones concurrentes desde servidores en espera
max_wal_senders = 5 

# Controla el número de conexiones en espera que pueden estar activas simultáneamente
max_replication_slots = 5

# Requerido para consultas de solo lectura en el servidor en espera (Hot Standby)
hot_standby = on

1.2 Crear un Usuario de Replicación Dedicado

Por seguridad, cree un usuario específico con el atributo REPLICATION. Este usuario será utilizado únicamente por el servidor en espera para obtener los registros WAL.

# Conectarse a PostgreSQL
psql -c "CREATE USER replica_user REPLICATION ENCRYPTED PASSWORD 'SuperSecurePassword123';"

1.3 Actualizar la Autenticación de Clientes (pg_hba.conf)

Permita que el usuario de replicación, desde la dirección IP del servidor en espera, se conecte a la pseudo-base de datos especial replication.

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    replication     replica_user    192.168.1.11/32         md5

1.4 Reiniciar el Servidor Primario

Aplique los cambios reiniciando el servicio de PostgreSQL:

sudo systemctl restart postgresql

Paso 2: Preparar el Servidor en Espera

Antes de clonar los datos, asegúrese de que el servicio de PostgreSQL del servidor en espera esté detenido y que su directorio de datos existente esté vacío.

2.1 Detener el Servicio PostgreSQL en Espera

sudo systemctl stop postgresql

2.2 Limpiar el Directorio de Datos

Advertencia: Este paso elimina permanentemente todos los datos que se encuentren actualmente en el directorio de datos del servidor en espera. Confirme la ruta antes de ejecutar.

# Ruta de ejemplo para PG 14
PG_DATA=/var/lib/postgresql/14/main

sudo rm -rf $PG_DATA/*

2.3 Clonar Datos Usando pg_basebackup

Use pg_basebackup para crear una copia exacta del directorio de datos del primario. El indicador -R es crucial ya que genera automáticamente los archivos de configuración necesarios (standby.signal y primary_conninfo) para la replicación por streaming (PostgreSQL 12+).

Ejecute este comando en el servidor en espera:

PG_DATA=/var/lib/postgresql/14/main

sudo -u postgres pg_basebackup -h 192.168.1.10 -D $PG_DATA -U replica_user -P -v -R

Opción	Descripción
-h	Dirección IP/nombre de host del servidor primario.
-D	Ruta local del directorio de datos.
-U	Nombre de usuario de replicación (replica_user).
-P	Mostrar progreso.
-v	Salida detallada (Verbose).
-R	Crear un archivo de configuración de replicación automáticamente.

Paso 3: Configurar e Iniciar el Servidor en Espera

3.1 Verificar la Configuración del Servidor en Espera

Si utilizó el indicador -R en el Paso 2.3, pg_basebackup creó un archivo standby.signal y completó la configuración primary_conninfo, generalmente en un archivo de configuración generado llamado postgresql.auto.conf dentro del directorio de datos.

Verifique el contenido de la cadena primary_conninfo. Debería verse similar a esto (verifique dentro de $PG_DATA/postgresql.auto.conf):

primary_conninfo = 'host=192.168.1.10 user=replica_user password=SuperSecurePassword123 application_name=standby_node'

Consejo: Asegúrese de que la contraseña esté incluida en primary_conninfo o que esté utilizando autenticación basada en certificados. Si utiliza pg_hba.conf con trust o cert, la contraseña puede omitirse.

3.2 Iniciar el Servicio en Espera

Dado que el archivo de señal requerido (standby.signal) está presente en el directorio de datos, el servicio se iniciará en modo de espera de solo lectura e intentará conectarse inmediatamente al primario.

sudo systemctl start postgresql

Paso 4: Verificar la Replicación por Streaming

Después de iniciar el servidor en espera, debe confirmar que la conexión está activa y que la sincronización de datos se está produciendo.

4.1 Verificación en el Servidor Primario

Conéctese al servidor primario y consulte la vista pg_stat_replication. Debería ver una fila que represente la conexión desde el servidor en espera.

psql -c "SELECT client_addr, state, sync_state, sent_lsn, write_lsn, flush_lsn FROM pg_stat_replication;"

Salida Esperada (Campos Clave):

• client_addr: Debería coincidir con la IP del servidor en espera (ej.: 192.168.1.11).
• state: Debería ser streaming. Si muestra startup (inicio) o catching up (poniéndose al día), espere un momento. Si muestra walsender arrancando, está cerca.
• sync_state: Debería ser async (para replicación asíncrona estándar).

4.2 Probar la Sincronización de Datos

Para confirmar el flujo de datos, ejecute un cambio en el primario e inmediatamente verifique su existencia en el servidor en espera.

En el Primario:

CREATE TABLE replication_test (id serial primary key, message text);
INSERT INTO replication_test (message) VALUES ('Data synchronized successfully');

En el Servidor en Espera (Solo Lectura):

-- Esto debe tener éxito sin error
psql -c "SELECT * FROM replication_test;"

Si los datos son visibles en el servidor en espera, la replicación por streaming está configurada y activa correctamente.

Mejores Prácticas y Solución de Problemas

Conexión Persistente: Ranuras de Replicación (Replication Slots)

Aunque son opcionales, se recomienda encarecidamente utilizar ranuras de replicación. Una ranura de replicación garantiza que el servidor primario no descarte prematuramente los segmentos WAL necesarios para el servidor en espera, incluso si este se desconecta temporalmente.

En el Primario:

SELECT * FROM pg_create_physical_replication_slot('standby_slot_name');

Luego, actualice la primary_conninfo en el servidor en espera para utilizar esta ranura:

primary_conninfo = 'host=192.168.1.10 user=replica_user ... application_name=standby_node **slotname=standby_slot_name**'

Advertencia: Las ranuras de replicación requieren una monitorización cuidadosa. Si un servidor en espera falla durante un período prolongado, los archivos WAL acumulados protegidos por la ranura pueden hacer que el espacio en disco del servidor primario se llene rápidamente.

Solución de Problemas Comunes

Problema	Causa Potencial	Solución
Servidor en espera atascado en starting (iniciando)	Firewall de red o pg_hba.conf incorrecto en el primario.	Verifique que el puerto 5432 esté abierto; confirme que la entrada de pg_hba.conf coincida con la IP y el usuario del servidor en espera.
pg_basebackup falla con error de autenticación	Contraseña incorrecta o entrada de host faltante en pg_hba.conf.	Verifique dos veces la contraseña de replica_user; asegúrese de que la base de datos primaria se haya reiniciado después de modificar pg_hba.conf.
El servidor en espera es de solo lectura	Este es el comportamiento esperado.	La presencia de standby.signal obliga al servidor a entrar en modo de recuperación.

Conclusión

Configurar la replicación por streaming es un paso fundamental en la construcción de una arquitectura PostgreSQL resistente. Siguiendo estos pasos, ha configurado con éxito un par primario-en espera que garantiza la sincronización continua de datos, mejorando significativamente las capacidades de alta disponibilidad de su sistema. El siguiente paso lógico es integrar una solución de monitoreo y un mecanismo de conmutación por error (como Patroni o Repmgr) para automatizar completamente la configuración de HA.