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 25.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 26.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 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 21.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. (Voir --tablespace-mapping pour changer cela.)
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.
Le taux maximum de transfert de données avec le serveur. Les valeurs sont en kilo-octets par seconde. Le suffixe M indique des méga-octets 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.
Le but est de limiter l'impact de pg_basebackup sur le serveur.
Cette option affecte le transfert du répertoire de données. Le transfert des journaux de transactions est seulement affecté si la méthode de récupération est fetch.
Écrit un fichier de configuration recovery.conf minimal dans le répertoire en sortie (ou dans le fichier d'archive du répertoire principal des données lors de l'utilisation du format tar) pour faciliter la configuration d'un serveur standby. Le fichier recovery.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 flux utilise la même configuration.
Cette option peut seulement être utilisée avec l'option -X stream. Elle fait en sorte que l'envoi des journaux dans le flux de réplication utilise le slot de réplication indiqué. Si la sauvegarde de base doit être utilisée pour un serveur standby avec un slot de réplication, elle devrait alors utilisée le même nom pour le slot de réplication dans le fichier recovery.conf. Ainsi, il est certain que le serveur ne supprimera pas les journaux nécessaires entre la fin de la sauvegarde et le début de lancement de la réplication en flux.
Transfère 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. (Mais il n'y a pas d'erreur s'il n'y a aucun tablespace dans ancien_repertoire contenu dans la sauvegarde.) ancien_repertoire et nouveau_repertoire doivent être des chemins absolus. Si un chemin survient pour contenir un signe =, échappez-le avec un anti-slash. Cette option peut être spécifiée plusieurs fois pour différents tablespaces. Voir les exemples ci-dessus.
Si un tablespace est transféré 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 tous les tablespaces dans les emplacements mis à jour.
Actuellement, cette option ne fonctionne qu'avec le format de sortie plain. Elle est ignorée sur le format tar est sélectionné.
Indique l'emplacement du répertoire des journaux de transactions. rep_xlog doit être un chemin absolu. Le répertoire des journaux de transactions peut seulement être spécifié quand la sauvegarde est en mode plain.
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 à immédiat (fast) ou en attente (spread, la valeur par défaut). Voir Section 25.3.3, « Effectuer une sauvegarde de base avec l'API bas niveau ».
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 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.
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. Ceci permet une supervision plus facile du progrès à partir du serveur. Une valeur de zéro désactive complètement les mises à jour périodiques de statut, bien qu'une mise à jour sera toujours envoyée lorsqu'elle est demandée par le serveur, pour éviter une déconnexion suite au dépassement d'un délai. 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 32.14, « Variables d'environnement »).
Au début d'une sauvegarde, un checkpoint doit être écrit sur le serveur où est réalisé la sauvegarde. Tout spécialement si l'option --checkpoint=fast n'est pas utilisée, ceci peut prendre du temps pendant lequel pg_basebackup semblera inoccupé.
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 réguliers et les répertoires sont copiés. Les liens symboliques (autres que ceux utilisés pour les tablespaces) et les fichiers spéciaux de périphériques sont ignorés. (Voir Section 51.4, « Protocole de réplication en continu » pour des détails précis.)
Les tablespaces seront en format plain par défaut et seront sauvegardés avec le même chemin que sur le serveur, sauf si l'option --tablespace-mapping est utilisée. Sans cette option, 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é, c'est de la responsabilité de l'utilisateur de déballer chaque archive tar avant de démarrer le serveur PostgreSQL. S'il existe des tablespaces supplémentaires, les archives tar les concernant doivent être déballé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 qui est inclus dans le fichier base.tar.
pg_basebackup fonctionne sur les serveurs de même version ou de versions plus anciennes (donc de version supérieure ou égale à la 9.1). Néanmoins, le mode de flux de journaux (option -X) fonctionne seulement avec les serveurs en version 9.3 et ultérieures, et le format tar (--format=tar) de la version actuelle fonctionne seulement avec les serveurs en version 9.5 et ultérieures.
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)
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
ecpg