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) ou comme le point de départ d'un serveur en standby, par exemple avec la réplication en flux (voir Section 26.2).
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 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), 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 et une pour le transfert
par flux des WAL (si utilisé).
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.
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 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.
-D répertoire
--pgdata=répertoire
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.
-F format
--format=format
Sélectionne le format de sortie. format
peut valoir :
p
plain
É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.
t
tar
É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 et le le transfert des WAL par flux
n'est pas utilisé.
-r taux
--max-rate=taux
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
.
-R
--write-recovery-conf
É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.
-S nom_slot
--slot=nom_slot
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.
Si cette option n'est pas spécifiée et que le serveur supporte les slots de réplication temporaires (version 10 et supérieures), alors un slot de réplication temporaire sera automatiquement utilisé pour le transfert des WAL par flux.
--no-slot
Cette option empêche la création d'un slot de réplication temporaire pendant la sauvegarde même si cela est supporté par le serveur.
Les slots de réplication temporaires sont crées par défaut si aucun nom
de slot n'est présicé avec l'option -S
quand l'envoi
des journaux de transaction par flux est utilisé.
Le but principale de cette option est d'autoriser la réalisation d'une sauvegarde des bases quand le serveur ne dispose ne dispose plus de slot de réplication libre. Utiliser les slots de réplication est presque toujours la meilleure solution, car cela empêche le serveur de supprimer pendant la sauvegarde les WAL nécessaires.
-T ancien_repertoire
=nouveau_repertoire
--tablespace-mapping=ancien_repertoire
=nouveau_repertoire
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é.
--waldir=rep_wal
Indique l'emplacement du répertoire des journaux de transactions.
rep_wal
doit être un chemin absolu. Le
répertoire des journaux de transactions peut seulement être
spécifié quand la sauvegarde est en mode plain.
-X method
--wal-method=method
Inclut les journaux de transactions requis (fichiers WAL) dans
la sauvegarde. Cela incluera toutes les transactions intervenues
pendant la sauvegarde. À moins que la méthode none
ne
soit spécifié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 :
n
none
N'inclue pas les journaux de transaction dans la sauvegarde.
f
fetch
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.
Quand le format tar est utilisé, les journaux de transaction seront
écrit dans le fichier base.tar
.
s
stream
Envoie 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.
Quand le format tar est utilisé, les journaux de transaction seront
écrit 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 est disponible
seulement lors de l'utilisation du 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 pour sans compression, 9
correspondant à la meilleure compression). La compression est
seulement disponible lors de l'utilisation du format tar, et le suffixe
.gz
sera automatiquement ajouté à tous les noms de
fichier tar.
Les options suivantes en ligne de commande 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 en attente (spread, la valeur par défaut). Voir Section 25.3.3.
-l label
--label=label
Configure le label de la sauvegarde. Sans indication, une valeur
par défaut, « pg_basebackup base backup
» sera
utilisée.
-n
--no-clean
Par défaut, quand pg_basebackup
échoue en erreur, il
supprime tout répertoire 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 transaction). Cette option empêche le
nettoyage et est donc pratique pour le débuggage.
Note that tablespace directories are not cleaned up either way.
-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,
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.
-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 renvoyer la main sans
attendre, ce qui est plus rapide, mais signifie qu'un arrêt brutal du
serveur survenant après la sauvegarde peut laisser la sauvegarde des
bases 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.
-v
--verbose
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.
-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 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.
-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 initialisée. Dans le cas
contraire, il s'agit de la valeur fournie à la compilation.
-s interval
--status-interval=interval
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.
-U nomutilisateur
--username=nomutilisateur
Le nom d'utilisateur utilisé pour la connexion.
-w
--no-password
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.
-W
--password
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 :
-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
Cet outil, comme la plupart des outils PostgreSQL, utilise les variables d'environnement supportées par libpq (voir Section 33.14).
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, à l'exception de certains fichiers temporaires générés par PostgreSQL. Seuls les fichiers réguliers et les répertoires sont copiés, à l'exception des liens symboliques utilisés pour les tablespaces qui sont préservés. Les liens symboliques pointant vers certains répertoires connus de PostgreSQ sont copiés comme de nouveaux répertoires. Les autres liens symboliques et les fichiers de périphérique spéciaux sont ignorés. Voir Section 52.6 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 -X fetch | 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