pg_dump

Nom

pg_dump --  sauvegarde 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 utilitaire pour sauvegarder une base de données PostgreSQL. Il réalise des sauvegardes consistantes même si la base de données est en cours d'utilisation concurrente. pg_dump ne bloque pas l'accès des autres utilisateurs (ni en lecture ni en écriture).

Les sauvegardes peuvent être sous forme de script ou de fichier d'archive. Les sauvegardes 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 à partir de 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, et même avec quelques modifications, sur d'autres produits de bases de données SQL.

Les autres formats de fichiers d'archive doivent ê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 formats d'archive permettent aussi de sauvegarder et restaurer les << objets larges >>, ce qui n'est pas possible dans une sauvegarde scriptée. 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 Unix standard comme tar.

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

Options

Les options suivantes en ligne de commande contrôlent le contenu et 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 formats d'archive, vous devez spécifier l'option a l'appel de pg_restore.

-b
--blobs

Inclut les objets larges dans la sauvegarde. Un format non textuel doit être choisi.

-c
--clean

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

Cette option est seulement intéressante pour le format texte. Pour les formats d'archive, vous devez spécifier l'option à l'appel de 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 formats d'archive, 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 ralentit 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éordonné 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 ralentit 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 utilisable par pg_restore. Utiliser ce format d'archives permet le réordonnancement et/ou l'exclusion d'objets de la base lors de la restauration de la base de données. Il est aussi possible de sélectionner 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 du chargement des données ainsi que la définition des objets. 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 schéma
--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 sont sauvegardés.

Note : Dans ce mode, pg_dump ne tente pas de sauvegarder tous les 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) comme faisant parti des données de chaque table. Utilisez cette option si votre application référence les colonnes OID (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 ALTER OWNER ou SET SESSION AUTHORIZATION pour initialiser le propriétaire des objets de la base de données. Ces instructions échouent lorsque le script n'est pas 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 remplace le propriétaire de tous les objets, spécifiez -O.

Cette option est seulement utile pour le format texte. Pour les formats d'archive, 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 la définition des objets (le schéma), 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 ne pas utiliser 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 le cas, toutes les tables correspondantes sont 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 fait que pg_dump affiche des commentaires détaillés sur les objets et les heures de début et de fin pour le fichier de sauvegarde, ainsi que 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 disable-dollar-quoting
--disable-dollar-quoting

Cette option désactive l'utilisation des guillemets dollar pour les corps des fonctions et les force à être entre guillemets en utilisant la syntaxe standard des chaînes dans SQL.

-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 à lancer le script résultant en tant que superutilisateur.

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

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

Affiche les commandes SET SESSION AUTHORIZATION du standard SQL au lieu des commandes OWNER TO. Ceci rend la sauvegarde plus compatible avec le standard mais, suivant l'historique des objets dans la sauvegarde, pourrait ne pas restaurer correctement.

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

Le fichier de sauvegarde produit par pg_dump ne contient pas les statistiques utilisées par l'optimiseur pour prendre les décisions de planification des requêtes. Du coup, il est conseillé de lancer ANALYZE après avoir restauré une sauvegarde pour s'assurer de bonnes performances.

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