pg_basebackup — réalise une sauvegarde de base d'une instance PostgreSQL™
pg_basebackup [option...]
pg_basebackup est utilisé pour prendre une sauvegarde de base d'une instance PostgreSQL™ en cours d'exécution. Elles se font sans affecter les autres clients du serveur de bases de données et peuvent être utilisées pour une restauration jusqu'à un certain point dans le temps (voir Section 24.3, « Archivage continu et récupération d'un instantané (PITR) ») ou comme le point de départ d'un serveur en standby, par exemple avec la réplication en flux (voir Section 25.2, « Serveurs de Standby par transfert de journaux »).
pg_basebackup fait une copie binaire des fichiers de l'instance en s'assurant que le système est mis automatiquement en mode sauvegarde puis en est sorti. 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 les sauvegardes de ce type, un outil comme pg_dump(1) doit être utilisé.
La sauvegarde se fait via une connexion PostgreSQL™ standard et utilise le protocole de réplication. La connexion doit se faire avec un utilisateur doté de l'attribut REPLICATION ou SUPERUSER (voir Section 20.2, « Attributs des rôles »), 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 laisser au moins une connexion disponible pour la sauvegarde.
Plusieurs commandes pg_basebackup peuvent être exécutées en même temps mais il est préférable pour les performances de n'en faire qu'une seule et de copier le résultat.
pg_basebackup peut effectuer une sauvegarde non seulement à partir du serveur maître mais aussi du serveur esclave. Pour effectuer une sauvegarde à partir de l'esclave, paramétrer l'esclave de manière à ce qu'il accepte les connexions pour réplication (c'est-à-dire définir les paramètres max_wal_senders et hot_standby, et configurer l'authentification du client). Il sera aussi nécessaire d'activer full_page_writes sur le maître.
À noter qu'il existe des limites à la sauvegarde à chaud depuis un serveur esclave :
Le fichier d'historique de la sauvegarde n'est pas créé dans l'instance de la base qui a été sauvegardée.
Il n'y a aucune garantie qu'à la fin de la sauvegarde l'ensemble des fichiers WAL nécessaires à la sauvegarde soient archivés. Si vous voulez utiliser la sauvegarde pour une restauration d'archive et être sûr que tous les fichiers soient disponibles à ce moment, vous devez les inclure à la sauvegarde au moyen de l'option -x.
Si le serveur esclave est promu maître durant la sauvegarde à chaud, la sauvegarde é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 maître 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.
Les options suivantes en ligne de commande contrôlent l'emplacement et le format de la sortie.
Répertoire où sera écrit la sortie. pg_basebackup créera le répertoire et tous les sous-répertoires si nécessaire. Le répertoire peut déjà exister mais doit être vide. Dans le cas contraire, une erreur est renvoyée.
Quand la sauvegarde est en mode tar et que le répertoire est spécifié avec un tiret (-), le fichier tar sera écrit sur stdout.
Cette option est requise.
Sélectionne le format de sortie. format peut valoir :
Écrit des fichiers standards, avec le même emplacement que le répertoire des données et les tablespaces d'origine. Quand l'instance n'a pas de tablespace supplémentaire, toute la base de données 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.
C'est le format par défaut.
Écrit des fichiers tar dans le répertoire cible. Le répertoire principal de données sera écrit sous la forme d'un fichier nommé base.tar et tous les autres tablespaces seront nommés d'après l'OID du tablespace.
Si la valeur - (tiret) est indiquée comme répertoire cible, le contenu du tar sera écrit sur la sortie standard, ce qui est intéressant pour une compression directe via un tube. Ceci est seulement possible si l'instance n'a pas de tablespace supplémentaire.
Utiliser cette option est équivalent à utiliser -X avec la méthode fetch.
Inclut les journaux de transactions requis (fichiers WAL) dans la sauvegarde. Cela incluera toutes les transactions intervenues pendant la sauvegarde. Si cette option est précisée, il est possible de lancer un postmaster directement sur le répertoire extrait 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 :
Les journaux de transactions sont récupérés à la fin de la sauvegarde. Cela étant, il est nécessaire de définir le paramètre wal_keep_segments à une valeur suffisamment élevée pour que le journal ne soit pas supprimé avant la fin de la sauvegarde. Si le journal est l'objet d'une rotation au moment où il doit être transféré, la sauvegarde échouera et sera inutilisable.
Envoit le journal de transactions tandis que la sauvegarde se réalise. Cette option ouvre une seconde connexion sur le serveur et commence l'envoi du journal de transactions en parallèle tout en effectuant la sauvegarde. À cet effet, ce mécanisme s'appuie sur deux connexions configurées par le paramètre max_wal_senders. Ce mode permet de ne pas avoir à sauvegarder des journaux de transactions additionnels sur le serveur maître, aussi longtemps que le client pourra suivre le flux du journal de transactions.
Active la compression gzip de l'archive tar en sortie, avec le niveau de compression par défaut. La compression est disponible seulement lors de l'utilisation du format tar.
Active la compression gzip du fichier tar en sortie, et précise le niveau de compression (de 0 à 9, 0 pour sans compression, 9 correspondant à la meilleure compression). La compression est seulement disponible lors de l'utilisation du format tar.
Les options suivantes en ligne de commande contrôlent la génération de la sauvegarde et l'exécution du programme.
Configure le mode du checkpoint à rapide (fast) ou en attente (spread, la valeur par défaut).
Configure le label de la sauvegarde. Sans indication, une valeur par défaut, « pg_basebackup base backup » sera utilisée.
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, ceci est seulement une approximation et pourrait 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 quand il dépasse l'estimation totale sans les journaux de transactions.
Quand cette option est activée, le serveur commencera par calculer la taille totale des bases de données, puis enverra leur contenu. Du coup, cela peut rendre la sauvegarde plus longue, en particulier plus longue avant l'envoi de la première donnée.
Active le mode verbeux, qui affichera les étapes supplémentaires pendant le démarrage et l'arrêt ainsi que le nom de fichier exact qui est en cours de traitement si le rapport de progression est aussi activé.
Les options suivantes en ligne de commande contrôlent les paramètres de connexion à la base de données.
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 utilisée comme répertoire pour le socket de domaine Unix. La valeur par défaut est fournie par la variable d'environnement PGHOST, si elle est initialisée. Dans le cas contraire, 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 initialisée. Dans le cas contraire, il s'agit de la valeur fournie à la compilation.
Spécifie le rythme en secondes de l'envoi des paquets au serveur informant de l'état en cours. Ce paramètre est utile lorsque le journal de transactions est suivi parallèlement à la sauvegarde (en utilisant --xlog=stream) notamment si le délai limite d'attente concernant la réplication est configuré sur le serveur. Il permet aussi une surveillance simplifiée. Une valeur de zéro désactive complètement les mises à jour du statut. La valeur par défaut est de 10 secondes.
Le nom d'utilisateur utilisé pour la connexion.
Ne demande jamais un 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 pour 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 à une base de données.
Cette option n'est jamais nécessaire car pg_basebackup demande automatiquement un mot de passe si le serveur exige une authentification par mot de passe. Néanmoins, pg_basebackup perd une tentative de connexion pour tester si le serveur demande un 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 :
Affiche la version de pg_basebackup puis quitte.
Affiche l'aide sur les arguments en ligne de commande de pg_basebackup, puis quitte
Cet outil, comme la plupart des outils PostgreSQL™, utilise les variables d'environnement supportées par libpq (voir Section 31.14, « Variables d'environnement »).
La sauvegarde incluera tous les fichiers du répertoire de données et des tablespaces, ceci incluant les fichiers de configuration et tout fichier supplémentaire placé dans le répertoire par d'autres personnes. Seuls les fichiers et répertoires standards sont autorisés dans le répertoire des données, pas de liens symboliques ou de fichiers périphériques spéciaux.
De la façon dont PostgreSQL™ gère les tablespaces, le chemin de chaque tablespace supplémentaire doit être identique quand une sauvegarde est restaurée. Néanmoins, le répertoire principal de données est relocalisable.
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 | bzip2 > backup.tar.bz2
(cette commande échouera s'il existe plusieurs tablespaces pour cette instance)
ecpg