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 PostgreSQL. Al configurar un servidor primario (maestro) para transmitir continuamente registros del Write-Ahead Log (WAL) a uno o más servidores en espera (réplicas), se garantiza la sincronización de datos con un retraso mínimo.

Esta guía explica la replicación asíncrona por streaming utilizando pg_basebackup, pg_hba.conf y archivos de señal de espera. Al finalizar, tendrá un par primario-en espera funcional y las comprobaciones necesarias para verificar que realmente está transmitiendo.

Requisitos previos y configuración del entorno

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

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 del sistema postgres) en ambos servidores.
• Red: El servidor en espera debe poder conectarse al servidor primario en el puerto de PostgreSQL (predeterminado 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. En los paquetes Debian y Ubuntu, esto suele estar en /etc/postgresql/<version>/main/postgresql.conf; en muchas instalaciones desde fuente o contenedor, reside en el directorio de datos. Establezca estos parámetros:

# Permitir conexiones desde otros hosts
listen_addresses = '*'

# Establecer el nivel de WAL en '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

# Permite consultas de solo lectura en el servidor en espera
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 registros WAL.

# Conectarse a PostgreSQL
sudo -u postgres psql -c "CREATE ROLE replica_user WITH REPLICATION LOGIN PASSWORD 'use-a-real-secret-here';"

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.

# TIPO  BASE_DE_DATOS        USUARIO            DIRECCIÓN                 MÉTODO
host    replication     replica_user    192.168.1.11/32         md5

1.4 Reiniciar el servidor primario

Aplique los cambios de configuración. Un reinicio es la opción simple después de cambiar listen_addresses; si solo cambió pg_hba.conf, una recarga es suficiente.

sudo systemctl restart postgresql

Paso 2: Preparar el servidor en espera

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

2.1 Detener el servicio PostgreSQL del servidor en espera

sudo systemctl stop postgresql

2.2 Limpiar el directorio de datos

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

# 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. La bandera -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	Nombre de host/dirección IP del servidor primario.
-D	Ruta del directorio de datos local.
-U	Nombre de usuario de replicación (replica_user).
-P	Mostrar progreso.
-v	Salida detallada.
-R	Crear automáticamente un archivo de configuración de replicación.

Paso 3: Configurar e iniciar el servidor en espera

3.1 Verificar la configuración del servidor en espera

Si usó la bandera -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 de que esté utilizando autenticación basada en certificados. Si usa pg_hba.conf con trust o cert, la contraseña puede omitirse.

3.2 Iniciar el servicio del servidor 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 solo lectura en espera 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 está ocurriendo.

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 representa 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: Debe coincidir con la IP del servidor en espera (por ejemplo, 192.168.1.11).
• state: Debe ser streaming. Si muestra startup o catching up, espere un momento. Si muestra walsender iniciando, está cerca.
• sync_state: Debe 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 y verifique inmediatamente 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 errores
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: Slots de replicación

Aunque son opcionales, los slots de replicación son altamente recomendados. Un slot de replicación asegura que el servidor primario no descarte prematuramente los segmentos WAL necesarios para el servidor en espera, incluso si el servidor en espera se desconecta temporalmente.

En el primario:

SELECT * FROM pg_create_physical_replication_slot('standby_slot_name');

Luego establezca primary_slot_name en el servidor en espera. No ponga el nombre del slot dentro de primary_conninfo.

primary_conninfo = 'host=192.168.1.10 user=replica_user password=use-a-real-secret-here application_name=standby_node'
primary_slot_name = 'standby_slot_name'

Advertencia: Los slots 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 el slot pueden llenar rápidamente el espacio en disco del servidor primario.

Solución de problemas comunes

Problema	Causa potencial	Solución
El servidor en espera no puede conectarse	Firewall de red, listen_addresses incorrecto o pg_hba.conf incorrecto en el primario.	Verifique que el puerto 5432 sea accesible; confirme que 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 falta de entrada de host en pg_hba.conf.	Vuelva a verificar la contraseña de replica_user; asegúrese de que la base de datos primaria se reinicie 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.

Siguiente paso

Configurar la replicación por streaming es un paso crítico en la construcción de una arquitectura PostgreSQL resiliente. 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.