Configure le répertoire cible de la sauvegarde. pg_basebackup créera le répertoire (et les répertoires parents) s'il n'existe pas. S'il existe déjà, il doit être vide.

Quand la sauvegarde est en mode tar, le répertoire doit être spécifié sous la forme d'un tiret (-), causant l'écriture du fichier tar sur stdout.

Cette option est obligatoire.

Sélectionne le format de sortie. format peut valoir :

Réalise une sauvegarde incrémentale. Le manifeste de sauvegarde pour la sauvegarde de référence doit être fourni et sera téléchargé sur le serveur, qui répondra en envoyant la sauvegarde incrémentale demandée.

Crée un fichier standby.signal et ajoute les paramètres de connexion dans le fichier postgresql.auto.conf du répertoire cible (ou dans le fichier d'archive du répertoire principal des données lors de l'utilisation du format tar). Ceci facilite la configuration d'un serveur secondaire en utilisant les résultats de la sauvegarde.

Le fichier postgresql.auto.conf enregistrera les paramètres de connexion et, si indiqué, le slot de réplication utilisé par pg_basebackup, pour que la réplication en streaming et ??? utilisent plus tard la même configuration. Le nom de la base sera enregistré seulement si le paramètre dbname était indiqué spécifiquement dans la chaîne de connexion ou via une variable d'environnement.

Indique au serveur où placer la sauvegarde de base. La cible par défaut est client, qui indique que la sauvegarde devrait être envoyée à la machine où pg_basebackup est exécuté. Si la cible est configurée à server:/un/chemin, la sauvegarde sera restaurée sur la machine où le serveur est exécuté dans le répertoire /un/chemin. Enregistrer une sauvegarde nécessite des droits de superutilisateur ou d'avoir les droits du rôle pg_write_server_files. Si la cible est configurée à blackhole, le contenu est ignoré et n'est pas sauvegardé. Ceci devrait seulement être utilisé pour des tests. Cela ne devrait pas concerner une sauvegarde réelle.

Comme le flux de journaux de transactions est implémenté par pg_basebackup plutôt que par le serveur, cette option ne peut pas être utilisée avec -Xstream. Comme il s'agit de la valeur par défaut, quand cette option est soumise, vous devez également spécifier soit -Xfetch soit -Xnone.

Déplace le tablespace du répertoire ancien_repertoire vers le répertoire nouveau_repertoire pendant la sauvegarde. Pour bien fonctionner, ancien_repertoire doit correspondre exactement à la spécification du tablespace tel qu'il est actuellement défini sur le serveur source. (Mais il n'y a pas d'erreur s'il n'y a aucun tablespace dans ancien_repertoire sur le serveur source.) Pendant ce temps, nouveau_repertoire est un répertoire dans le système de fichiers de l'hôte cible. Comme avec le répertoire principal cible nouveau_repertoire n'a pas besoin d'exister déjà, mais s'il existe, il doit être vide. ancien_repertoire et nouveau_repertoire doivent tous deux être des chemins absolus. S'il se trouve qu'un chemin contient un signe =, échappez-le avec un anti-slash (\). Cette option peut être spécifiée plusieurs fois pour différents tablespaces.

Si un tablespace est déplacé de cette façon, les liens symboliques à l'intérieur du répertoire de données principal sont mis à jour pour pointer vers le nouvel emplacement. Du coup, le nouveau répertoire de données est prêt à être utilisé sur la nouvelle instance avec les nouveaux chemins.

Actuellement, cette option ne fonctionne qu'avec le format de sortie plain. Elle est ignorée si le format tar est sélectionné.

Indique l'emplacement du répertoire des journaux de transactions. Par défaut, les journaux de transactions seront placés dans le sous-répertoire pg_wal du répertoire cible, mais cette option peut être utilisée pour les placer ailleurs. rep_wal doit être un chemin absolu. Comme avec le répertoire principal des données, waldir peut ne pas exister mais s'il existe déjà, il doit être vide. Cette option ne peut être utilisée que quand la sauvegarde est au format plain.

Inclut les journaux de transactions requis (fichiers WAL) dans la sauvegarde. Cela inclura toutes les transactions intervenues pendant la sauvegarde. À moins que la méthode none ne soit spécifiée, il est possible de démarrer un postmaster sur le répertoire cible sans avoir besoin de consulter les archives des journaux, ce qui rend la sauvegarde complètement autonome.

Les méthodes suivantes sont supportées pour récupérer les journaux de transactions :

Active la compression gzip de l'archive tar en sortie, avec le niveau de compression par défaut. La compression n'est disponible qu'avec le format tar, et le suffixe .gz sera automatiquement ajouté à tous les noms de fichier tar.

Réclame la compression de la sauvegarde. Si client ou server est inclus, cela indique où la compression doit avoir lieu. Compresser sur le serveur réduira la bande passante réseau mais augmentera la consommation CPU du serveur. La valeur par défaut est client sauf quand --target est utilisé. Dans ce cas, la sauvegarde n'est pas envoyée au client, donc seule la compression serveur est sensée. Quand -Xstream, qui est la valeur par défaut, est utilisé, la compression côté serveur n'est pas appliquée aux journaux de transaction. Pour les compresser, utilisez la compression niveau client ou indiquez -Xfetch.

La méthode de compression peut être gzip, lz4, zstd, none pour aucune compression, ou un entier (pas de compression si 0, compression gzip si supérieur à 0). Une chaîne de détails sur la compression peut être indiquée en option. Sinon, il faut 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, long et workers. La chaîne de détails ne peut pas être utilisée quand la méthode de compression est indiquée sous la forme d'un entier.

Si aucun niveau de compression n'est indiqué, le niveau de compression par défaut sera utilisé. Si seulement un niveau est indiqué sans mention d'un algorithme, la compression gzip sera utilisée si le niveau est supérieur à zéro, et aucune compression ne sera utilisée si le niveau est 0.

Quand le format tar est utilisé avec gzip, lz4 ou zstd, le suffixe, respectivement, .gz, .lz4 ou .zst sera automatiquement ajouté aux noms de fichiers tar. Quand le format plain est utilisé, la compression côté client peut ne pas être précisée mais il est toujours possible de réclamer la compression niveau serveur. Si c'est fait, le serveur compressera la sauvegarde pour transmission, et le client la décompressera et l'extraira.

Quand cette option est utilisée en combinaison avec -Xstream, pg_wal.tar sera compressé en utilisant gzip si la compression gzip côté client est sélectionnée, mais ne sera pas compressé si un autre algorithme de compression est sélectionné ou si la compression côté serveur est sélectionnée.

Configure le mode du checkpoint à immédiat (fast) ou étalé (spread, la valeur par défaut). Voir Section 25.3.4.

Indique que le slot de réplication nommé par l'option --slot doit être créé avant d'exécuter la sauvegarde. Une erreur est levée si le slot existe déjà.

Définit un nom pour la sauvegarde. Sans indication, la valeur par défaut, « pg_basebackup base backup », sera utilisée.

Par défaut, quand pg_basebackup échoue avec une erreur, il supprime tous les répertoires qu'il aurait pu créer avant de découvrir qu'il ne peut pas terminer le travail (par exemple, le répertoire de données et le répertoire des journaux de transactions du serveur cible). Cette option désactive le nettoyage, et est donc pratique pour le débogage.

Notez que les répertoires des tablespaces ne sont pas supprimés non plus.

Par défaut, pg_basebackup attendra que tous les fichiers soient écrits de manière sûre sur disque. Cette option demande à pg_basebackup de rendre la main sans attendre, ce qui est plus rapide, mais signifie qu'un arrêt brutal du serveur après la sauvegarde peut laisser la sauvegarde de base dans un état corrompu. De manière générale, cette option est utile durant les tests, mais ne devrait pas être utilisée dans un environnement de production.

Active l'indicateur de progression. Activer cette option donnera un rapport de progression approximatif lors de la sauvegarde. Comme la base de données peut changer pendant la sauvegarde, ce n'est qu'une approximation, et peut ne pas se terminer à exactement 100%. En particulier, lorsque les journaux de transactions sont inclus dans la sauvegarde, la quantité totale de données ne peut pas être estimée à l'avance et, dans ce cas, la taille cible estimée va augmenter une fois dépassée l'estimation totale sans les journaux.

Configure le taux maximum de transfert de données avec lequel les données sont récupérées du serveur source. Ceci peut se révéler utile pour limiter l'impact de pg_basebackup sur le serveur. Les valeurs sont en kilooctets par seconde. Le suffixe M indique des mégaoctets par seconde. Un suffixe k est aussi accepté, mais n'a pas d'effet supplémentaire. Les valeurs valides vont de 32 ko/s à 1024 Mo/s.

Cette option concerne le transfert du répertoire de données. Le transfert des journaux de transactions n'est affecté que si la méthode de récupération est fetch.

Cette option ne peut être utilisée qu'avec l'option -X stream. Elle entraîne l'utilisation du slot de réplication indiqué par le flux de réplication des journaux. Si la sauvegarde de base doit être utilisée pour un serveur secondaire avec un slot, ce serveur devra alors utiliser le même nom de slot dans primary_slot_name. Ainsi, on s'assure que le serveur primaire ne supprimera pas les journaux nécessaires entre la fin de la sauvegarde et le début du lancement de la réplication par streaming sur le nouveau secondaire.

Le slot de réplication spécifié doit exister, sauf si l'option -C est aussi utilisée.

Si cette option n'est pas spécifiée, et que le serveur supporte les slots de réplication temporaires (versions 10 et supérieures), alors un slot de réplication temporaire sera automatiquement utilisé pour le transfert des WAL par streaming.

Quand il est initialisé à fsync, qui est la valeur par défaut, pg_basebackup va ouvrir récursivement tous les fichiers du répertoire de données et les synchroniser sur disque. Quand le format plain est utilisé, la recherche des fichiers suivra les liens symboliques pour le répertoire des journaux de transactions et chaque tablespace configuré.

Sur Linux, syncfs peut être utilisé à la place pour demander au système d'exploitation de synchroniser le système de fichiers complet qui contient le répertoire de sauvegarde. Quand le format plain est utilisé, pg_basebackup synchronisera aussi les systèmes de fichiers qui contiennent les journaux de transactions et chaque tablespace. Voir recovery_init_sync_method pour plus d'informations sur les points importants à connaître lors de l'utilisation de syncfs.

Cette option n'a aucun effet quand --no-sync est utilisé.

Active le mode verbeux. Il affichera des étapes supplémentaires pendant le démarrage et l'arrêt, ainsi que, si le rapport de progression est aussi activé, le nom exact du fichier en cours de traitement.

Spécifie l'algorithme à utiliser dans le manifeste de la sauvegarde pour les sommes de contrôle appliquées à chaque fichier. Les algorithmes disponibles sont actuellement NONE, CRC32C, SHA224, SHA256, SHA384 et SHA512. Le défaut est CRC32C.

Si NONE est choisi, le manifeste ne contiendra aucune somme de contrôle. Sinon, il y en aura une pour chaque fichier de la sauvegarde, avec l'algorithme indiqué. De plus, le manifeste contiendra toujours une somme de contrôle SHA256 de son propre contenu. Les algorithmes SHA sont significativement plus consommateurs de CPU que CRC32C ; choisir l'un d'eux peut donc augmenter la durée nécessaire à la sauvegarde.

Une fonction de hachage SHA fournit un résumé cryptographiquement sûr de chaque fichier, pour les utilisateurs voulant vérifier que la sauvegarde n'a pas été modifiée ; alors que l'algorithme CRC32C fournit une somme de contrôle bien plus rapide à calculer, bonne pour déceler des erreurs dues à des changements accidentels, mais vulnérable à des modifications ciblées. Notez que, pour qu'il serve face à un adversaire avec un accès à la sauvegarde, il faut stocker de manière sécurisée, ailleurs, le fichier manifeste, ou vérifier d'une manière ou d'une autre qu'il n'a pas été modifié depuis le moment de la sauvegarde.

pg_verifybackup peut être utilisé pour vérifier l'intégrité d'une sauvegarde grâce à son manifeste.

Dans le manifeste de la sauvegarde, force l'encodage hexadécimal de tous les noms de fichiers. Sans cette option, seuls les noms de fichiers non-UTF8 sont ainsi encodés. Cette option est surtout destinée à tester que les outils qui lisent un manifeste de sauvegarde traitent correctement ce cas.

Empêche le serveur d'estimer la taille totale de la sauvegarde qui sera renvoyée, et entraînera toujours une valeur NULL pour la colonne backup_total de pg_stat_progress_basebackup.

Sans cette option, la sauvegarde commencera par calculer la taille de toute l'instance, puis procédera à l'envoi du contenu. Cela peut allonger légèrement la sauvegarde, en particulier avant l'envoi des premières données. Si cela est trop long, cette option permet de l'éviter.

Cette option n'est pas autorisée si l'on utilise --progress.

Désactive la génération du fichier manifeste de la sauvegarde. Sans cette option, le serveur générera et enverra un manifeste, contrôlable avec pg_verifybackup. Ce manifeste est une liste de tous les fichiers présent dans la sauvegarde, à l'exception d'éventuels fichiers WAL. Pour chaque fichier, il stocke aussi la taille, le moment de la dernière modification et, optionnellement, une somme de contrôle.

Empêche la création d'un slot de réplication temporaire pour la sauvegarde.

Par défaut, si le flux de réplication est sélectionné mais qu'aucun nom de slot n'a été donné avec l'option -S, alors un slot de réplication temporaire est créé si cela est supporté par le serveur source).

Le but principal de cette option est de permettre de prendre une sauvegarde de base même si le serveur est à cours de slots de réplication. Utiliser les slots est presque toujours la meilleure solution, car cela empêche le serveur de supprimer les WAL nécessaires pendant la sauvegarde.

Désactive la vérification des sommes de contrôles, si elles sont activées sur le serveur sur lequel la sauvegarde est réalisée.

Par défaut, les sommes de contrôles sont vérifiées, et les erreurs produiront un code de sortie différent de zéro. Cependant, la sauvegarde ne sera pas supprimée, comme si l'option --no-clean avait été utilisée. Les échecs de vérification des sommes de contrôle seront aussi rapportés dans la vue pg_stat_database.

Indique les paramètres utilisés pour se connecter au serveur sous la forme d'une chaîne de connexion ; elles surchargeront les options en ligne de commande conflictuelles.

Cette option est appelée --dbname par cohérence avec les autres applications clientes, mais comme pg_basebackup ne se connecte à aucune base de données particulière dans l'instance, le nom de la base de données dans la chaîne de connexion est ignorée par PostgreSQL. Néanmoins, un nom de base fourni de cette façon surcharge le nom de base par défaut (replication) pour rechercher le mot de passe de la connexion de réplication dans ~/.pgpass. De façon similaire, les logiciels tiers et proxies utilisés dans la connexion à PostgreSQL pourraient utiliser le nom pour le routage de connexion. Le nom de la base spécifié dans la chaîne de connexion peut aussi être utilisé par la synchronisation du slot de réplication logique.

Indique le nom d'hôte de la machine sur laquelle le serveur de bases de données est exécuté. Si la valeur commence par une barre oblique (/), elle est interprétée comme le répertoire de socket de domaine Unix. La valeur par défaut est fournie par la variable d'environnement PGHOST, si elle est en place ; sinon une connexion sur la socket de domaine Unix est tentée.

Indique le port TCP ou l'extension du fichier local de socket de domaine Unix sur lequel le serveur écoute les connexions. La valeur par défaut est fournie par la variable d'environnement PGPORT, si elle est en place ; sinon il s'agit de la valeur fournie à la compilation.

Spécifie le nombre de secondes entre les envois au serveur source des paquets informant de l'état en cours. Des valeurs plus petites permettent une supervision plus précise de la progression de la sauvegarde à partir du serveur source. Une valeur de zéro désactive complètement les mises à jour de statut périodiques, bien qu'une mise à jour sera toujours envoyée sur demande du serveur, pour éviter une déconnexion suite au dépassement d'un délai. La valeur par défaut est de 10 secondes.

Indique le nom d'utilisateur pour la connexion.

Empêche l'affichage d'une demande de mot de passe. Si le serveur en réclame un pour l'authentification, et qu'un mot de passe n'est pas disponible d'une autre façon (par exemple avec le fichier .pgpass), la tentative de connexion échouera. Cette option peut être utile dans les batchs et les scripts où aucun utilisateur n'est présent pour saisir un mot de passe.

Force pg_basebackup à demander un mot de passe avant la connexion au serveur source.

Cette option n'est jamais nécessaire, car pg_basebackup demandera automatiquement un mot de passe si le serveur exige une telle authentification. Néanmoins, pg_basebackup gaspillera une tentative de connexion pour découvrir que le serveur veut ce mot de passe. Dans certains cas, il est préférable d'ajouter l'option -W pour éviter la tentative de connexion.

Affiche la version de pg_basebackup, puis quitte.

Affiche l'aide sur les arguments en ligne de commande de pg_basebackup, puis quitte.