pg_dumpall

pg_dumpall — extraire une grappe de bases de données PostgreSQL™ dans un fichier de script

Synopsis

pg_dumpall [option_connexion...] [option...]

Description

pg_dumpall est un outil d'extraction (« sauvegarde ») de toutes les bases de données PostgreSQL™ d'une grappe vers un fichier script. Celui-ci contient les commandes SQL utilisables pour restaurer les bases de données avec psql(1). Cela est obtenu en appelant pg_dump(1) pour chaque base de données de la grappe. pg_dumpall sauvegarde aussi les objets globaux, communs à toutes les bases de données. (pg_dump ne sauvegarde pas ces objets.) Cela inclut aussi les informations concernant les utilisateurs et groupes des bases de données, ainsi que les tablespaces et les propriétés telles que les droits d'accès s'y appliquant.

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 utilisateurs, les groupes et les bases de données.

Le script SQL est écrit sur la sortie standard. Utilisez l'option [-f|fichier] 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 31.15, « Fichier de mots de passe » pour plus d'informations.

Options

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

Les commandes SQL de nettoyage (suppression) des bases de données avant leur recréation sont incluses. Des commandes DROP sont également ajoutées pour les rôles et les tablespaces.

-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 table (colonne, ...) VALUES ...). 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™.

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

Utilise une commande conditionnelle (c'est-à-dire ajouter une clause IF EXISTS pour la suppression des bases et autres objets. Cette option n'est valide que si --clean est également spécifié.

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

--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-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-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 recommendée lors de la sauvegarde d'une base de données dont la version majeure de PostgreSQL™ est différente de celle de pg_dumpall ou quand la sortie doit être chargée dans un serveur d'une version majeure différente. Par défaut, pg_dumpall met seulement entre guillemets les identifiants qui sont des mots réservés pour sa propre version majeure. Parfois, cela résulte en des soucis de compatibilité lorsque c'est traité par des serveurs d'autres versions qui pourraient avoir des ensembles différents de mots réservés. Utiliser --quote-all-identifiers empêche de tels problèmes, au prix d'un script de sauvegarde 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 à utiliser pour se connecter au serveur, en tant que chaîne de connexions. Voir Section 31.1.1, « Chaînes de connexion » pour plus d'informations.

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é pour sauvegarder les objets globaux et pour découvrir 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.

Environnement

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 31.14, « Variables d'environnement »).

Notes

Comme pg_dumpall appelle pg_dump en interne, certains messages de diagnostique se réfèrent en fait à pg_dump.

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.

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.

Exemples

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

Voir aussi

Vérifier pg_dump(1) pour des détails sur les conditions d'erreur possibles.