pg_receivewal — suit le flux des journaux de transactions d'un serveur PostgreSQL
pg_receivewal
[option
...]
pg_receivewal est utilisé pour suivre le flux des journaux de transactions d'une instance de PostgreSQL en cours d'activité. Les journaux de transactions sont suivis en utilisant le flux du protocole de réplication, et sont écrits sous forme de fichiers dans un répertoire local. Ce répertoire peut être utilisé comme emplacement des archives dans l'optique d'une restauration utilisant le mécanisme de sauvegarde à chaud et de récupération à un instant t (PITR, voir Section 25.3).
pg_receivewal suit le flux des journaux de transactions en temps réel alors qu'il est généré sur le serveur principal. Il n'attend pas la fin de l'écriture d'un segment complet d'un journal de transactions comme archive_command et archive_library le font. Pour ces raisons, il n'est pas nécessaire de configurer archive_timeout lors de l'utilisation de pg_receivewal
Contrairement au receveur de WAL d'un serveur PostgreSQL standby,
pg_receivewal place les données WAL sur disque
par défaut uniquement quand un fichier WAL est fermé. L'option
--synchronous
doit être ajoutée pour que les données WAL
soient écrites en temps réel. Comme pg_receivewal
n'applique pas les WAL, vous ne devez pas lui permettre de devenir un
standby synchrone quand synchronous_commit vaut
remote_apply
. Dans le cas contraire, ce sera un standby
qui ne réussit jamais à rattraper son retard et causera le blocage des
validations des transactions. Pour éviter ceci, vous devez soit configurer
une valeur appropriée pour synchronous_standby_names,
soit spécifier une valeur pour le paramètre
application_name
pour
pg_receivexlog qui ne correspond pas, soit
modifier la valeur du paramètre synchronous_commit
à
quelque chose d'autres que remote_apply
.
Le journal de transactions est envoyé via une connexion
PostgreSQL traditionnelle, et utilise le
protocole de réplication. La connexion doit être créée avec un compte
superutilisateur ou utilisateur disposant des droits
REPLICATION
(voir Section 21.2) et
le fichier pg_hba.conf
doit permettre la connexion de
réplication. Le serveur doit aussi être configuré avec une valeur
suffisamment haute du paramètre max_wal_senders pour
laisser au moins une session disponible pour le flux.
Le point de démarrage du flux des journaux de transactions est calculé quand pg_receivewal démarre :
Tout d'abord, il parcourt le répertoire où les segments de journaux de transactions sont écrits et trouver le segment terminé le plus récent pour l'utiliser comme point de départ du prochain segment.
Si un point de démarrage ne peut pas être calculé avec la méthode
précédente et si un slot de réplication est utilisé, une commande
READ_REPLICATION_SLOT
supplémentaire est exécutée pour
récupérer le restart_lsn
du slot et l'utiliser comme
point de démarrage. Cette option est seulement disponible quand les
journaux de transactions en flux proviennent de
PostgreSQL 15 ou ultérieur.
Si un point de démarrage ne peut pas être calculé avec la méthode
précédente, l'emplacement de vidage des journaux de transactions est
utilisé comme indiqué par le serveur à partir d'une commande
IDENTIFY_SYSTEM
.
Si la connexion est perdue ou si elle ne peux pas être établie
initialement, via une erreur non fatale,
pg_receivewal essaiera à nouveau indéfiniment,
et rétablira le flux dès que possible. Pour éviter ce comportement,
utilisez le paramètre -n
.
En l'absence d'erreurs fatales, pg_receivewal s'exécutera jusqu'à recevoir le signal SIGINT (Control+C) ou SIGTERM.
-D répertoire
--directory=répertoire
Répertoire dans lequel écrire le résultat.
Ce paramètre est obligatoire.
-E lsn
--endpos=lsn
Arrête automatiquement la réplication et quitte avec le code de sortie standard 0 une fois arrivé au LSN indiqué.
S'il n'y a pas d'enregistrement avec un LSN strictement identique à
lsn
, l'enregistrement sera traité.
--if-not-exists
Ne renvoie pas une erreur quand --create-slot
est
indiqué et qu'un slot de même nom existe déjà.
-n
--no-loop
N'effectue pas de nouvelle tentative en cas d'erreur à la connexion. À la place, le programme s'arrête en retournant une erreur.
--no-sync
Cette option force pg_receivewal
à ne pas imposer de
vider les données WAL sur disque. C'est plus rapide mais cela signifie
aussi qu'un crash du système d'exploitation peut laisser les segments
WAL corrompus. En règle général, cette option est utile pour des tests
mais ne devrait pas être utilisée lors de l'archivage de journaux de
transactions sur un système en production.
Cette option est incompatible avec --synchronous
.
-s intervalle
--status-interval=intervalle
Spécifie le rythme en secondes de l'envoi des paquets au serveur informant de l'état en cours. Ceci permet une supervision plus simple du progrès à partir du serveur. Une valeur de zéro désactive complètement la mise à jour périodique du statut, bien qu'une mise à jour sera toujours envoyée si elle est réclamée par le serveur pour éviter la déconnexion après un certain délai. La valeur par défaut est de 10 secondes.
-S slotname
--slot=nom_slot
Requiert l'utilisation d'un slot de réplication existant avec pg_receivewal (voir Section 26.2.6). Quand cette option est utilisée, pg_receivewal renverra une position de vidage au serveur, indiquant quand chaque segment a été synchronisé sur disque. Cela permet au serveur de supprimer ce segment s'il n'est pas utile ailleurs.
Quand le client de réplication pg_receivewal
est configuré sur le serveur comme un standby synchrone, l'utilisation
d'un slot de réplication renverra la position de vidage sur disque du
serveur, mais seulement lors de la fermeture d'un fichier WAL. De ce
fait, cette configuration entraînera que les transactions sur le
primaire attendront un long moment, ce qui aura pour effet de ne pas
fonctionner de manière satisfaisante. L'option
--synchronous
(voir ci- dessous) doit être ajoutée
pour que cela fonctionne correctement.
--synchronous
Vide les données WAL sur disque dès leur réception. De plus, envoie un
paquet de statut au serveur immédiatement après le vidage, quelque soit
la configuration de l'option --status-interval
.
Cette option doit être utilisée si le client de réplication de pg_receivewal est configuré en tant que serveur standby synchrone pour s'assurer que le retour est renvoyé à temps au serveur principal.
-v
--verbose
Active le mode verbeux.
-Z niveau
-Z méthode
[:détail
]
--compress=niveau
--compress=méthode
[:détail
]
Active la compression des journaux de transactions.
La méthode de compression peut être configurée à gzip
,
lz4
(si PostgreSQL a été
configuré avec --with-lz4
) ou none
pour aucune compression. Une chaîne de détails sur la compression peut
être indiquée en option. Si la chaîne est un entier, elle précise le
niveau de compression. Sinon, cela pourrait être une liste d'éléments
séparés par des virgules, chaque élément devant être de la forme
motclé
ou motclé=valeur
.
Actuellement, le seul mot clé supporté est level
.
Si aucun niveau de compression n'est indiqué, le niveau de compression par
défaut sera utilisé. Si seul un niveau est indiqué sans mention d'un
algorithme, la compression gzip
sera utilisée si le
niveau est supérieur à 0, et aucune compression ne sera utilisée si le
niveau vaut 0.
Le suffixe .gz
sera automatiquement ajouté à tous les
noms de fichier lors de l'utilisation de gzip
, et le
suffixe .lz4
sera ajouté lors de l'utilisation de
lz4
.
Les options en ligne de commande qui suivent permettent de paramétrer la connexion à la base de données.
-d connstr
--dbname=connstr
Spécifie les paramètres utilisés pour se connecter au serveur, sous la forme d'une chaîne de connexion. Elles surchargent toutes les options en ligne de commande conflictuelles.
Cette option est nommée --dbname
par cohérence avec
les autres applications clients mais, comme
pg_receivewal ne se connecte à aucune base
de données en particulier dans l'instance, tout nom de la base dans la
chaîne de connexion sera ignoré by
PostgreSQL. Des logiciels tiers ou des
proxys, utilisés dans la connexion à
PostgreSQL pourraient néanmoins utiliser
la valeur.
-h hôte
--host=hôte
Spécifie le nom de l'hôte de la machine sur lequel le serveur
s'exécute. Si la valeur commence par un slash, il est utilisé comme le
répertoire de la socket du domaine Unix (IPC). La valeur par défaut est
issue de la variable d'environnement PGHOST
, si elle est
définie, sinon une connexion à une socket du domaine Unix est tentée.
-p port
--port=port
Spécifie le port TCP ou l'extension du fichier de la socket du domaine
Unix sur lequel le serveur va écouter les connexions. La valeur par
défaut est issue de la variable d'environnement PGPORT
,
si elle est définie, ou d'une valeur définie lors de la compilation.
-U nom_utilisateur
--username=nom_utilisateur
L'utilisateur avec lequel se connecter.
-w
--no-password
Ne demande pas la saisie d'un mot de passe. Si le serveur nécessite un
mot de passe d'authentification et qu'aucun mot de passe n'est
disponible par d'autre biais comme le fichier
.pgpass
, la tentative de connexion échouera. Cette
option peut être utile dans des batchs où aucun utilisateur ne pourra
saisir un mot de passe.
-W
--password
Oblige pg_receivewal à demander un mot de passe avant de se connecter à la base.
Cette option n'est pas indispensable car
pg_receivewal demandera automatiquement un
mot de passe si le serveur nécessite une authentification par mot de
passe. Cependant, pg_receivewal perdra une
tentative de connexion avant de savoir si le serveur nécessite un mot
de passe. Dans certain cas, il est possible d'ajouter l'option
-W
pour éviter une tentative de connexion superflue.
pg_receivewal peut réaliser une des deux actions suivantes pour contrôler les slots de réplication physiques :
--create-slot
Crée un slot de réplication physique avec le nom spécifié par l'option
--slot
, puis quitte.
--drop-slot
Supprime le slot de réplication dont le nom est spécifié par l'option
--slot
, puis quitte.
D'autres options sont aussi disponibles :
-V
--version
Affiche la version de pg_receivewal et quitte le programme.
-?
--help
Affiche l'aide concernant les arguments en ligne de commande de pg_receivewal, et quitte le programme.
pg_receivewal sortira avec un code 0 quand il est terminé par le signal SIGINT ou SIGTERM. (C'est la façon normale de l'arrêter, d'où le fait qu'il ne s'agit pas d'une erreur.) Pour les erreurs fatales ou pour tout autre signal, le code de sortie sera différent de zéro.
Cet outil, comme la plupart des autres outils PostgreSQL, utilise les variables d'environnement supportées par libpq (voir Section 32.15).
La variable d'environnement PG_COLOR
indique s'il faut
utiliser les couleurs dans les messages de diagnostic. Les valeurs
possibles sont always
, auto
,
never
.
Lorsque vous utilisez pg_receivewal à la place de archive_command ou archive_library comme méthode principale de sauvegarde des WAL, il est fortement recommandé d'utiliser les slots de réplication. Dans le cas contraire, le serveur est libre de recycler ou supprimer les fichiers des journaux de transactions avant qu'ils ne soient sauvegardés car il n'a aucune information, provenant soit de archive_command, soit de archive_library soit des slots de réplication, sur la quantité de WAL déjà archivée. Néanmoins, notez qu'un slot de réplication remplira l'espace disque du serveur si le receveur n'arrive pas à suivre le rythme de récupération des données WAL.
pg_receivewal conservera les droits sur le groupe pour les fichiers WAL reçus si les droits du groupe sont activés sur l'instance source.
Pour suivre le flux des journaux de transactions du serveur
mon-serveur-de-donnees
et les stocker dans le répertoire
local /usr/local/pgsql/archive
:
$
pg_receivewal -h mon-serveur-de-donnees -D /usr/local/pgsql/archive