Guida Passo-Passo per Configurare la Replica in Streaming di PostgreSQL

La replica in streaming è il meccanismo fondamentale per ottenere alta disponibilità (HA) e scalabilità in lettura negli ambienti PostgreSQL. Configurando un server primario (master) per trasmettere continuamente i record del Write-Ahead Log (WAL) a uno o più server standby (replica), garantisci la sincronizzazione dei dati con un ritardo minimo.

Questa guida illustra la replica asincrona in streaming utilizzando pg_basebackup, pg_hba.conf e i file di segnale standby. Alla fine avrai una coppia primario-standby funzionante e le verifiche necessarie per dimostrare che lo streaming è effettivamente attivo.

Prerequisiti e Configurazione dell'Ambiente

Prima di iniziare, assicurati che siano soddisfatti i seguenti prerequisiti. Questa guida presuppone due server, Primario e Standby, che eseguono la stessa versione principale di PostgreSQL (si consiglia la versione 12 o successiva).

Server	Ruolo	Indirizzo IP (Esempio)
Primario	Fonte di verità	192.168.1.10
Standby	Replica	192.168.1.11

• Utente: Devi avere accesso amministrativo (ad es. sudo o l'utente di sistema postgres) su entrambi i server.
• Rete: Il server Standby deve essere in grado di connettersi al server Primario sulla porta PostgreSQL (default 5432).

Passo 1: Configurare il Server Primario

Il server primario deve essere configurato per generare e servire i file WAL per la replica.

1.1 Modificare postgresql.conf

Modifica il file di configurazione principale. Sui pacchetti Debian e Ubuntu si trova spesso in /etc/postgresql/<versione>/main/postgresql.conf; su molte installazioni da sorgente o container risiede nella directory dei dati. Imposta questi parametri:

# Consenti connessioni da altri host
listen_addresses = '*'

# Imposta il livello WAL su 'replica' o superiore
wal_level = replica

# Numero massimo di connessioni concorrenti dai server standby
max_wal_senders = 5 

# Controlla il numero di connessioni standby che possono essere attive simultaneamente
max_replication_slots = 5

# Consente query di sola lettura sullo standby
hot_standby = on

1.2 Creare un Utente di Replica Dedicato

Per sicurezza, crea un utente specifico con l'attributo REPLICATION. Questo utente sarà utilizzato solo dal server standby per prelevare i record WAL.

# Connettiti a PostgreSQL
sudo -u postgres psql -c "CREATE ROLE replica_user WITH REPLICATION LOGIN PASSWORD 'usa-un-segreto-reale-qui';"

1.3 Aggiornare l'Autenticazione Client (pg_hba.conf)

Consenti all'utente di replica dall'indirizzo IP del server standby di connettersi al pseudo-database speciale replication.

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

1.4 Riavviare il Server Primario

Applica le modifiche di configurazione. Un riavvio è l'opzione semplice dopo aver cambiato listen_addresses; se hai modificato solo pg_hba.conf, è sufficiente un ricaricamento.

sudo systemctl restart postgresql

Passo 2: Preparare il Server Standby

Prima di clonare i dati, assicurati che il servizio PostgreSQL dello standby sia fermo e che la sua directory dati esistente sia cancellata.

2.1 Fermare il Servizio PostgreSQL dello Standby

sudo systemctl stop postgresql

2.2 Cancellare la Directory Dati

Attenzione: Questo passaggio elimina permanentemente tutti i dati attualmente nella directory dati dello standby. Conferma il percorso prima dell'esecuzione.

# Esempio di percorso per PG 14
PG_DATA=/var/lib/postgresql/14/main

sudo rm -rf $PG_DATA/*

2.3 Clonare i Dati Usando pg_basebackup

Usa pg_basebackup per creare una copia esatta della directory dati del primario. Il flag -R è cruciale perché genera automaticamente i file di configurazione necessari (standby.signal e primary_conninfo) per la replica in streaming (PostgreSQL 12+).

Esegui questo comando sul server Standby:

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

Opzione	Descrizione
-h	Nome host o indirizzo IP del server primario.
-D	Percorso della directory dati locale.
-U	Nome utente di replica (replica_user).
-P	Mostra progresso.
-v	Output dettagliato.
-R	Crea automaticamente un file di configurazione della replica.

Passo 3: Configurare e Avviare lo Standby

3.1 Verificare la Configurazione dello Standby

Se hai usato il flag -R nel Passo 2.3, pg_basebackup ha creato un file standby.signal e popolato l'impostazione primary_conninfo, di solito in un file di configurazione generato chiamato postgresql.auto.conf all'interno della directory dati.

Verifica il contenuto della stringa primary_conninfo. Dovrebbe assomigliare a questa (controlla all'interno di $PG_DATA/postgresql.auto.conf):

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

Suggerimento: Assicurati che la password sia inclusa in primary_conninfo o che tu stia usando l'autenticazione basata su certificati. Se usi pg_hba.conf con trust o cert, la password può essere omessa.

3.2 Avviare il Servizio Standby

Poiché il file di segnale richiesto (standby.signal) è presente nella directory dati, il servizio si avvierà in modalità standby di sola lettura e tenterà immediatamente di connettersi al primario.

sudo systemctl start postgresql

Passo 4: Verificare la Replica in Streaming

Dopo aver avviato lo standby, devi confermare che la connessione sia attiva e che la sincronizzazione dei dati stia avvenendo.

4.1 Verifica sul Server Primario

Connettiti al server primario e interroga la vista pg_stat_replication. Dovresti vedere una riga che rappresenta la connessione dal server standby.

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

Output Atteso (Campi Chiave):

• client_addr: Dovrebbe corrispondere all'IP del server standby (ad es. 192.168.1.11).
• state: Dovrebbe essere streaming. Se mostra startup o catching up, attendi un momento. Se mostra walsender in avvio, sei vicino.
• sync_state: Dovrebbe essere async (per la replica asincrona standard).

4.2 Testare la Sincronizzazione dei Dati

Per confermare il flusso di dati, esegui una modifica sul primario e verifica immediatamente la sua esistenza sullo standby.

Sul Primario:

CREATE TABLE replication_test (id serial primary key, message text);
INSERT INTO replication_test (message) VALUES ('Dati sincronizzati con successo');

Sullo Standby (Sola Lettura):

-- Questo deve riuscire senza errori
psql -c "SELECT * FROM replication_test;"

Se i dati sono visibili sullo standby, la replica in streaming è configurata e attiva con successo.

Best Practice e Risoluzione dei Problemi

Connessione Persistente: Replication Slots

Sebbene opzionali, i replication slots sono altamente raccomandati. Un replication slot garantisce che il server primario non scarti prematuramente i segmenti WAL necessari allo standby, anche se lo standby si disconnette temporaneamente.

Sul Primario:

SELECT * FROM pg_create_physical_replication_slot('standby_slot_name');

Poi imposta primary_slot_name sullo standby. Non inserire il nome dello slot all'interno di primary_conninfo.

primary_conninfo = 'host=192.168.1.10 user=replica_user password=usa-un-segreto-reale-qui application_name=standby_node'
primary_slot_name = 'standby_slot_name'

Attenzione: I replication slots richiedono un monitoraggio attento. Se uno standby fallisce per un periodo prolungato, i file WAL accumulati protetti dallo slot possono riempire rapidamente lo spazio su disco del server primario.

Risoluzione dei Problemi Comuni

Problema	Causa Potenziale	Soluzione
Lo standby non riesce a connettersi	Firewall di rete, listen_addresses errato o pg_hba.conf non corretto sul primario.	Verifica che la porta 5432 sia raggiungibile; conferma che pg_hba.conf corrisponda all'IP dello standby e all'utente.
pg_basebackup fallisce con errore di autenticazione	Password errata o voce host mancante in pg_hba.conf.	Ricontrolla la password per replica_user; assicurati che il database primario sia stato riavviato dopo la modifica di pg_hba.conf.
Lo standby è in sola lettura	Questo è il comportamento previsto.	La presenza di standby.signal forza il server in modalità di recupero.

Passo Successivo

Configurare la replica in streaming è un passo critico nella costruzione di un'architettura PostgreSQL resiliente. Seguendo questi passaggi, hai configurato con successo una coppia primario-standby che garantisce una sincronizzazione continua dei dati, migliorando significativamente le capacità di alta disponibilità del tuo sistema. Il passo logico successivo è integrare una soluzione di monitoraggio e un meccanismo di failover (come Patroni o Repmgr) per automatizzare completamente la configurazione HA.