pg_dump

Nom

pg_dump --  extrait une base de données PostgreSQL dans un script ou un autre fichier d'archive

Synopsis

pg_dump [option...] [nom_base]

Description

pg_dump est un outil pour sauvegarder une base de données PostgreSQL. Il réalise des sauvegardes consistantes même si la base de données est en utilisation concurrente. pg_dump ne bloque pas l'accès des autres utilisateurs (en lecture ou en écriture).

Les sauvegardes peuvent être sous forme de script ou de fichier d'archive. Les fichiers script sont au format texte 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 ces scripts, utilisez psql. Ils peuvent être utilisés pour reconstruire la base de données y compris sur d'autres machines et d'autres architectures avec quelques modifications, y compris sur les autres produits de bases de données SQL.

Les autres formats de fichiers d'archive ont pour but d'être utilisés avec pg_restore pour reconstruire la base de données. Ils permettent aussi à pg_restore de sélectionner ce qui doit être restauré ou même de réordonner les éléments avant qu'ils ne soient restaurés. Les fichiers d'archive sont aussi conçus pour être portable suivant les architectures.

Lorsqu'il est utilisé avec un des formats de fichier d'archive et combiné avec pg_restore, pg_dump fournit un mécanisme flexible d'archivage et de transfert. pg_dump peut être utilisé pour sauvegarder une base de données entière, puis pg_restore peut être utilisé pour examiner l'archive et/ou sélectionner quelles parties de la base de données seront restaurées. Le format de fichier en sortie le plus flexible est le format << personnalisé >> (-Fc). Il permet la sélection et le réordonnancement de tous les éléments archivés 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 au chargement mais est assez flexible ; de plus, il est manipulable avec d'autres outils comme tar.

Lorsque pg_dump est en cours d'exécution, vous devriez examiner la sortie à la recherche de tout message d'avertissement (affiché sur le sortie standard des erreurs), spécialement à la lumière des limitations indiquées ci-dessous.

Options

Les options suivantes en ligne de commande sont utilisées pour contrôler le format de sortie.

nom_base

Spécifie le nom de la base de données à sauvegarder. Si elle n'est pas spécifiée, la variable d'environnement PGDATABASE est utilisée. Dans le cas contraire, le nom de l'utilisateur spécifié pour la connexion est utilisé.

-a
--data-only

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

Cette option est seulement intéressante pour le format texte. Pour les autres formats, vous devez spécifier l'option quand vous appelez pg_restore.

-b
--blobs

Inclut les objets larges dans la sauvegarde.

-c
--clean

Ajoute les commandes pour nettoyer (supprimer) les objets de la base avant (les commandes pour) les supprimer.

Cette option est seulement intéressante pour le format texte. Pour les autres formats, vous devez spécifier l'option lorsque vous appelez pg_restore.

-C
--create

Commence la sortie avec une commande de création de la base de données elle-même et de reconnexion à la nouvelle base de données. (Avec un script de cette forme, peu importe la base de données à laquelle vous vous connectez avant de lancer le script.)

Cette option est seulement intéressante pour le format texte. Pour les autres formats, vous devez spécifier l'option à l'appel de pg_restore.

-d
--inserts

Sauvegarde les données avec des commandes INSERT (plutôt qu'une commande COPY). Ceci ralentira la restauration ; c'est principalement utile pour créer des sauvegardes qui seront chargées dans des bases de données autres que PostgreSQL. Notez que la restauration pourrait échouer si vous avez réordonner l'ordre des colonnes. L'option -D est plus sûre, bien qu'encore plus lente.

-D
--column-inserts
--attribute-inserts

Sauvegarde les données avec des commandes INSERT et des noms de colonnes explicites (INSERT INTO table (colonne, ...) VALUES ...). Ceci ralentira de beaucoup la restauration ; c'est principalement utile pour créer des sauvegardes qui seront chargées dans des bases de données autres que PostgreSQL..

-f file
--file=file

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

-F format
--format=format

Sélectionne le format de la sortie. format correspond à un des éléments suivants :

p

Crée un fichier de scripts SQL en texte simple (par défaut).

t

Crée une archive tar convenable pour pg_restore. Utiliser ce format d'archives permet le réordonnancement et/ou l'exclusion d'éléments du schéma lors de la restauration de la base de données. Il est aussi possible de limiter les données rechargées au moment de la restauration.

c

Crée une archive personnalisée convenable pour pg_restore. C'est le format le plus flexible dans le fait qu'il permet le réordonnancement de la charge des données ainsi que des éléments du schéma. Ce format est aussi compressé par défaut.

-i
--ignore-version

Ignore les différences de version entre pg_dump et le serveur de bases de données.

pg_dump peut gérer des bases de données à partir des versions précédentes de PostgreSQL mais les très anciennes versions ne sont plus supportées (actuellement celles précédant la 7.0). Utilisez cette option si vous avez besoin de ne pas vérifier la version (et si pg_dump échoue à ce moment, ne prétendez pas que vous n'avez pas été prévenu).

-n namespace
--schema=schema

Sauvegarde seulement le contenu de schema. 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 tente pas de sauvegarder tous les autres objets de la base de données qui ne font pas partie du schéma sélectionné. Du coup, il n'y a pas de garantie que la sauvegarde d'un seul schéma puisse être restaurée avec succès dans une base de données propre.

-o
--oids

Sauvegarde les identifiants d'objets (OID) pour chaque table. Utilisez cette option si votre application référence les colonnes OID d'une certaine façon (par exemple dans une contrainte de clé étrangère). Sinon, cette option ne devrait pas être utilisée.

-O
--no-owner

N'affiche pas les commandes d'initialisation du propriétaire des objets pour correspondre à la base de données originale. Par défaut, pg_dump lance des instructions SET SESSION AUTHORIZATION pour initialiser le propriétaire des éléments du schéma. Ces instructions échoueront lorsque le script est lancé sauf s'il est lancé par un superutilisateur (ou par l'utilisateur qui possède tous les objets de ce script). Pour créer un script qui peut restaurer tous les utilisateurs et remplacera le propriétaire de tous les objets, spécifiez -O.

Cette option est seulement utile pour le format texte. Pour les autres formats, vous devez spécifier l'option à l'appel de pg_restore.

-R
--no-reconnect

Cette option est obsolète mais est toujours acceptée pour des raisons de compatibilité ascendante.

-s
--schema-only

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

-S nomutilisateur
--superuser=nomutilisateur

Spécifie le nom du superutilisateur à utiliser lors de la désactivation des déclencheurs. Ceci est seulement utile si --disable-triggers est utilisé. (Habituellement, il est mieux de laisser ceci et de lancer le script en tant que ce superutilisateur.)

-t table
--table=table

Sauvegarde uniquement les données de table. Il est possible d'avoir plusieurs tables avec le même nom dans différents schémas ; si c'est bien le cas, toutes les tables correspondantes seront sauvegardées. Spécifiez à la fois --schema et --table pour sélectionner seulement une table.

Note : Dans ce mode, pg_dump ne fait aucune tentative de sauvegarde des autres objets de la base de données dont la table sélectionnée pourrait dépendre. Du coup, il n'existe aucune garantie que cette sauvegarde d'une seule table pourra être restaurée toute seule dans une base de données propre.

-v
--verbose

Spécifie le mode verbeux. Ceci fera que pg_dump affichera des messages de progression sur la sortie standard des erreurs.

-x
--no-privileges
--no-acl

Empêche la sauvegarde des droits d'accès (commandes grant/revoke).

-X use-set-session-authorization
--use-set-session-authorization

Cette option est obsolète mais est toujours acceptée pour des raisons de compatibilité ascendante. Maintenant, pg_dump se comportera toujours de la façon sélectionnée par cette option.

-X disable-triggers
--disable-triggers

Cette option est seulement utile pour créer une sauvegarde des données seules. Elle demande à pg_dump d'inclure des commandes pour désactiver temporairement les déclencheurs sur les tables cibles pendant que les données sont en cours de chargement. Utilisez ceci si vous avez des vérifications d'intégrité ou d'autres déclencheurs sur les tables, déclencheurs que vous ne souhaitez pas exécuter pendant le chargement des données.

Actuellement, les commandes émises pour --disable-triggers doivent être lancées par le superutilisateur. Donc, vous devez aussi spécifier le nom du superutilisateur avec -S ou, de préférence, faire attention au lancement du script résultant en tant que superutilisateur.

Cette option est seulement utile pour le format texte. Pour les autres formats, vous devez spécifier l'option à l'appel de pg_restore.

-Z 0..9
--compress=0..9

Spécifie le niveau de compression à utiliser. Zéro signifie sans compression. Pour le format d'archive personnalisé, cela signifie la compression des segments individuels des données des tables. La valeur par défaut est de compresser à un niveau modéré. Pour le format texte, indiquer une valeur différente de zéro fait que le fichier entier est compressé, bien qu'il a été envoyé à gzip ; mais par défaut, la sortie n'est pas compressée. Le format d'archive tar ne supporte pas du tout la compression.

pg_dump accepte aussi les arguments suivants comme paramètres de connexion :

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

-p port
--port port

Indique le port TCP ou le fichier local de socket de domaine Unix sur lequel le serveur écoute pour la connexion.

-U nomutilisateur

Nom d'utilisateur à utiliser pour se connecter.

-W

Force la demande d'un mot de passe.

Environnement

PGDATABASE
PGHOST
PGPORT
PGUSER

Paramètres de connexion par défaut.

Diagnostiques

pg_dump exécute en interne des instructions SELECT. Si vous avez des problèmes en lançant pg_dump, assurez-vous d'être capable de sélectionner les informations de la base de données en utilisant, par exemple, psql.

Notes

Si votre groupe de bases de données a des ajouts supplémentaires dans la base de données template1, faites attention à restaurer la sortie de pg_dump dans une base de données réellement vide ; sinon vous obtiendrez certainement des erreurs dûes à la définition dupliquée des objets ajoutés. Pour faire qu'une base de données soit vide et sans ajout local, copiez à partir de template0, et non pas à partir de template1, par exemple :

CREATE DATABASE foo WITH TEMPLATE template0;

pg_dump a quelques limitations :

Les membres des archives tar sont limités à une taille inférieure à 8 Go. (Ceci est une limitation inhérente au format des fichiers tar.) Du coup, ce format ne pourra pas être utilisé si la représentation textuelle d'une table dépasse cette taille. La taille totale d'une archive tar et de tout autre format de sortie n'est pas limitée, sauf peut-être par le système d'exploitation.

Une fois restaurée, il est conseillé de lancer ANALYZE sur chaque table restaurée pour que l'optimiseur dispose de statistiques utiles.

Exemples

Pour sauvegarder une base de données :

$ pg_dump mabase > base.out

Pour recharger cette base de données :

$ psql -d base -f base.out

Pour sauvegarder une base de données nommée mabase, contenant des objets larges dans un fichier tar :

$ pg_dump -Ft -b mabase > base.tar

Pour recharger cette base de données (avec des objets larges) dans une base de données existante appelée nouvellebase :

$ pg_restore -d nouvellebase base.tar

Historique

L'outil pg_dump est d'abord apparu dans Postgres95 version 0.02. Les formats de sortie non texte ont été introduits dans la version 7.1 de PostgreSQL.

Voir aussi

pg_dumpall, pg_restore, psql