Documentation PostgreSQL 14.22 » Internes » Protocole client/serveur » Protocole de réplication en continu

Précédent | Niveau supérieur | Suivant
53.3. Authentification SASL | Sommaire | 53.5. Protocole de réplication logique en flux

## 53.4. Protocole de réplication en continu

Pour initier la réplication en flux continu, le client envoie le paramètre `replication` dans son message d'ouverture. Une valeur booléenne `true` (ou `on`, `yes`, `1`) indique au processus serveur de basculer en mode walsender pour la réplication physique, où un petit ensemble de commandes de réplication, montré ci-dessous, peut être exécuté à la place de requêtes SQL.

En passant `database` comme valeur du paramètre `replication`, on demande au backend de passer en mode walsender pour la réplication logique lors de la connexion à la base spécifiée dans le paramètre `dbname`. En mode walsender pour la réplication logique, les commandes de réplication montrées ci-dessous ainsi que les commandes SQL normales peuvent être utilisées.

En mode `walsender` pour la réplication physique ou pour la réplication logique, seul le protocole de messages Simple Query peut être utilisé.

Pour tester les commandes de réplication, vous pouvez réaliser une connexion de réplication via psql ou tout autre outil utilisant libpq avec une chaîne de connexion utilisant 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 enregistrées dans le journal du serveur lorsque 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 set de résultat d'une seule ligne contenant quatre champs:

  `systemid` (`text`)

    L'identifiant système unique du cluster. Il peut être utilisé pour vérifier que la base de sauvegarde utilisée pour initialiser le serveur en attente provient du même cluster.

  `timeline` (`int4`)

    Timeline ID courant. Tout aussi utile pour vérifier que le serveur en attente est consistant avec le primaire.

  `xlogpos` (`text`)

    Emplacement de vidage courant des journaux de transactions. Utile pour connaître un emplacement dans les journaux de transactions à partir duquel le mode de réplication en flux peut commencer.

  `dbname` (`text`)

    Base de données connectée ou NULL.

`SHOW` `nom`

  Demande au serveur d'envoyer la valeur actuelle d'un paramètre. Elle est identique à la commande SQL SHOW.

  `nom`

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

`TIMELINE_HISTORY` `tli`

  Demande au serveur l'envoi du fichier historique de la ligne de temps `tli`. Le serveur répond avec un résultat sur une seule ligne, contenant deux champs. Bien que les champs soient labelisés en tant que `text`, elles renvoient en fait des octets bruts, sans conversion d'encodage: :

  `filename` (`text`)

    Nom du fichier de l'historique de la ligne de temps, par exemple `00000002.history`.

  `content` (`text`)

    Contenu du fichier historique de la ligne de temps.

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

  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. Doit être un nom d'un slot de réplication valide (voir Section 27.2.6.1).

  `output_plugin`

    Le nom d'un plugin en sortie utilisé pour le décodage logique (voir Section 49.6).

  `TEMPORARY`

    Précise que ce slot de réplication est 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é.

  `RESERVE_WAL`

    Spécifie que le slot de réplication physique réserve les WAL immédiatement. Dans le cas contraire, les WAL sont seulement conservés à partir de la connexion d'un client de réplication en flux.

  `EXPORT_SNAPSHOT`
  `NOEXPORT_SNAPSHOT`
  `USE_SNAPSHOT`

    Décide quoi faire du snapshot créé lors de l'initialisation du slot de réplication. `EXPORT_SNAPSHOT`, qui est le défaut, exportera le snapshot à utiliser dans les autres sessions. Cette option ne peut pas être utilisée dans une transaction. `USE_SNAPSHOT` utiliser le snapshot pour la transaction 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, `NOEXPORT_SNAPSHOT` utilisera seulement le snapshot pour le décodage logique, mais ne fera rien de plus avec.

  En réponse à cette commande, le serveur enverra un résultat sur une seule ligne contenant les champs suivants :

  `slot_name` (`text`)

    Le nom du nouveau slot de réplication.

  `consistent_point` (`text`)

    L'emplacement dans les journaux à partir duquel le slot devient cohérent. C'est l'emplacement le plus proche à partir duquel la réplication en 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 d'une connexion de réplication. NULL si le slot créé est physique.

  `output_plugin` (`text`)

    Le nom du plugin de sortie utilisé par le nouveau slot de réplication. NULL si le slot créé est physique.

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

  Demande au serveur de débuter l'envoi de WAL en continu, en commençant à la position `XXX/XXX` dans le WAL. Si l'option `TIMELINE` est spécifiée, le flux commence sur la timeline `tli`. Dans le cas contraire, la timeline actuelle du serveur est utilisée. Le serveur peut répondre avec une erreur, par exemple si la section de WAL demandée a déjà été recyclée. En cas de succès, le serveur répond avec un message CopyBothResponse et débute l'envoi en continu de WAL au client.

  Si un nom de slot est fourni via `nom_slot`, il sera mis à jour au fur et à mesure de la progression de la réplication pour que le serveur primaire connaisse les segments WAL qui sont toujours nécessaires au serveur standby. Si `hot_standby_feedback` est activé, la granularité est au niveau de chaque transaction.

  Si le client demande une timeline qui ne correspond pas à la dernière mais qui fait néanmoins partie de l'historique du serveur, le serveur va envoyer tous les journaux de transactions en commençant à partir de point de démarrage demandé sur cette timeline, jusqu'à arriver au moment où le serveur a changé de nouveau de timeline. Si le client réclame l'envoi à partir de la fin de l'ancienne timeline, le serveur ignore complètement le mode COPY.

  Après l'envoi de tous les journaux de transactions d'une timeline qui n'est pas la dernière, le serveur arrêtera le flux en quittant le mode COPY. Quand le client accepte ceci en quittant lui aussi le mode COPY, le serveur envoie un ensemble de résultats comprenant une ligne et deux colonnes, indiquant la prochaine timeline dans l'histoire de ce serveur. La première colonne est l'identifiant de la prochaine timeline (type `int8`) et la deuxième colonne est la position XLOG où la bascule a eu lieu (type `text`). Généralement, la position de la bascule correspond à la fin du journal de transactions qui a été envoyé mais, il existe des cas particuliers où le serveur peut envoyer quelques enregistrements de journaux à partir 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 un autre qui termine `START_REPLICATION`), et est prêt à accepter une nouvelle commande.

  Les données des WAL sont envoyées en une série de messages `CopyData` (ce qui permet d'envoyer d'autres informations dans les intervalles ; en particulier un serveur peut envoyer un message `ErrorResponse` s'il rencontre une erreur après le début de l'envoi en continu des données). Le contenu de chaque message `CopyData` à partir du serveur vers le client contient un message faisant partie d'un des formats suivants :

  XLogData (B)

    Byte1('w')

      Identifie le message comme une donnée de WAL.

    Int64

      Le point de départ de la donnée du WAL dans ce message.

    Int64

      Le fin courante du WAL sur le serveur.

    Int64

      L'horloge système du serveur à l'heure de la transmission, en microsecondes à partir du 1er janvier 2000, à minuit.

    Byte`n`

      Une section de donnée du flux de WAL.

      Un enregistrement d'un journal de transactions n'est jamais divisé en deux messages `XLogData`. Quand un enregistrement dépasse la limite d'une page d'un journal de transactions, et est de ce fait déjà divisé en utilisant les enregistrements de suivi, il peut être divisé sur la limite de la page. En d'autres termes, le premier enregistrement principal d'un journal de transactions et ses enregistrements de suivi peuvent être envoyés sur différents messages `XLogData`.

  Message principal de keepalive (B)

    Byte1('k')

      Identifie le message comme un keepalive émis.

    Int64

      La fin actuelle du journal de transactions sur le serveur.

    Int64

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

    Byte1

      1 signifie que le client doit répondre à ce message dès que possible pour éviter une déconnexion après délai. 0 dans les autres cas.

  Le processus en réception répond à l'envoyeur à tout moment en utilisant un des formats de message suivants (aussi dans la charge d'un message `CopyData`) :

  Mise à jour du statut du serveur en standby (F)

    Byte1('r')

      Identifie le message comme une mise à jour du statut du réceptionneur.

    Int64

      L'emplacement du dernier octet des journaux de transactions + 1 reçu et écrit sur le disque du serveur en standby.

    Int64

      L'emplacement du dernier octet du journal de transactions + 1 poussé sur le standby.

    Int64

      L'emplacement du dernier octet du journal de transactions + 1 appliqué sur le standby.

    Int64

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

    Byte1

      Si 1, le client demande une réponse immédiate du serveur à ce message. Cela peut être utilisé pour tester si la connexion est toujours bonne.

  Message de réponse Hot Standby (F)

    Byte1('h')

      Identifie le message comme un message de réponse Hot Standby.

    Int64

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

    Int32

      La valeur du xmin global actuel pour le serveur standby, excluant le catalog_xmin de tout slot de réplication. Si cette valeur et le catalog_xmin suivant valent 0, ceci est traité comme une notification qu'aucun retour du Hot Standby ne sera envoyé sur cette connexion. Les messages ultérieurs différents de 0 peuvent réinitialiser le mécanisme de retours d'informations.

    Int32

      La valeur epoch de l'identifiant de transaction xmin global sur le serveur standby.

    Int32

      La valeur minimale de catalog_xmin pour tout slot de réplication sur le standby. Configuré à 0 si aucun catalog_xmin n'existe sur le standby ou si le retour d'informations du serveur en Hot Standby est désactivé.

    Int32

      La valeur epoch de l'identifiant de transaction catalog_xmin sur le serveur standby.

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

  Indique au serveur de commencer le flux de réplication pour de la réplication logique, en commençant à la position `XXX/XXX` dans le journal des transactions. Le serveur peut répondre avec une erreur, par exemple si la section demandée du journal de transactions a déjà été recyclée. En cas de succès, le serveur répond avec un message CopyBothResponse, puis commence à envoyer le flux vers le client.

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

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

  `SLOT` `nom_slot`

    Le nom du slot. Ce paramètre est requis et doit correspond à un slot de réplication existant créé avec `CREATE_REPLICATION_SLOT` en mode `LOGICAL`.

  `XXX/XXX`

    La position WAL où commencer le flux.

  `option_name`

    Le nom d'une option passée au plugin de décodage logique du slot. Voir Section 53.5 pour les options qui sont acceptées par le plugin standard (`pgoutput`).

  `option_value`

    Une valeur en option, sous la forme d'une chaîne de caractères, associée à l'option indiquée.

`DROP_REPLICATION_SLOT` `nom_slot` [ `WAIT` ]

  Supprime un slot de réplication, libérant toute ressource réservée du côté serveur.

  `nom_slot`

    Le nom du slot à supprimer.

  `WAIT`

    Cette option fait en sorte que la commande attende si le slot est actif jusqu'à ce qu'il devienne inactif. Le comportement par défaut revient à lever une erreur.

`BASE_BACKUP` [ `LABEL` `'label'` ] [ `PROGRESS` ] [ `FAST` ] [ `WAL` ] [ `NOWAIT` ] [ `MAX_RATE` `rate` ] [ `TABLESPACE_MAP` ] [ `NOVERIFY_CHECKSUMS` ] [ `MANIFEST` `manifest_option` ] [ `MANIFEST_CHECKSUMS` `checksum_algorithm` ]

  Demande au serveur de commencer l'envoi d'une sauvegarde de base. Le système sera mis automatiquement en mode sauvegarde avant que celle-ci ne commence et en sera sorti une fois la sauvegarde terminée. Les options suivantes sont acceptées :

  `LABEL` `'label'`

    Précise le label de la sauvegarde. Si aucun label n'est indiqué, le label utilisé est `base backup`. Les règles de mise entre guillemets du label sont les mêmes que pour une chaîne SQL standard avec standard_conforming_strings activé.

  `PROGRESS`

    Demande la génération d'un rapport de progression. Cela enverra la taille approximative dans l'en-tête de chaque tablespace, qui peut être utilisé pour calculer ce qu'il reste à récupérer. La taille est calculée en énumérant la taille de tous les fichiers avant de commencer le transfert. Du coup, il est possible que cela ait un impact négatif sur les performances. En particulier, la première donnée peut mettre du temps à être envoyée. De plus, comme les fichiers de la base de données peuvent être modifiés pendant la sauvegarde, la taille est seulement approximative et peut soit grandir, soit diminuer entre le moment de son calcul initial et le moment où les fichiers sont envoyés.

  `FAST`

    Demande un checkpoint rapide.

  `WAL`

    Inclut les journaux de transactions nécessaires dans la sauvegarde. Cela inclue tous les fichiers entre le début et la fin de la sauvegarde de base dans le répertoire `pg_wal` dans l'archive tar.

  `NOWAIT`

    Par défaut, la sauvegarde attendra que le dernier journal de transactions requis soit archivé ou émettra un message d'avertissement si l'archivage des journaux de transactions n'est pas activé. Indiquer `NOWAIT` désactive les deux (l'attente et le message), laissant le client responsable de la disponibilité des journaux de transactions requis.

  `MAX_RATE` `taux`

    Limite la quantité maximale de données transférées du serveur au client par unité de temps. L'unité attendue est le ko/s. Si cette option est indiquée, la valeur doit être soit égale à zéro, soit être comprise entre 32 ko et 1 Go (inclus). Si zéro est passé ou que l'option n'est pas indiquée, aucune restriction n'est imposée sur le transfert.

  `TABLESPACE_MAP`

    Inclut les informations sur les liens symboliques présents dans le répertoire `pg_tblspc` dans un fichier nommé `tablespace_map`. Le fichier de correspondance des tablespaces inclut les noms des liens symboliques tels qu'ils existent dans le répertoire `pg_tblspc/` et le chemin complet de ce lien symbolique.

  `NOVERIFY_CHECKSUMS`

    Par défaut, les sommes de contrôle sont vérifiées pendant une sauvegarde de base si celles-ci sont activées. Spécifier `NOVERIFY_CHECKSUMS` désactive cette vérification.

  `MANIFEST` `manifest_option`

    Quand cette option est indiquée avec une valeur `yes` ou `force-encode`, un manifeste 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 pourraient être inclus. Il enregistre la taille, la date de dernière modification et une somme de contrôle optionnelle pour chaque fichier. Une valeur de `force-encode` force l'encodage en hexadécimal de tous les noms de fichier. Dans le cas contraire, ce type d'encodage est uniquement réalisé pour les fichiers dont le nom contient des séquences d'octets hors de l'UTF-8. `force-encode` sert principalement de tests, pour être certain que les clients lisant le manifeste de sauvegarde peuvent 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 à utiliser pour chaque fichier inclus dans le manifeste de sauvegarde. Actuellement, les algorithmes disponibles sont `NONE`, `CRC32C`, `SHA224`, `SHA256`, `SHA384` et `SHA512`. Celui par défaut est `CRC32C`.

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

  Le premier ensemble de résultats standard contient la position de démarrage de la sauvegarde, dans une seule ligne avec deux colonnes. La première colonne contient la position de départ donnée dans le format XLogRecPtr, et la deuxième colonne contient l'identifiant correspondant de la timeline.

  Le deuxième ensemble de résultats standard contient une ligne pour chaque tablespace. Voici la liste des champs d'une telle ligne :

  `spcoid` (`oid`)

    L'OID du tablespace, ou `null` s'il s'agit du répertoire de données.

  `spclocation` (`text`)

    Le chemin complet du répertoire du tablespace, ou `null` s'il s'agit du répertoire de données.

  `size` (`int8`)

    La taille approximative du tablespace, en kilo-octets (1024 octets), si le rapport de progression a été demandé, `null` dans le cas contraire.

  Après l'envoi du deuxième ensemble standard de résultats, un ou plusieurs résultats de type `CopyOutResponse` seront envoyés, un pour le répertoire de données principal et un pour chaque tablespace supplémentaire, autre que `pg_default` et `pg_global`. Les données dans les résultats de type `CopyOutResponse` seront dans le format tar (en suivant le « format d'échange ustar » spécifié dans le standard POSIX 1003.1-2008) du contenu du tablespace, sauf que les deux blocs de zéros à la fin indiqués dans le standard sont omis. Une fois que l'envoi des données du tar est terminé et si un manifeste de sauvegarde a été réclamé, un autre résultat `CopyOutResponse` est envoyé, contenant les données du manifeste pour la sauvegarde de base actuelle. Dans tous les cas, un ensemble final de résultats sera envoyé, contenant la position finale de la sauvegarde dans les journaux de transactions, au même format que la position de départ.

  L'archive tar du répertoire des données et de chaque tablespace contiendra tous les fichiers du répertoire, que ce soit des fichiers PostgreSQL ou des fichiers ajoutés dans le même répertoire. Les seuls 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 l'opération du serveur PostgreSQL, ainsi que tout fichier ou répertoire commençant par `pgsql_tmp` et les relations temporaires.

  - Les relations non journalisées (`unlogged`, à l'exception de l'`init fork` qui est requis pour recréer une relation vide non journalisée lors la restauration.

  - `pg_wal`, ainsi que les sous-répertoires. Si la sauvegarde est lancée avec ajout des journaux de transactions, une version synthétisée de `pg_wal` sera incluse, mais elle ne contiendra que les fichiers nécessaires au bon fonctionnement de la sauvegarde, et pas le reste de son 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 si ce sont des liens symboliques).

  - Les fichiers autres que les fichiers standards et les répertoires, c'est à dire les liens symboliques (autre que les répertoires indiqués ci-dessus) et les fichiers de périphériques sont ignorés. (Les liens symboliques dans `pg_tblspc` sont maintenus.)

  Le propriétaire, le groupe et les droits du fichier sont conservés si le système de fichiers du serveur le permet.