pg_dump − Extrait une base de données PostgreSQL dans un fichier de script ou dans un autre fichier d’archive

pg_dump [ option... ] [ nom de base de données ]

pg_dump est un utilitaire de sauvegarde d’une base de données PostgreSQL. Il réalise une sauvegarde cohérente même si la base de données est utilisée en même temps. pg_dump ne bloque pas les autres utilisateurs d’accéder à la base de données, que ce soit en lecture ou en écriture.

Les sauvegardes peuvent être générées dans un format de fichier de script ou d’archive. Les fichiers de scripts sont en format texte plein et contiennent les commandes SQL requises pour reconstruire la base de données dans l’état où elle était au moment de la sauvegarde. Pour restaurer à partir des scripts, utilisez la commande psql(1). Ils peuvent être utilisés pour reconstruire la base de données même sur d’autres machines et d’autres architectures, avec quelques modifications sur d’autres gestionnaires de base de données SQL.

Les fichiers alternatifs de format archive sont censés être utilisés avec pg_restore(1) pour reconstruire la base de données, et ils permettent aussi à pg_restore d’être sélectif sur ce qui est restauré, ou même de réordonner les éléments avant leur restauration. Les fichiers archives sont aussi tout désignés pour être portables entre architectures.

Lorsqu’il est utilisé avec un fichier au format archive et combiné avec pg_restore, pg_dump fournit une archive et un mécanisme de transfert flexible. pg_dump peut être utilisé pour faire une sauvegarde entière de la base de données, alors pg_restore peut être utilisé pour examiner l’archive et/ou sélectionner quelles parties de la base de données sont à restaurer. Le format de fichier de sortie le plus flexible est le format « personnalisé » (-Fc). Il tient compte du choix et du réarrangement de tous les éléments, et est compressé par défaut. Le format tar (-Ft) n’est pas compressé et il n’est pas possible de réordonner les données lors du chargement, mais sinon il est tout à fait flexible ; de plus, il peut être manipulé avec d’autres outils comme tar.

En exécutant pg_dump, il faudrait examiner la sortie pour des avertissements eventuels (imprimé sur la sortie standard), spécialement à la lumière les limitations citées ci-dessous.

Les lignes de commandes suivantes sont utilisées pour contôler le format de sortie.

nom de base de données

Spécifie le nom de la base de données à sauvegarder. Si ce n’est pas spécifié, la variable d’environnement PGDATABASE est utilisée. Si ce n’est pas initialisé, le nom d’utilisateur spécifié par la connexion est utilisé.

-a

--data-only

Sauvegarde seulement les données, pas le schéma (définition des données).

Cette option n’est significative que pour le format texte simple. Pour les autres formats, vous devriez spécifier l’option quand vous appelez pg_restore.

-b

--blobs

Inclut les grands objets dans la sauvegarde.

-c

--clean

Commande de sortie pour nettoyer (drop) la base de données des objets avant de les récréer (commandes de recréation).

Cette option n’est significative que pour le format texte simple. Pour les autres formats, vous devriez spécifier l’option quand vous appelez pg_restore.

-C

--create

Commence la sortie avec une commande pour créer la base de données elle-même et se reconnecte à cette même base ainsi créée. (Avec un script de cette forme, la base de données à laquelle vous êtes connecté n’a aucune importance.)

Cette option n’est significative que pour le format texte simple. Pour les autes formats, vous devriez spécifier l’option quand vous appelez pg_restore.

-d

--inserts

Sauvegarde les données sous la forme de commandes INSERT (au lieu de commande COPY). Cela produira une restauration très lente, mais créera les archives plus portables sur d’autres systèmes de gestion de base de données SQL.

-D

--column-inserts

--attribute-inserts

Sauvegarde les données comme des commandes INSERT avec des noms de colonnes explicites (INSERT INTO table (column, ...) VALUES ...). Cela produira une restauration très lente, mais cela est nécessaire si vous désirez réarranger l’ordre des colonnes.

-f file

--file=file

Envoie la sortie dans le fichier spécifié. Si cela est omis, la sortie standard est utilisée.

-F format

--format=format

Sélectionne le format de la sortie. format peut être l’une des options suivantes :

p

Sort un fichier de script SQL en texte simple (option par défaut)

t

Sort une archive tar appropriée pour une entrée dans pg_restore. Utiliser ce format d’archive permet les réarrangements et/ou l’exclusion d’éléments du schéma au moment de la restauration de la base de données. Il est aussi possible de limiter quelles sont les données à recharger au moment de la restauration.

c

Sort une archive personnalisée appropriée pour une entrée dans pg_restore. C’est le format le plus flexible dans lequel vous pouvez aussi bien réordonner le chargement des données que les éléments du schéma. Ce format est aussi compressé par défaut.

-i

--ignore-version

Ignore les erreurs de version entre pg_dump et le serveur de base de données.

pg_dump peut manipuler des bases de données de version antérieure de PostgreSQL, mais les très anciennes versions ne sont plus compatibles (antérieure à la version 7.0). Utilisez cette option si vous avez besoin d’ignorer la vérification de version (et si pg_dump échoue alors, vous ne pourrez pas dire que vous n’aurez pas été prévenu).

-n namespace

--schema=schema

Sauvegarde le contenu du schema seulement. Si cette option n’est pas spécifiée, tous les schémas non système de la base de données cible seront sauvegardés.

Note : Dans ce mode, pg_dump ne fait aucune tentative pour sauvegarder n’importe quels objets de la base de données qui dépendraient d’autres objets précédent du schéma séléctionné. C’est pourquoi, il n’y a aucune garantie que le résultat de la sauvegarde du schéma simple peut être rechargé avec succès par lui-même dans une base de données vide.

-o

--oids

Sauvegarde les identifiants d’objets (OIDs) pour toutes les tables. Utilisez cette option si votre application référencie d’une certaine façon les colonnes d’OID. (Par exemple, dans une contrainte de clé étrangère). Autrement, cette option ne devrait pas être utlisée.

-O

--no-owner

Ne sort pas les commandes en initialisant le propriétaire des objets pour qu’il soit identique à la base de données originale. Par défaut, pg_dump vous présente une déclaration SET SESSION AUTHORIZATION pour initialiser le propriétaire des éléments du schéma en train d’être créé. Ces déclarations échoueront, sauf si le script est démarré par un superutilisateur (ou par le même utilisateur qui est propriétaire des objets dans le script). Pour faire un script qui peut être restauré par n’importe quel utilisateur, mais donnera aux objets la propriété de l’utilisateur en train de restaurer, , spécifiez -O.

Cette option n’est significative que pour le format texte simple. Pour les autres formats, vous devriez spécifier l’option quand vous appelez pg_restore.

-R

--no-reconnect

Cette option est désuette, mais reste acceptée pour une question de compatibilité avec les versions antérieures.

-s

--schema-only

Ne sauvegarde que le schéma (la définition des données), pas les données.

-S username

--superuser=username

Spécifie le nom du superutilisateur à utiliser lorsque l’on désactive les mécanismes d’autentification. Cela est approprié si --disable-triggers est utilisé. (D’habitude, il est meilleur de l’omettre, et au lieu de cela démarrer le script résultant comme superutilisateur.)

-t table

--table=table

Sauvegarde les données d’une table seulement. Il est possible de faire plusieurs tables avec le même nom si plusieurs tables ont le même nom mais appartiennent à différents schémas ; si vous êtes dans ce cas, toutes les tables correspondantes seront sauvegerdées. Spécifiez à la fois --schema et --table pour ne sélectionner juste qu’une seule table.

Note: Dans ce mode, pg_dump ne fait aucune tentative pour sauvegarder n’importe quels objets de la base de données qui dépendraient d’autres objets précédant du schéma sélectionné. C’est pourquoi il n’a aucune garantie que le résultat de la sauvegarde du schéma simple peut être rechargé avec succès par lui-même dans une base de données vide.

-v

--verbose

Spécifie le mode parlant. Cela demandera à pg_dump d’afficher des messages de progression sur la sortie d’erreur standard.

-x

--no-privileges

--no-acl

Empêche le privilège de droit de sauvegarde (commandes de grant/revoke).

-X use-set-session-authorization

--use-set-session-authorization

Cette option est désuette mais reste acceptée pour des raisons de compatibilité ascendante. Pg_dump se comporte maintenant toujours par défaut dans ce mode.

-X disable-triggers

--disable-triggers

Cette option n’est approprié que lors de création de sauvegarde contenant uniquement des données. Il charge pg_dump d’inclure des commandes pour désactiver temporairement les déclenchements sur les tables cibles, tant que les données sont rechargées. Utilisez ceci si vous avez une vérification d’intégrité référentielle ou d’autres déclenchements que vous ne voulez pas invoquer sur les tables durant le rechargement des données.

Actuellement, les commandes émises pour --disable-triggers doivent être passées comme étant un superutilisisateur. Donc, vous devriez aussi spécifier un nom de superutilisateur avec -S, ou être de préférence prudent de commencer le script résultant comme superutilisateur.

Cette option n’est significative que pour le format texte simple. Pour les autres formats, vous devriez spécifier l’option quand vous appellez pg_restore.

-Z 0..9

--compress=0..9

Spécifie un niveau de compression à utiliser dans les formats d’archives qui gèrent la compression. (Actuellement seules les archives au format personnalisé supportent la compression.)

Les options de lignes de commandes suivantes contrôlent les paramètres de connexion aux bases de données.

-h host

--host=host

Spécifie le nom d’hébergement de la machine sur laquelle le serveur tourne. Si la valeur commence par un slash, le paramètre est utilisé comme un répertoire pour une connection à un répertoire de domaine Unix. La valeur par défaut est prise dans la variable d’environnement PGHOST , si elle est initialisée, sinon une connexion à un répertoire de domaine Unix est tentée.

-p port

--port=port

Spécifie le port TCP ou l’extension de fichier local pour la connexion au domaine Unix sur lequel le serveur écoute les tentatives de connexions. Par défaut la variable d’environnement est PGPORT , si elle est inutilisée, ou la variable utilisée lors de la compilation du serveur.

-U username

Connecte sous le nom donné.

-W

Force la demande de mot de passe. Cela devrait arriver automatiquement si le serveur demande des authentifications par mot de passe.

PGDATABASE

PGHOST

PGPORT

PGUSER

Paramètres par defaut de connexion.

pg_dump exécute en interne des déclarations en SELECT. Si vous avez des problèmes à exécuter pg_dump, soyez sûr d’avoir les droits de sélection d’informations sur la base de données utilisée, par exemple, psql(1).

Si votre groupe de base de données a des compléments locaux à la base de données template1, faites attention de bien restaurer dans une base de données vraiment vide avec pg_dump ; autrement vous aurez probablement des erreurs dues à des duplications de définitions des objets ajoutés. Pour faire une base de données vide sans additions locales, copiez depuis template0 pas de template1, Par exemple :

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump a quelques petites limitations:

•

Lors du déchargement d’une seule table ou lors d’une création d’archive comme texte plein, pg_dump ne manipule pas les objets larges. Les objets larges doivent être déchargés avec la base de données entière en utilisant une des archives au format non texte.

•

Lorsqu’une sauvegarde des données seulement est utilisée et que l’option --disable-triggers est utilisée, pg_dump émet des commandes pour désactiver les déclenchements sur les tables utilisées avant d’insérer les données et les commandes pour réactiver les déclenchements après que les données soient insérées. Si la restauration est arrêtée au milieu, le catalogue système peut être laissé dans un mauvais état.

Les membres d’une archive de type tar sont limités à une taille inférieure à 8 GB. (Ceci est inhérent à la limitation d’un fichier au format tar.) C’est pourquoi ce format ne peut pas être utilisé si une représentation textuelle d’une table excède cette taille. La taille totale d’une archive tar et n’importe quels autres formats de sortie ne sont pas limités, exeption faite du système d’exploitation.

Une fois terminé, il serait sage d’exécuter ANALYZE sur chacune des tables restaurées, ainsi l’optimiseur aura des statistiques utiles.

Pour sauvegarder une base de données :

$ pg_dump mydb > db.out

Pour recharger cette même base de données :

$ psql -d database -f db.out

Pour sauvegarder une base de données appellée mydb qui contient des objets larges dans un fichier tar :

$ pg_dump -Ft -b mydb > db.tar

Pour recharger cette même base de données (avec des objets larges) dans une base de données existante appellée newdb :

$ pg_restore -d newdb db.tar

L’utilitaire pg_dump est apparu la première fois dans Postgres95 release 0.02. Les formats de sortie non texte plein ont été introduits depuis PostgreSQL release 7.1.

pg_dumpall(1), pg_restore(1), psql(1)

Christophe Labarthe, 2003.

Il est possible que cette traduction soit imparfaite ou périmée. En cas de doute, veuillez vous reporter au document original en langue anglaise fourni avec le programme.