55.4. Protocole de réplication en flux

» » »

Précédent	Niveau supérieur	Suivant
55.3. Authentification SASL	Sommaire	55.5. Logical Streaming Replication Protocol

55.4. Protocole de réplication en flux

Pour initier une réplication en flux, le client envoie le paramètre replication dans le message de démarrage. Une valeur booléenne à true (ou on, yes, 1) indique au backend d'entrer dans le mode walsender de réplication physique, dans lequel un petit ensemble de commandes de réplication, affichées ci-dessous, peut être exécutées à la place de requêtes SQL.

Passer database comme valeur du paramètre replication instruit le backend à entrer en mode walsender de réplication logique, se connectant à la base de données spécifiée par le paramètre dbname. Dans le mode walsender de réplication logique, les commandes de réplication affichées ci-dessous peuvent être exécutées ainsi que des commandes SQL standards.

Dans les deux modes walsender, seul le protocole de requête simple peut être utilisé.

Dans le but de tester des commandes de réplication, vous pouvez faire une connexion de réplication via l'outil psql ou tout autre outil utilisant la bibliothèque libpq avec une chaîne de connexion incluant l'option replication, par exemple :

psql "dbname=postgres replication=database" -c "IDENTIFY_SYSTEM;"

Néanmoins, il est souvent plus utile d'utiliser pg_receivewal (pour la réplication physique) ou pg_recvlogical (pour la réplication logique).

Les commandes de réplication sont tracées dans les journaux applicatifs du serveur quand log_replication_commands est activé.

Les commandes acceptées en mode réplication sont :

IDENTIFY_SYSTEM

Demande au serveur de s'identifier. Le serveur répond avec un ensemble de résultats contenant une ligne composée de quatre champs :

systemid (text): L'identifiant système unique de l'instance. Ceci peut être utilisé pour vérifier que la sauvegarde utilisée pour initialiser le serveur secondaire provient bien de la même instance.
timeline (int4): Identifiant de timeline actuel. Aussi utile pour vérifier que le serveur secondaire est cohérent avec le primaire.
xlogpos (text): Emplacement actuel de vidage des journaux de transactions. Utile pour obtenir un emplacement connu dans les journaux de transactions où commencer le flux.
dbname (text): Base de données où se connecter, ou NULL.

SHOW nom

Demande au serveur d'envoyer la configuration actuelle d'un paramètre. C'est similaire à la commande SQL SHOW.

nom: Le nom d'un paramètre. Les paramètres disponibles sont documentées dans Chapitre 20.

TIMELINE_HISTORY tli

Demande au serveur d'envoyer le fichier d'historique des timelines pour la timeline tli. Le serveur répond avec un ensemble de résultat d'une seule ligne comprenant deux champs. Bien que les champs soient du type text, elles renvoient réellement des octets bruts sans conversion d'encodage :

filename (text): Nom du fichier d'historique des timelines, par exemple 00000002.history.
content (text): Contenu du fichier d'historique des timelines.

CREATE_REPLICATION_SLOT nom_slot [ TEMPORARY ] { PHYSICAL | LOGICAL plugin_sortie } [ ( option [, ...] ) ]

Crée un slot de réplication physique ou logique. Voir Section 27.2.6 pour plus d'informations sur les slots de réplication.

nom_slot: Le nom du slot à créer. Ce doit être un nom valide pour un slot de réplication (voir Section 27.2.6.1).
output_plugin: Le nom du plugin de sortie utilisé pour le décodage logique (voir Section 49.6).
TEMPORARY: Indique que ce slot de réplication est un slot temporaire. Les slots temporaires ne sont pas sauvegardés sur disque et sont automatiquement supprimés en cas d'erreur ou quand la session est terminée.

Les options suivantes sont acceptées :

TWO_PHASE [ boolean ]: Si true, ce slot de réplication logique accepte le décodage des validations en deux phases. Avec cette option, les commandes relatives au 2PC telles que PREPARE TRANSACTION, COMMIT PREPARED et ROLLBACK PREPARED sont décodées et transmises. La transaction sera décodée et transmise au moment du PREPARE TRANSACTION. La valeur par défaut est false.
RESERVE_WAL [ boolean ]: Si true, ce slot de réplication physique réserve immédiatement les WAL. Sinon, les WAL sont seulement réservés à la connexion d'un client de réplication en flux. La valeur par défaut est false.
SNAPSHOT { 'export' | 'use' | 'nothing' }: Décide ce qu'il faut faire du snapshot créé lors de l'initialisation du slot logique. 'export', qui est la valeur par défaut, exportera le snapshot à utiliser dans d'autres sessions. Cette option ne peut pas être utilisée à l'intérieur d'une transaction. 'use' utilisera le snapshot pour la transaction courante exécutant la commande. Cette option doit être utilisée dans une transaction, et CREATE_REPLICATION_SLOT doit être la première commande exécutée dans cette transaction. Enfin, 'nothing' utilisera uniquement le snapshot pour le décodage logique comme d'habitude mais ne fera rien de plus avec.

En réponse à cette commande, le serveur enverra un ensemble de résultat d'une ligne contenant les champs suivants :

slot_name (text): Le nom du slot de réplication nouvellement créé.
consistent_point (text): L'emplacement dans les WAL à partir duquel le slot devient cohérent. C'est l'emplacement le plus proche à partir duquel le flux peut commencer sur ce slot de réplication.
snapshot_name (text): L'identifiant du snapshot exporté par la commande. Le snapshot est valide jusqu'à l'exécution d'une nouvelle commande sur cette connexion ou jusqu'à la fermeture de la connexion de réplication. NULL si le slot créé est physique.
output_plugin (text): Le nom du plugin de sortie utilisé par le slot de réplication nouvellement créé. NULL si le slot créé est physique.

CREATE_REPLICATION_SLOT slot_name [ TEMPORARY ] { PHYSICAL [ RESERVE_WAL ] | LOGICAL output_plugin [ EXPORT_SNAPSHOT | NOEXPORT_SNAPSHOT | USE_SNAPSHOT | TWO_PHASE ] }

Pour la compatibilité avec les anciennes versions, cette syntaxe alternative pour CREATE_REPLICATION_SLOT est toujours acceptée.

READ_REPLICATION_SLOT slot_name

Lit certaines informations associées avec un slot de réplication. Renvoie une ligne avec des valeurs NULL si le slot de réplication n'existe pas. Cette commande est actuellement uniquement acceptée pour les slots de réplication physique.

En réponse à cette commande, le serveur renverra un ensemble de résultats d'une ligne, contenant les champs suivants :

slot_type (text): Le type du slot de réplication, soit physical soit NULL.
restart_lsn (text): Le restart_lsn du slot de réplication.
restart_tli (int8): L'identifiant de timeline associé avec restart_lsn, suivant l'historique actuelle des timelines.

START_REPLICATION [ SLOT slot_name ] [ PHYSICAL ] XXX/XXX [ TIMELINE tli ]

Demande au serveur de commencer le flux de WAL, en commençant à l'emplacement XXX/XXX. Si l'option TIMELINE est spécifiée, le flux commence sur la timeline tli ; sinon la timeline actuelle du serveur est sélectionnée. Le serveur peut répondre avec une erreur, par exemple si la section demandée de WAL a déjà été recyclée. En cas de succès, le serveur répond avec un message CopyBothResponse, puis commence le flux de WAL vers le client.

Si un nom de slot est fourni via slot_name, il sera mis à jour au fur et à mesure de la progression de la réplication pour que le serveur se rappelle des segments WAL et, si hot_standby_feedback vaut on, des transactions toujours nécessaires pour le secondaire.

If the client requests a timeline that's not the latest but is part of the history of the server, the server will stream all the WAL on that timeline starting from the requested start point up to the point where the server switched to another timeline. If the client requests streaming at exactly the end of an old timeline, the server skips COPY mode entirely.

Après le flux de tous les WAL d'une timeline qui n'est pas la dernière, le serveur terminera le flux en sortant du mode COPY. Quand le client reconnait cette situation en quittant lui aussi le mode COPY, le serveur envoie un ensemble de résultats d'une ligne et de deux colonnes, indiquant la prochaine timeline dans l'historique du serveur. La première colonne est l'identifiant de la prochaine timeline (type int8), et la deuxième colonne est l'emplacement des WAL où la bascule a eu lieu (type text). Habituellement, la position de bascule est la fin du WAL en cours de flux, mais il existe des cas particuliers où le serveur peut envoyer certains WAL de l'ancienne timeline qu'il n'a pas encore rejoué avant la promotion. Enfin, le serveur envoie deux messages CommandComplete (un qui termine le CopyData et l'autre qui termine le START_REPLICATION lui-même), et est prêt à accepter une nouvelle commande.

Les données WAL sont envoyées sous la forme d'une série de messages CopyData. (Ceci permet le mélange d'autres informations ; en particulier, le serveur peut envoyer un message ErrorResponse s'il rencontre un échec après le début du flux.) La charge de chaque message CopyData du serveur vers le client contient un message sur un des formats suivants :

XLogData (B)

Byte1('w')

Identifie le message comme des données WAL.

Int64

Le début des données WAL dans ce message.

Int64

La fin actuelle des WAL sur le serveur.

Int64

L'horloge système du serveur au moment de la transmission, en microsecondes depuis le 1er janvier 2000 à minuit.

Byten

Une section du flux de données WAL.

Un enregistrement WAL seul n'est jamais divisé en deux messages XLogData. Quand un enregistrement WAL arrive sur une limite de page d'un WAL et est, de ce fait, déjà divisé en utilisant les enregistrements de continuité, il peut être divisé sur la limite de la page. Autrement dit, le premier enregistrement WAL principal et ses enregistrements de continuité peuvent être envoyés dans différents messages XLogData.

Primary keepalive message (B)

Byte1('k'): Identifie le message comme un keepalive de l'envoyeur.
Int64: La fin actuelle du WAL sur le serveur.
Int64: L'horloge système du serveur au moment de la transmission, en microsecondes depuis le 1er janvier 2000.
Byte1: 1 signifie que le client devrait répondre à ce message aussi vite que possible pour éviter une déconnexion par dépassement de délai d'attente.

Le processus en réception peut envoyer des réponses à l'émetteur à tout moment, en utilisant un des formats de message suivants (aussi dans la charge d'un message CopyData) :

Standby status update (F)

Byte1('r'): Identifie le message comme mise à jour du statut du receveur.
Int64: L'emplacement du dernier octet du WAL + 1 réçu et écrit sur disque par le secondaire.
Int64: L'emplacement du dernier octet du WAL + 1 vidé sur disque par le secondaire.
Int64: L'emplacement du dernier octet du WAL + 1 appliqué sur disque par le secondaire.
Int64: L'horloge système du serveur au moment de la transmission, en microsecondes depuis le 1er janvier 2000.
Byte1: Si 1, le client demande au serveur de répondre immédiatement à ce message. Ceci peut être utilisé pour appeler le serveur, pour tester si la connexion est toujours active.

Hot standby feedback message (F)

Byte1('h'): Identifie le message comme un message de retour d'informations du serveur secondaire.
Int64: L'horloge système du serveur au moment de la transmission, en microsecondes depuis le 1er janvier 2000.
Int32: Le xmin global actuel du secondaire, excluant le catalog_xmin de tout slot de réplication. Si cette valeur et le catalog_xmin suivant sont à 0, ceci est traité comme une notification que le retour du secondaire ne sera plus envoyé sur cette connexion. Des messages ultérieurs différents de zéro pourraient ré-initier le mécanisme de retour.
Int32: Le nombre epoch du xmin xid global sur le serveur secondaire.
Int32: Le catalog_xmin le plus bas de tout slot de réplication sur le secondaire. Configuré à 0 si aucun catalog_xmin n'existe sur le secondaire ou si le retour d'informations du secondaire est en cours de désactivation.
Int32: Le nombre epoch du XID catalog_xmin sur le secondaire.

START_REPLICATION SLOT slot_name LOGICAL XXX/XXX [ ( option_name [ option_value ] [, ...] ) ]

Demande au serveur de commencer le flux de WAL pour la réplication logique, en commençant soit à la position WAL XXX/XXX soit à la position confirmed_flush_lsn du slot (voir Section 54.19), suivant la position la plus grande. Ce comportement facilite la tache pour les clients qui évitent ainsi de mettre à jour le statut LSN local quand il n'y a aucune donnée à traiter. Cependant, commencer à un LSN différent de celui demandé pourrait ne pas récupérer certaines types d'erreurs clients ; donc le client pourrait souhaiter vérifier que confirmed_flush_lsn correspond à ses attentes avant de lancer START_REPLICATION.

Le serveur peut répondre avec une erreur, par exemple si le slot n'existe pas. En cas de succès, le serveur répond avec un message CopyBothResponse, puis lance le flux de WAL vers le client.

Le message à l'intérieur des messages CopyBothResponse sont du même format documenté que pour START_REPLICATION ... PHYSICAL, ceci incluant les deux messages CommandComplete.

Le plugin de sortie associé avec le slot sélectionné est utilisé pour traiter la sortie pour le flux.

SLOT slot_name: Le nom du slot pour lequel envoyer en flux les changements. Ce paramètre est requis, et doit correspondre à un slot existant de réplication logique créé avec CREATE_REPLICATION_SLOT dans le mode LOGICAL mode.
XXX/XXX: L'emplacement dans le WAL à partir duquel commence le flot.
option_name: Le nom d'une option passée au plugin de décodage logique du slot. Voir Section 55.5 pour les options qui sont acceptées par le plugin standard (pgoutput).
option_value: Valeur optionnelle, sous le forme d'une constante de type chaîne de caractères, associée à l'option indiquée.

DROP_REPLICATION_SLOT slot_name [ WAIT ]

Supprime un slot de réplication, libérant toute ressource réservée. Si le slot est un slot logique créé dans une base de données autre que celle de connexion du walsender, cette commande échoue.

slot_name: Le nom du slot à supprimer.
WAIT: Cette option force la commande à attendre si le slot est actif et jusqu'à ce que ce dernier devienne inactif. Dans le cas contraire, une erreur est levée (comportement par défaut).

BASE_BACKUP [ ( option [, ...] ) ]

Demande au serveur le lancement d'une sauvegarde en flux. Le système sera automatiquement placé en mode sauvegarde avant que la sauvegarde ne commence, et sorti de ce mode quand la sauvegarde est terminée. Les options suivantes sont acceptées :

LABEL 'label'

Configure le label de la sauvegarde. Si aucun label n'est donné, le label base backup sera utilisé. Les règles de guillemet pour le label sont les mêmes que pour une chaîne SQL standard lorsque standard_conforming_strings vaut on.

TARGET 'target'

Indique au serveur où envoyer la sauvegarde. Si la cible est client (ce qui est la valeur par défaut), les données de la sauvegarde sont envoyées au client. Si elle vaut server, les données de la sauvegarde sont écrites sur le serveur dans le chemin indiqué par l'option TARGET_DETAIL. Si elle vaut blackhole, les données de la sauvegarde ne sont pas envoyées ; elles sont simplement ignorées.

La cible server nécessite l'attribut SUPERUSER ou être membre du rôle pg_write_server_files.

TARGET_DETAIL 'detail'

Fournit des informations supplémentaires sur la cible de sauvegarde.

Actuellement, cette option peut seulement être utilisée quand la cible de sauvegarde est server. Elle indique le répertoire du serveur, répertoire dans lequel la sauvegarde sera écrite.

PROGRESS [ boolean ]

Si configuré à true, réclame des informations nécessaires pour générer un rapport de progression. Cela enverra une taille approximative dans l'en-tête de chaque tablespace, qui peut être utilisé pour calculer le reste du flux. Le calcul se fait en énumérant toutes les tailles de fichier avant que le transfert ne commence, et cela pourrait avoir un impact négatif sur les performances. En particulier, cela pourrait prendre du temps avant que les premières données ne soient envoyées. Comme les fichiers de la base peuvent évoluer pendant la sauvegarde, la taille n'est qu'approximative, et pourrait soit augmenter soit diminuer entre le moment de l'approximation et celui de l'envoi des fichiers. La valeur par défaut est false.

CHECKPOINT { 'fast' | 'spread' }

Configure le type de checkpoint à réaliser au début de la sauvegarde. La valeur par défaut est spread.

WAL [ boolean ]

Si configuré à true, inclut les segments WAL nécessaires dans la sauvegarde. Cela inclura tous les fichiers entre le début et la fin de la sauvegarde, et ils seront placés dans le répertoire pg_wal du répertoire principal. La valeur par défaut est false.

WAIT [ boolean ]

Si configuré à true, la sauvegarde attendra jusqu'à ce que le dernier segment WAL requis soit archivé ou émettra un message d'avertissement si l'archivage des journaux de transactions n'est pas activé. Si false, la sauvegarde n'attendra pas et ne préviendra pas, laissant le client responsable de la vérification de la disponibilité du dernier segment WAL. La valeur par défaut est false.

COMPRESSION 'method'

Demande au serveur de compresser la sauvegarde en utilisant la méthode indiquée. Actuellement, les méthodes acceptées sont gzip, lz4 et zstd.

COMPRESSION_DETAIL detail

Donne les détails sur la méthode de compression choisie. Ceci devrait être utilisé en conjonction avec l'option COMPRESSION. Si la valeur est un entier, elle indique le niveau de compression. Sinon, elle peut être une liste d'éléments séparés par des virgules, chaque élément étant de la forme motclé ou motclé=valeur. Actuellement, les mots clés acceptés sont level et workers.

Le mot clé level configure le niveau de compression. Pour gzip, le niveau de compression devrait être un entier compris entre 1 et 9 (par défaut Z_DEFAULT_COMPRESSION ou -1), pour lz4 un entier compris entre 1 et 12 (par défaut 0 pour le mode de compression rapide), et pour zstd un entier compris entre ZSTD_minCLevel() (habituellement -131072) et ZSTD_maxCLevel() (habituellement 22), (par défaut ZSTD_CLEVEL_DEFAULT ou 3).

Le mot clé workers configure le nombre de threads devant être utilisé pour paralléliser la compression. Cette fonctionnalité n'est disponible qu'avec zstd.

MAX_RATE rate

Limite la quantité maximale de données transférées du serveur au client par unité de temps. L'unité attendue est du Ko par seconde. Si cette option est indiqué, la valeur doit être soit égale à zéro, soit être compris dans l'intervalle allant de 32 ko à 1 Go (valeurs inclues). Si un zéro est passé ou si l'option n'est pas indiquée, aucune restriction n'est imposée pendant le transfert.

TABLESPACE_MAP [ boolean ]

Si true, inclut des informations sur les liens symboliques présents dans le répertoire pg_tblspc dans un fichier nommé tablespace_map. Le fichier de cartographie des tablespaces inclut, pour chaque tablespace, le nom du lien symbolique dans le répertoire pg_tblspc/ et le chemin complet de ce lien symbolique. La valeur par défaut est false.

VERIFY_CHECKSUMS [ boolean ]

Si true, les sommes de contrôle sont vérifiées lors d'une sauvegarde si elles sont activées. Si false, elles sont ignorées. La valeur par défaut est true.

MANIFEST manifest_option

Quand cette option est indiquée avec une valeur yes ou force-encode, un manifest de sauvegarde est créé et envoyé avec la sauvegarde. Le manifeste est une liste de chaque fichier présent dans la sauvegarde à l'exception des fichiers WAL qui y sont inclus. Il enregistre aussi la taille, l'horodatage de la dernière modification et en option une somme de contrôle pour chaque fichier. Une valeur de force-encode force tous les noms de fichier à être codé en hexadécimal ; sinon ce type d'encodage est réalisé seulement pour les fichiers dont le nom est une séquence d'octets non UTF8. force-encode existe principalement pour des tests, pour être sûr que les clients qui lisent le manifeste de sauvegarde puissent gérer ce cas. Pour la compatibilité avec les anciennes versions, la valeur par défaut est MANIFEST 'no'.

MANIFEST_CHECKSUMS checksum_algorithm

Précise l'algorithme des sommes de contrôle, à appliquer à chaque fichier inclus dans le manifeste de sauvegarde. Actuellement, les seuls algorithmes disponibles sont NONE, CRC32C, SHA224, SHA256, SHA384 et SHA512. La valeur par défaut est CRC32C.

Quand la sauvegarde est lancée, le serveur enverra tout d'abord deux ensembles de résultats ordinaires, suivis par un ou plusieurs résultats CopyOutResponse.

Le premier ensemble de résultat contient la position de départ de la sauvegarde, sur une liste ligne comprenant deux colonnes. La première colonne contient la position de départ donné dans un format correspondant à XLogRecPtr, et la deuxième colonne contient l'identifiant de la timeline correspondante.

Le deuxième ensemble de résultat a une ligne pour chaque tablespace. Voici la liste des champs de cette ligne :

spcoid (oid): L'OID du tablespace, ou NULL s'il s'agit du répertoire principal.
spclocation (text): Le chemin complet du répertoire du tablespace, ou NULL si c'est le répertoire principal.
size (int8): La taille approximative du tablespace, en kilooctets (1024 octets), si le rapport de progression a été demandé ; sinon NULL.

Après le deuxième ensemble de résultats, un message CopyOutResponse sera envoyé. La chaque de chaque message CopyData contiendra un message dans un des formats suivants :

new archive (B)

Byte1('n'): Identifie le messaage comme indiquant le début d'une nouvelle archive. Il y a aura une archive pour le répertoire principal des données et une archive pour chaque tablespace supplémentaire ; chacune utilisera le format tar (en suivant le format « ustar interchange format » spécifié dans le standard POSIX 1003.1-2008).
String: Le nom du fichier pour cette archive.
String: Pour le répertoire principal des données, une chaîne vide. Pour les autres tablespaces, le chemin complet vers le répertoire à partir duquel cette archive a été créée.

manifest (B)

Byte1('m'): Identifie le message comme indiquant le début d'un manifeste de sauvegarde.

archive or manifest data (B)

Byte1('d'): Identifie le message comme contenant une archive ou des données du manifeste.
Byten: Octets des données.

progress report (B)

Byte1('p'): Identifie le message comme un rapport de progression.
Int64: Le nombre d'octets du tablespace actuel pour lequel le traitement a terminé.

Après que le CopyOutResponse et tous ces types de réponses aient été envoyés, un ensemble de résultat ordinaire final sera envoyé, contenant la position finale dans les WAL de la sauvegarde, dans le même format que la position de départ.

L'archive tar pour le répertoire de données principal et pour chaque tablespace contiendra tous les fichiers des répertoires, qu'ils appartiennent à PostgreSQL ou pas (fichiers ajoutées dans le même répertoire). Les fichiers exclus sont :

postmaster.pid
postmaster.opts
pg_internal.init (trouvé dans plusieurs répertoires)
Différents fichiers et répertoires temporaires créés pendant les opérations du serveur PostgreSQL, tels que les fichiers ou répertoire commençant avec pgsql_tmp et les objets temporaires.
Relations non journalisées, sauf pour le type init qui est requis pour recréer à vide les relations non journalisés lors d'une restauration.
pg_wal, en incluant les sous-répertoires. Si la sauvegarde est exécuté avec les fichiers WAL inclus, une version synthétisée de pg_wal sera inclus, mais elle contiendra seulement les fichiers nécessaires pour que la sauvegarde fonctionne, et pas le reste du contenu.
pg_dynshmem, pg_notify, pg_replslot, pg_serial, pg_snapshots, pg_stat_tmp et pg_subtrans sont copiés sous la forme de répertoires vides (même s'il s'agit de lien symbolique).
Fichiers autres que les fichiers et répertoires standards, tels que des liens symboliques (autre que pour les répertoires indiqués ci-dessus), les fichiers périphériques et les fichiers du système d'exploitation. Les liens symboliques dans pg_tblspc sont maintenus.)

Propriétaire, groupe et droits sont configurés si le système de fichiers sous-jacent l'accepte.