pg_dumpall — extraire une grappe de bases de données PostgreSQL dans un fichier de script
pg_dumpall
[option_connexion
...] [option
...]
pg_dumpall est un outil d'extraction (« sauvegarde ») de toutes les bases de données PostgreSQL de l'instance vers un fichier script. Celui-ci contient les commandes SQL utilisables pour restaurer les bases de données avec psql. Cela est obtenu en appelant pg_dump pour chaque base de données de la grappe. pg_dumpall sauvegarde aussi les objets globaux, communs à toutes les bases de données, autrement dit les rôles et les tablespaces. (pg_dump ne sauvegarde pas ces objets.)
Puisque pg_dumpall lit les tables de toutes les bases de données, il est préférable d'avoir les droits de superutilisateur de la base de données pour obtenir une sauvegarde complète. De plus, il faut détenir des droits superutilisateur pour exécuter le script produit, afin de pouvoir créer les rôles et les bases de données.
Le script SQL est écrit sur la sortie standard. Utilisez l'option
-f
/--file
ou les opérateurs shell pour la
rediriger vers un fichier.
pg_dumpall se connecte plusieurs fois
au serveur PostgreSQL (une fois par base de
données). Si l'authentification par mot de passe est utilisé,
un mot de passe est demandé à chaque tentative de connexion. Il est intéressant
de disposer d'un fichier ~/.pgpass
dans de tels cas. Voir Section 34.15 pour plus d'informations.
Les options suivantes, en ligne de commande, contrôlent le contenu et le format de la sortie.
-a
--data-only
Seules les données sont sauvegardées, pas le schéma (définition des données).
-c
--clean
Émet des commandes SQL DROP
pour supprimer toutes les
bases, rôles et tablespaces sauvegardés avant de les recréer.
Cette option est utile quand la restauration doit écraser une instance
existante. Si un des objets n'existe pas dans l'instance de destination,
les messages d'erreur, à ignorer, seront renvoyés lors de la
restauration sauf si l'option --if-exists
est aussi
indiquée.
-E encoding
--encoding=encoding
Crée la sauvegarde dans l'encodage spécifié. Par défaut, l'encodate de
la base est utilisé. (Une autre façon d'obtenir le même résultat est de
configurer la variable d'environnement PGCLIENTENCODING
avec l'encodage désiré pour la sauvegarde.)
-f nomfichier
--file=nomfichier
Envoie le résultat dans le fichier indiqué. Si cette option n'est pas utilisée, la sortie standard est utilisée.
-g
--globals-only
Seuls les objets globaux sont sauvegardés (rôles et tablespaces), pas les bases de données.
-o
--oids
Les identifiants des objets (OID) sont sauvegardés comme faisant partie des données de chaque table. Cette option est utilisée si l'application référence les colonnes OID (par exemple, dans une contrainte de clé étrangère). Sinon, cette option ne doit pas être utilisée.
-O
--no-owner
Les commandes permettant de positionner les propriétaires des objets
à ceux de la base de données originale. Par défaut,
pg_dumpall lance les instructions
ALTER OWNER
ou SET SESSION AUTHORIZATION
pour configurer le propriétaire des éléments créés. Ces instructions
échouent lorsque le script est lancé par un utilisateur ne disposant
pas des droits de superutilisateur (ou ne possédant pas les droits du
propriétaire de tous les objets compris dans ce script). Pour que ce
qui devient alors propriétaire de tous les objets créés, l'option
-O
doit être utilisée.
-r
--roles-only
Sauvegarde seulement les rôles, pas les bases ni les tablespaces.
-s
--schema-only
Seules les définitions des objets (schéma), sans les données, sont sauvegardées.
-S username
--superuser=username
Précise le nom du superutilisateur à utiliser pour la désactivation
des déclencheurs. Cela n'a d'intérêt que lorsque
--disable-triggers
est utilisé. (Il est en général préférable
de ne pas utiliser cette option et de lancer le script résultant
en tant que superutilisateur.)
-t
--tablespaces-only
Sauvegarde seulement les tablespaces, pas les bases ni les rôles.
-v
--verbose
Indique l'utilisation du mode verbeux. Ainsi pg_dumpall affiche les heures de démarrage/arrêt dans le fichier de sauvegarde et les messages de progression sur la sortie standard. Il active également le mode verbeux dans pg_dump.
-V
--version
Affiche la version de pg_dumpall puis quitte.
-x
--no-privileges
--no-acl
Les droits d'accès (commandes grant/revoke) ne sont pas sauvegardés.
--binary-upgrade
Cette option est destinée à être utilisée pour une mise à jour en ligne. Son utilisation dans d'autres buts n'est ni recommandée ni supportée. Le comportement de cette option peut changer dans les versions futures sans avertissement.
--column-inserts
--attribute-inserts
Extraire les données en tant que commandes INSERT
avec des noms de colonnes explicites (INSERT INTO
). Ceci rendra la restauration très lente ;
c'est surtout utile pour créer des extractions qui puissent être
chargées dans des bases de données autres que
PostgreSQL.
table
(colonne
, ...) VALUES
...
--disable-dollar-quoting
L'utilisation du dollar comme guillemet dans le corps des fonctions est désactivée. Celles-ci sont mises entre guillemets en accord avec la syntaxe du standard SQL.
--disable-triggers
Cette option n'est utile que lors de la création d'une sauvegarde des seules données. pg_dumpall inclut les commandes de désactivation temporaire des déclencheurs sur les tables cibles pendant le rechargement des données. Cette option est utile lorsqu'il existe des vérifications d'intégrité référentielle ou des déclencheurs sur les tables qu'on ne souhaite pas voir appelés lors du rechargement des données.
Actuellement, les commandes émises par --disable-triggers
nécessitent d'être lancées par un superutilisateur. Il est donc impératif de
préciser le nom du superutilisateur avec -S
ou,
préférentiellement, de lancer le script résultant en tant que superutilisateur.
--if-exists
Utilisez des commandes DROP ... IF EXISTS
pour
supprimer des objets dans le mode --clean
. Cela
permet de supprimer les erreurs « does not exist » qui
seraient sinon renvoyées. Cette option n'est pas valide sauf si
--clean
est aussi indiquée.
--inserts
Extraire les données en tant que commandes INSERT
(plutôt que COPY
). Ceci rendra la restauration très
lente ; c'est surtout utile pour créer des extractions qui
puissent être chargées dans des bases de données autres que
PostgreSQL.
Notez que la restauration peut échouer complètement si vous avez changé
l'ordre des colonnes. L'option --column-inserts
est
plus sûre, mais encore plus lente.
--load-via-partition-root
Lors de l'export de données d'une partition, faire que les instructions
COPY
ou INSERT
ciblent la racine
du partitionnement qui contient cette partition, plutôt que la
partition elle-même. Ceci fait que la partition appropriée soit
re-déterminée pour chaque ligne au moment du chargement. Ceci peut être
utile quand le rechargement des données se fait sur un serveur où les
lignes ne tomberont pas forcément dans les mêmes partitions que celles
du serveur original. Ceci pourrait arriver si la colonne de
partitionnement est de type text et que les deux systèmes ont une
définition différente du collationnement utilisé pour tier la colonne
de partitionnement.
--lock-wait-timeout=expiration
Ne pas attendre indéfiniment l'acquisition de verrous partagés
sur table au démarrage de l'extraction. Échouer à la place s'il est
impossible de verrouiller une table dans le temps
d'expiration
spécifié.
L'expiration peut être indiquée dans tous les formats acceptés par
SET statement_timeout
, les valeurs autorisées dépendant
de la version du serveur sur laquelle vous faites l'extraction, mais
une valeur entière en millisecondes est acceptée par toutes les versions
depuis la 7.3. Cette option est ignorée si vous exportez d'une version
antérieure à la 7.3.
--no-subscriptions
Ne sauvegarde pas les souscriptions.
--no-sync
Par défaut, pg_dumpall
attendra que tous les
fichiers aient été écrits de manière sûre sur disque. Cette option
force
pg_dumpall
à rendre 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 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.
--no-tablespaces
Ne pas générer de commandes pour créer des tablespace, ni sélectionner de tablespace pour les objets. Avec cette option, tous les objets seront créés dans le tablespace par défaut durant la restauration.
--no-comments
Ne sauvegarde pas les commentaires.
--no-publications
Ne sauvegarde pas les publications.
--no-role-passwords
Ne sauvegarde pas les mots de passe des rôles. Lors de la
restauration, les rôles auront un mot de passe vide et
l'authentification par mot de passe échouera toujours jusqu'à ce que
le mot de passe soit initialisé. Puisque les valeurs des mots de
passe ne sont pas nécessaires quand cette option est spécifiée,
l'information sur le rôle est lue depuis le catalogue système
pg_roles
au lieu de
pg_authid
. De ce fait, cette option aide
aussi si l'accès à pg_authid
est restreint
par certaines politiques de sécurité.
--no-security-labels
Ne sauvegarde pas les labels de sécurité.
--no-unlogged-table-data
Ne sauvegarde pas le contenu des tables non tracées dans les journaux de transactions. Cette option n'a pas d'effet sur la sauvegarde des définitions de table ; il supprime seulement la sauvegarde des données des tables.
--quote-all-identifiers
Force la mise entre guillemets de tous les identifiants. Cette option
est recommandée lors de la sauvegarde d'un serveur
PostgreSQL dont la version majeure est
différente de celle du pg_dumpall ou quand
le résultat est prévu d'être rechargé dans une autre version majeure.
Par défaut, pg_dumpall met entre guillemets
uniquement les identifiants qui sont des mots réservés dans sa propre
version majeure. Ceci peut poser parfois des problèmes de compatibilité
lors de l'utilisation de serveurs de versions différentes qui auraient
des ensembles différents de mots clés. Utiliser
--quote-all-identifiers
empêche ce type de problèmes
au prix d'un script résultant plus difficile à lire.
--use-set-session-authorization
Les commandes SET SESSION AUTHORIZATION
du standard
SQL sont affichées à la place des commandes ALTER OWNER
pour préciser le propriétaire de l'objet. Cela améliore la compatibilité
de la sauvegarde vis-à-vis des standard. Toutefois, du fait de l'ordre
d'apparition des objets dans la sauvegarde, la restauration peut
ne pas être correcte.
-?
--help
Affiche l'aide sur les arguments en ligne de commande de pg_dumpall, puis quitte
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. Comme pg_dumpall
a besoin de se connecter à plusieurs bases de données, le nom de la base
indiqué dans la chaîne de connexion sera ignorée. Utilisez l'option
-l
pour spécifier le nom de la base utilisée pour la
connexion initiale sauvegardant les objets globaux et découvrant les
bases à sauvegarder.
-h hôte
--host=hôte
Précise le nom d'hôte de la machine sur laquelle le serveur de bases de
données est en cours d'exécution. Si la valeur commence avec un slash,
elle est utilisée comme répertoire du socket de domaine Unix. La valeur
par défaut est prise à partir de la variable d'environnement
PGHOST
, si elle est initialisée, sinon une connexion
socket de domaine Unix est tentée.
-l dbname
--database=dbname
Spécifie le nom de la base où se connecter pour la sauvegarde des
objets globaux et pour découvrir les bases qui devraient être
sauvegardées. Si cette option n'est pas utilisée, la base
postgres
est utilisé et, si elle n'existe pas,
template1
sera utilisée.
-p port
--port=port
Précise le port TCP ou l'extension du fichier socket de domaine Unix
local sur lequel le serveur est en écoute des connexions. La valeur par défaut
est la variable d'environnement PGPORT
, si elle est
initialisée, ou la valeur utilisée lors de la compilation.
-U nomutilisateur
--username=nomutilisateur
Utilisateur utilisé pour initier 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_dumpall à demander un mot de passe avant la connexion à une base de données.
Cette option n'est jamais obligatoire car
pg_dumpall demandera automatiquement un
mot de passe si le serveur exige une authentification par mot de
passe. Néanmoins, pg_dumpall perdra une
tentative de connexion pour trouver que le serveur veut un mot de
passe. Dans certains cas, il est préférable d'ajouter l'option
-W
pour éviter la tentative de connexion.
Notez que le mot de passe sera demandé pour chaque base de données
à sauvegarder. Habituellement, il est préférable de configurer un
fichier ~/.pgpass
pour que de s'en tenir à une
saisie manuelle du mot de passe.
--role=nomrole
Spécifie un rôle à utiliser pour créer l'extraction.
Avec cette option, pg_dumpall émet une commande
SET ROLE
nomrole
après s'être connecté à la base.
C'est utile quand l'utilisateur authentifié (indiqué par
-U
) n'a pas les droits dont pg_dumpall
a besoin, mais peut basculer vers un rôle qui les a. Certaines installations
ont une politique qui est contre se connecter directement en tant que superutilisateur,
et l'utilisation de cette option permet que les extractions soient
faites sans violer cette politique.
PGHOST
PGOPTIONS
PGPORT
PGUSER
Paramètres de connexion par défaut
Cet outil, comme la plupart des autres outils PostgreSQL, utilise aussi les variables d'environnement supportées par la bibliothèque libpq (voir Section 34.14).
Comme pg_dumpall appelle pg_dump en interne, certains messages de diagnostique se réfèrent en fait à pg_dump.
L'option --clean
peut être utile même si votre intention
est de restaurer le script de sauvegarde sur une instance vierge. L'utilisation
de --clean
authorise le script à supprimer puis re-créer les
bases de données internes postgres
et template1
,
en s'assurant que ces bases conserveront les mêmes propriétés (par exemple la locale
et l'encodage) que sur l'instance source. Sans l'option, ces bases conserveront
les propriétés existantes au niveau base ainsi que le contenu pré-existant.
Une fois la restauration effectuée, il est conseillé de lancer
ANALYZE
sur chaque
base de données, de façon à ce que l'optimiseur dispose de statistiques
utiles. vacuumdb -a -z
peut également être utilisé pour analyser
toutes les bases de données.
On ne doit pas s'attendre à ce que le script de sauvegarde s'exécute sans
erreur. En particulier, comme le script exécutera un CREATE
ROLE
pour chaque rôle existant sur l'instance source, il est
certain d'obtenir une erreur « role already exists » pour le
superutilisateur initial sauf si l'instance de destination a été initialisé
avec un autre nom pour le superutilisateur initial. Cette erreur est sans
gravité et doit être ignorée. L'utilisation de l'option
--clean
a des chances de produire des messages d'erreur
supplémentaires sans risque pour les objets inexistants. Vous pouvez
minimiser ces erreurs en ajoutant l'option --if-exists
.
pg_dumpall requiert que tous les tablespaces nécessaires existent avant la restauration. Dans le cas contraire, la création de la base échouera pour une base qui ne se trouve pas dans l'emplacement par défaut.
Sauvegarder toutes les bases de données :
$
pg_dumpall > db.out
Pour recharger les bases de données à partir de ce fichier, vous pouvez utiliser :
$
psql -f db.out postgres
La base de données utilisée pour la connexion initiale n'a pas d'importance ici
car le fichier de script créé par pg_dumpall
contient les commandes nécessaires à la création et à la connexion aux bases
de données sauvegardées. Si vous utilisez l'option --clean
,
vous devez vous connecter à la base postgres
au début ;
le script tentera de supprimer les autres bases immédiatement et ceci échouera
pour la base où vous êtes connecté.
Vérifier pg_dump pour des détails sur les conditions d'erreur possibles.