pg_dump

Name

pg_dump --  extrait une base PostgreSQL vers un fichier script ou autre fichier archive.

Synopsis

pg_dump [-a | -s] [-b] [-c] [-C] [-d | -D] [-f file] [-F format] [-i] [-n | -N] [-o] [-O] [-R] [-S] [-t table] [-v] [-x] [-X keyword] [-Z 0...9] [-h host] [-p port] [-U username] [-W] dbname

Description

pg_dump est un utilitaire pour extraire une base Postgres vers un fichier script contenant des commandes de requêtes. Les fichiers script sont en format texte et peuvent être utilisés pour reconstruire la base même sur d'autres machines et d'autres architectures., avec quelques modifications même sur d'autres produits SGBDR. De plus, il existe des alternatives dans les formats de fichiers archive comme indiqué avec l'utilisation de pg_restore (1) pour reconstruire la base, qui admettent aussi pg_restore pour sélectionner ce qui doit être restauré, ou même pour retrier les priorités d'items à restaurer. Les fichiers archive sont prévus pour être portables sur diverses architectures.

pg_dump produira les requêtes nécessaires pour régénérer tous les types utilisateurs, fonctions, tables, index, agrégats, et opérateurs. De plus, toutes les données sont copiées en format texte et ainsi facilement copiables à nouveau, aussi bien qu'importables dans des éditeurs.

pg_dump est pratique pour transférer les contenus d'une base à déplacer depuis une installation Postgres vers une autre.

Quand il est utilisé avec un des formats de fichiers archive et combiné avec pg_restore (1), pg_dump fournit un mécanisme souple d'archivage et de transfert. pg_dump pzut être utilisé pour sauvegarder une base entière, ensuite pg_restore peut être utilisé pour examiner l'archive et/ou sélectionner quelles parties de la base seront restaurées. Le format de fichier en sortie le plus souple est "custom" (-Fc). Il permet la sélection et le réordonnancement de tous les items archivés, et il est compressé par défaut. Le format tar (-Ft) n'est pas compressé et il n'est pas possible de réordonnancer les données au chargement, mais d'un autre côté il est très souple; de plus, il peut être manipulé avec d'autres outils comme tar.

Tandis que pg_dump tourne, les sorties peuvent être examinées au niveau des warnings (affichage de l'erreur standard), spécialement à la lumière des limitations listées ci-dessous.

pg_dump fait des sauvegardes consistentes même si la base est utilisée concurremment. pg_dump ne bloque pas les autres utilisateurs qui accèdent à la base (en lecture ou écriture).

Options

pg_dump accepte les arguments en ligne de commande suivants. (Les formes d'options longues ne sont disponibles que sur certaines plateformes).

dbname

Spécifie le nom de la base à sauvegarder.

-a, --data-only

Sauvegarde seulement les données, pas le schéma (définitions de données).

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

-b, --blobs

Inclut les objets longs dans la sauvegarde.

-c, --clean

Commandes de sortie pour nettoyer (drop) les objets de la base avant de les créer.

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

-C, --create

Débute avec une commande pour créer la base elle-même et reconnecter la base créée. (Avec un script de cette forme, peut importe la base à laquelle vous vous connectez avant de lancer le script).

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

-d, --inserts

Sauvegarde les données comme commandes INSERT (d'avantage que comme COPY). Ce qui rendra la restauration très lente, mais permet aux archives d'être portables sur d'autres SGBDR.

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

Sauvegarde les données comme commandes INSERT avec les noms de colonnes explicites (INSERT INTO table (column, ...) VALUES ...). Ce qui rendra la restauration très lente, mais c'est nécessaire si vous voulez modifier l'ordonnancement des colonnes.

-f file, --file=file

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

-F format, --format=format

Sélectionne le format de sortie. Le format peut être un des suivants :

p

Fichier script SQL texte en sortie (par défaut).

t

Sort une archive tar adéquate pour les entrées dans pg_restore. Utiliser ce format d'archive permet de réordonnancer et/ou l'exclusion d'éléments du schéma au moment où la base est restaurée. Il est aussi possible de limiter les données à recharger à la restauration.

c

Sort une archive adéquate pour l'entrée dans pg_restore. C'est le fomat le plus souple en ce qu'il permet le réordonnancement des données chargées aussi bien que des éléments du schéma. Ce format est aussi compressé par défaut.

-i, --ignore-version

Ignore le défaut d'appariement entre pg_dump et le serveur de la base. Chaque version de pg_dump est prévue pour fonctionner avec la version correspondante du serveur de base. Utilisez cette option si vous voulez outrepasser la vérification de version (et si pg_dump échoue sans vous prévenir).

-n, --no-quotes

Supprime les guillemets autour des identifiants sauf absolue nécessité. Ceci peut causer des difficultés au chargement des données sauvegardées s'il y a des mots-clé réservés utilisés comme identifiants. C'est le comportement par défaut de pg_dump avant la version version 6.4.

-N, --quotes

Inclut les guillemets autour des identifiants. Comportement par défaut.

-o, --oids

Sauvegarde les identifiants objet (OID) pour chaque table. Utilisez cette option si votre application référence les colonnes OID de cette façon (ex., dans une contrainte de clé étrangère). Sinon, cette option ne sera pas utilisée.

-O, --no-owner

N'envoit pas de commandes pour vérifier le propriétaire de l'objet sur la base. Typiquement, pg_dump sort des instructions (psql-specific) \connect pour placer le propriétaire des éléments du schéma. Voir aussi -R et -X use-set-session-authorization. Notez que -O n'empêche pas toutes les reconnexions à la base, seuls ceux qui sont exclusivement utilisés pour les ajustements de propriété.

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

-d, --inserts

Sauvegarde les données comme commandes INSERT (d'avantage que comme COPY). Ce qui rendra la restauration très lente, mais permet aux archives d'être portables sur d'autres SGBDR.

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

Sauvegarde les données comme commandes INSERT avec les noms de colonnes explicites (INSERT INTO table (column, ...) VALUES ...). Ce qui rendra la restauration très lente, mais c'est nécessaire si vous voulez modifier l'ordonnancement des colonnes.

-f file, --file=file

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

-F format, --format=format

Sélectionne le format de sortie. Le format peut être un des suivants :

p

Fichier script SQL texte en sortie (par défaut).

t

Sort une archive tar adéquate pour les entrées dans pg_restore. Utiliser ce format d'archive permet de réordonnancer et/ou l'exclusion d'éléments du schéma au moment où la base est restaurée. Il est aussi possible de limiter les données à recharger à la restauration.

c

Sort une archive adéquate pour l'entrée dans pg_restore. C'est le fomat le plus souple en ce qu'il permet le réordonnancement des données chargées aussi bien que des éléments du schéma. Ce format est aussi compressé par défaut.

-i, --ignore-version

Ignore le défaut d'appariement entre pg_dump et le serveur de la base. Chaque version de pg_dump est prévue pour fonctionner avec la version correspondante du serveur de base. Utilisez cette option si vous voulez outrepasser la vérification de version (et si pg_dump échoue sans vous prévenir).

-n, --no-quotes

Supprime les guillemets autour des identifiants sauf absolue nécessité. Ceci peut causer des difficultés au chargement des données sauvegardées s'il y a des mots-clé réservés utilisés comme identifiants. C'est le comportement par défaut de pg_dump avant la version version 6.4.

-N, --quotes

Inclut les guillemets autour des identifiants. Comportement par défaut.

-o, --oids

Sauvegarde les identifiants objet (OID) pour chaque table. Utilisez cette option si votre application référence les colonnes OID de cette façon (ex., dans une contrainte de clé étrangère). Sinon, cette option ne sera pas utilisée.

-O, --no-owner

Ne place pas de commandes de sortie pour vérifier le propiétaire de l'objet sur la base. Typiquement, pg_dump sort les instructions (psql-specific) \connect pour placer le propriétaire des éléments du schéma. Voir aussi -R et -X use-set-session-authorization. Notez que -O n'évite pas toutes les reconnexions à la base, seules celles qui sont exclusivement utilisées pour des ajustemments de propriété.

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

-R, --no-reconnect

Interdit à pg_dump de produire un script qui nécessiterait des reconnexions à la base en cours de restauration. Un script de restauration moyen doit habituellement se reconnecter plusieurs fois à différents utilisateurs pour placer les droits d'origine aux objets. Cette option est un instrument un peu émoussé car il fait que pg_dump perd son information sur les droits de propriété, sauf si vous utilisez l'option -X use-set-session-authorization.

Une raison possible pour laquelle les reconnexions pendant la restauration ne soient pas désirées est que l'accès à la base nécessite des interactions manuelles (ex., les mots-de-passe).

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

-s, --schema-only

Sauvegarde seulement le schéma (définitions de données), pas les données.

-S username, --superuser=username

Les scripts ou les archives créées par pg_dump doivent avoir les droits du superutilisateur dans certains cas, comme lors de la désactivation des déclencheurs ou le placement des droits des éléments d schéma. Cette option spécifie le nom d'utilisateur à utiliser pour ces cas là.

-t table, --table=table

Sauvegarde les données pour la table seulement.

-v, --verbose

Spécifie le mode verbeux.

-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

Normalement, si un script (mode texte) généré par pg_dump doit modifier l'utilisateur courant de la base (ex., pour placer des droits corrects), il utilise la commande psql(1) \connect. Cette commande ouvre une nouvelle connexion, qui peut nécessiter des interactions manuelles (ex., les mots-de-passe). Si vous utilisez l'option -X use-set-session-authorization, pg_dump produira les commandes SET SESSION AUTHORIZATION à la place. Ceci a le même effet, mais nécessite que l'utilisateur qui restaure la base depuis le script généré soit le superutilisateur de la base. Cette option outrepasse l'option -R.

SET SESSION AUTHORIZATION est une commande SQL standard, bien que \connect fonctionne seulement dans psql(1), cette option accroît la portabilité théorique du script produit.

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

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

Spécifie le niveau de compression à utiliser dans les formats d'archive qui supportent la compression.

pg_dump accepte aussi les arguments en ligne de commande suivants pour les paramètres de connexion :

-h host, --host=host

Specifies the host name of the machine on which the server is running. If host begins with a slash, it is used as the directory for the Unix domain socket.

-p port, --port=port

Spécifie le port Internet TCP/IP ou l'extension de fichier socket de domaine local Unix sur lequel le serveur est en attente de connexions. Le numéro de port par défaut est le 5432, ou la valeur de la variable d'environnement PGPORT (si elle est placée).

-U username

Connexion comme utilisateur donné.

-W

Force un prompt de mot-de-passe. Ceci se fait automatiquement si le serveur nécessite l'authentification par mot-de-passe.

Diagnostics

Connection to database 'template1' failed.
connectDBStart() -- connect() failed: No such file or directory
        Is the postmaster running locally
        and accepting connections on Unix socket '/tmp/.s.PGSQL.5432'?
pg_dump ne peut pas se lier au processus postmaster sur l'hôte et le port spécifiés. Si vous voyez ce messsage, assurez vous que le postmaster tourne sur l'hôte correct et que vous avez spécifié le bon port.

Note

pg_dump exécute en interne les instructions SELECT. Si vous avez des problèmes pour lancer pg_dump, assurez vous que vous avez accès en select à la base, par exemple, psql(1).

Notes

pg_dump a quelques limitations.

Exemples

Pour sauvegarder une base :

$ pg_dump mydb > db.out

Pour recharger cette base :

$ psql -d database -f db.out

Pour sauvegarder une base appelée mydb qui contient des objets longs vers une fichier tar :

$ pg_dump -Ft -b mydb > db.tar

Pour recharger cette base (avec les objets longs) vers une base existante appelée newdb:

$ pg_restore -d newdb db.tar

Historique

L'utilitaire pg_dump est apparu dans la version Postgres95 0.02. Les formats de sortie non texte furent introduits dans PostgreSQL version 7.1.

Voir aussi

pg_dumpall(1), pg_restore (1), psql(1), Guide de l'administrateur PostgreSQL.