Documentation PostgreSQL 14.22 » Référence » Applications client de PostgreSQL » pg_basebackup

Précédent | Niveau supérieur | Suivant
pg_amcheck | Sommaire | pgbench

## pg_basebackup

pg_basebackup — réalise une sauvegarde de base d'une instance PostgreSQL

## Synopsis

`pg_basebackup` [`option`...]

## Description

pg_basebackup est utilisé pour effectuer une sauvegarde de base d'une instance PostgreSQL en cours d'exécution. Elle se fait sans affecter les autres clients du serveur de bases de données, et peut être utilisée pour une restauration à un certain point dans le temps (PITR, voir Section 26.3) ou comme point de départ pour un serveur secondaire, par envoi des journaux de transactions ou par le flux de réplication (voir Section 27.2).

pg_basebackup fait une copie exacte des fichiers de l'instance, en s'assurant que le système entre et sort du mode sauvegarde automatiquement. Les sauvegardes sont toujours faites sur l'ensemble de l'instance ; il n'est donc pas possible de sauvegarder une base individuelle ou des objets d'une base. Pour de telles sauvegardes, utiliser un outil comme pg_dump.

La sauvegarde se fait via une connexion PostgreSQL standard qui utilise le protocole de réplication. La connexion doit se faire avec un rôle doté de l'attribut `REPLICATION` ou `SUPERUSER` (voir Section 22.2), et `pg_hba.conf` doit explicitement permettre la connexion de réplication. Le serveur doit aussi être configuré avec un max_wal_senders suffisamment élevé pour fournir au moins une connexion disponible pour la sauvegarde, et une autre pour le transfert par flux des journaux de transactions (si utilisé).

Plusieurs commandes `pg_basebackup` peuvent tourner en même temps, mais, du point de vue des performances, il est généralement préférable de n'en faire qu'une seule, puis de faire une copie du résultat.

pg_basebackup peut effectuer une sauvegarde non seulement à partir du serveur primaire, mais aussi d'un serveur secondaire. Pour cela, paramétrez le secondaire pour accepter les connexions pour réplication (c'est-à-dire configurez les paramètres `max_wal_senders` et hot_standby, et configurez le fichier `pg_hba.conf` de façon approprié). Il sera aussi nécessaire d'activer full_page_writes sur le serveur primaire.

Il est à noter qu'il existe des limites à la sauvegarde à chaud depuis un serveur secondaire :

- Le fichier d'historique de la sauvegarde n'est pas créé dans l'instance sauvegardée.

- pg_basebackup ne peut forcer le serveur standby à basculer vers un nouveau fichier WAL à la fin de la sauvegarde. Quand vous utilisez `-X none`, si l'activité en écriture sur le primaire est basse, pg_basebackup peut avoir besoin d'attendre un long moment pour que le dernier fichier WAL requis par la sauvegarde soit archivé. Dans ce cas, il pourrait être utile d'exécuter `pg_switch_wal` ur le primaire pour causer un changement immédiat de fichier WAL.

- Si le serveur secondaire est promu en tant que primaire durant la sauvegarde à chaud, celle-ci échouera.

- Toutes les entrées WAL nécessaires à la sauvegarde doivent disposer de suffisamment de pages complètes, ce qui nécessite d'activer `full_page_writes` sur le primaire et de ne pas utiliser d'outils comme pg_compresslog en tant qu'`archive_command` pour supprimer les pages complètes inutiles des fichiers WAL.

La vue `pg_stat_progress_basebackup` du serveur sauvegardé permet de suivre la progression d'une sauvegarde de base effectuée avec pg_basebackup. Voir Section 28.4.5 pour les détails.

## Options

Les options de ligne de commande suivantes contrôlent l'emplacement et le format du résultat.

`-D `répertoire``
`--pgdata=`répertoire``

  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.

`-F `format``
`--format=`format``

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

  `p`
  `plain`

    Écrit des fichiers standards, avec l'agencement d'origine du répertoire des données et des tablespaces du serveur source. Si l'instance n'a pas de tablespace supplémentaire, toute l'instance sera placée dans le répertoire cible. Si l'instance contient des tablespaces supplémentaires, le répertoire principal des données sera placé dans le répertoire cible mais les autres tablespaces seront placés dans le même chemin absolu que celui d'origine. (Voir `--tablespace-mapping` pour changer cela.)

    C'est le format par défaut.

  `t`
  `tar`

    Écrit des fichiers tar dans le répertoire cible. Le contenu du répertoire principal de données sera écrit dans un fichier nommé `base.tar`, et tous les autres tablespaces seront écrit dans un fichier tar séparé nommé d'après l'OID du tablespace.

    Si le répertoire cible est indiqué avec un tiret `-`, le contenu du fichier tar sera écrit sur la sortie standard, ce qui est permet de l'envoyer par un tube vers gzip, par exemple. Ceci n'est autorisé que si l'instance n'a pas de tablespaces supplémentaires, ou que le transfert des WAL par streaming n'est pas utilisé.

`-R`
`--write-recovery-conf`

  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 utilise plus tard la même configuration.

`-T `ancien_repertoire`=`nouveau_repertoire``
`--tablespace-mapping=`ancien_repertoire`=`nouveau_repertoire``

  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 sur le format tar est sélectionné.

`--waldir=`rep_wal``

  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.

`-X `methode``
`--wal-method=`methode``

  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 :

  `n`
  `none`

    N'inclut pas les journaux de transactions dans la sauvegarde.

  `f`
  `fetch`

    Les journaux de transactions sont récupérés à la fin de la sauvegarde. Il est donc nécessaire de définir le paramètre wal_keep_size du serveur source suffisamment haut pour que les données WAL requises ne soient pas recyclées avant la fin de la sauvegarde. Si les données WAL ont été recyclées avant qu'il n'ait été possible de les transférer, la sauvegarde échouera et sera inutilisable.

    Quand le format tar est utilisé, les journaux de transactions seront écrits dans le fichier `base.tar`.

  `s`
  `stream`

    Envoie les données des journaux de transactions lors de la sauvegarde. Cette option ouvre une seconde connexion sur le serveur et entame l'envoi du journal de transactions en parallèle de la sauvegarde. À cet effet, ce mécanisme consommera deux connexions, et non pas juste une. Ce mode permet de ne pas avoir à sauvegarder des journaux de transactions additionnels sur le serveur primaire, aussi longtemps que le client pourra suivre le flux des journaux de transactions.

    Quand le format tar est utilisé, les journaux de transactions seront écrits dans un fichier séparé nommé `pg_wal.tar` (si le serveur est d'une version antérieure à la version 10, le fichier sera nommé `pg_xlog.tar`).

    Cette valeur est la valeur par défaut.

`-z`
`--gzip`

  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.

`-Z `niveau``
`--compress=`niveau``

  Active la compression gzip du fichier tar en sortie, et précise le niveau de compression (de 0 à 9, 0 étant sans compression, et 9 la meilleure). La compression n'est disponible qu'avec le format tar, et le suffixe `.gz` sera automatiquement ajouté à tous les noms de fichier tar.

Les options de ligne de commande suivantes contrôlent la génération de la sauvegarde et l'exécution du programme :

`-c `fast|spread``
`--checkpoint=`fast|spread``

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

`-C`
`--create-slot`

  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à.

`-l `label``
`--label=`label``

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

`-n`
`--no-clean`

  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.

`-N`
`--no-sync`

  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.

`-P`
`--progress`

  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.

`-r `taux``
`--max-rate=`taux``

  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`.

`-S `nom_slot``
`--slot=`nom_slot``

  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.

`-v`
`--verbose`

  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.

`--manifest-checksums=`algorithm``

  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.

`--manifest-force-encode`

  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.

`--no-estimate-size`

  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`.

`--no-manifest`

  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.

`--no-slot`

  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.

`--no-verify-checksums`

  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.

Les options de ligne de commande suivantes contrôlent la connexion au serveur source :

`-d `connstr``
`--dbname=`connstr``

  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.

`-h `hôte``
`--host=`hôte``

  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.

`-p `port``
`--port=`port``

  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.

`-s `interval``
`--status-interval=`interval``

  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.

`-U `nom_utilisateur``
`--username=`nom_utilisateur``

  Indique le nom d'utilisateur pour la connexion.

`-w`
`--no-password`

  Enpê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.

`-W`
`--password`

  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.

D'autres options sont aussi disponibles :

`-V`
`--version`

  Affiche la version de pg_basebackup, puis quitte.

`-?`
`--help`

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

## Environnement

Cet outil, comme la plupart des outils PostgreSQL, utilise les variables d'environnement supportées par libpq (voir Section 34.15).

La variable d'environnement `PG_COLOR` indique s'il faut utiliser les couleurs dans les messages de diagnostics. Les valeurs possibles sont `always`, `auto`, `never`.

## Notes

Au début d'une sauvegarde, un checkpoint doit être réalisé sur le serveur cible. Ceci peut prendre un certain temps (tout spécialement si l'option `--checkpoint=fast` n'est pas utilisée), pendant lequel pg_basebackup semblera inactif.

La sauvegarde inclura tous les fichiers du répertoire de données et des tablespaces, dont les fichiers de configuration, et aussi tout autre fichier placé dans le répertoire par d'autres personnes, à l'exception de certains fichiers temporaires gérés par PostgreSQL. Seuls les fichiers normaux et les répertoires sont cependant copiés. Les liens symboliques utilisés pour les tablespaces sont aussi préservés. Les liens symboliques pointant vers certains répertoires connus de PostgreSQL sont copiés en tant que répertoires vides. Les autres liens symboliques et les fichiers de périphérique spéciaux sont ignorés. Voir Section 53.4 pour des détails précis.

Dans le format plain, les tablespaces seront sauvegardés avec le même chemin que sur le serveur source, sauf si l'option `--tablespace-mapping` est utilisée. Sans elle, restaurer et lancer une sauvegarde de format plain sur le même serveur ne fonctionnera pas si les tablespaces sont utilisés, car la sauvegarde devra écrire dans les mêmes répertoires que ceux des tablespaces originaux.

Quand le format tar est utilisé, il est de la responsabilité de l'utilisateur de décompresser chaque archive tar avant de démarrer un serveur PostgreSQL qui utilisera ces données. S'il existe des tablespaces supplémentaires, les archives tar les concernant doivent être décompressés au même emplacement. Dans ce cas, les liens symboliques pour ces tablespaces seront créés par le serveur, suivant le contenu du fichier `tablespace_map` inclus dans le fichier `base.tar`.

pg_basebackup fonctionne sur les serveurs de même version, ou de version plus ancienne jusqu'à la 9.1. Néanmoins, le streaming des WAL (option `-X`) ne fonctionne qu'avec un serveur en version 9.3 ou ultérieure, et le format tar (`--format=tar`) ne fonctionne qu'avec les serveurs de version 9.5 ou ultérieure.

pg_basebackup conservera les droits de groupe pour les fichiers de données si les droits de groupe sont activés sur l'instance cible.

## Exemples

Pour créer une sauvegarde de base du serveur `mon_sgbd` et l'enregistrer dans le répertoire local `/usr/local/pgsql/data` :

    $ pg_basebackup -h mon_sgbd -D /usr/local/pgsql/data

Pour créer une sauvegarde du serveur local avec un fichier tar compressé pour chaque tablespace, et stocker le tout dans le répertoire `sauvegarde`, tout en affichant la progression pendant l'exécution :

    $ pg_basebackup -D sauvegarde -Ft -z -P

Pour créer une sauvegarde d'une base de données locale avec un seul tablespace, et la compresser avec bzip2 :

    $ pg_basebackup -D - -Ft -X fetch | bzip2 > backup.tar.bz2

(Cette commande échouera s'il existe plusieurs tablespaces dans l'instance.)

Pour créer une sauvegarde d'une base locale, où le tablespace situé dans `/opt/ts` doit être déplacé vers `./backup/ts` :

    $ pg_basebackup -D backup/data -T /opt/ts=$(pwd)/backup/ts

## Voir aussi

pg_dump, Section 28.4.5