pg_dump — sauvegarder une base de données PostgreSQL dans un script ou tout autre fichier d'archive
pg_dump
[option_connexion
...] [option
...] [nom_base
]
pg_dump est un outil de sauvegarde d'une base de données PostgreSQL. Les sauvegardes réalisées sont cohérentes, même lors d'accès concurrents à la base de données. pg_dump ne bloque pas l'accès des autres utilisateurs (ni en lecture ni en écriture).
pg_dump sauvegarde seulement une base de données. Pour sauvegarder une instance complète ou pour sauvegarder les objets globaux communs à toutes les bases de données d'une même instance, tels que les rôles et les tablespaces, utilisez pg_dumpall.
Les extractions peuvent être réalisées sous la forme de scripts ou de fichiers d'archive. Les scripts sont au format texte et contiennent les commandes SQL nécessaires à la reconstruction de la base de données dans l'état où elle était au moment de la sauvegarde. La restauration s'effectue en chargeant ces scripts avec psql. Ces scripts permettent de reconstruire la base de données sur d'autres machines et d'autres architectures, et même, au prix de quelques modifications, sur d'autres bases de données SQL.
La reconstruction de la base de données à partir d'autres formats de fichiers archive est obtenue avec pg_restore. pg_restore permet, à partir de ces formats, de sélectionner les éléments à restaurer, voire de les réordonner avant restauration. Les fichiers d'archive sont conçus pour être portables au travers d'architectures différentes.
Utilisé avec un des formats de fichier d'archive et combiné avec
pg_restore, pg_dump
fournit un mécanisme d'archivage et de transfert flexible.
pg_dump peut être utilisé pour sauvegarder une
base de données dans son intégralité ;
pg_restore peut alors être utilisé pour examiner
l'archive et/ou sélectionner les parties de la base de données à restaurer.
Les formats de fichier en sortie les plus flexibles sont le format
« custom » (-Fc
) et le format
« directory » (-Fd
). Ils permettent la
sélection et le ré-ordonnancement de tous les éléments archivés, le support
de la restauration en parallèle. De plus, ils sont compressés par défaut.
Le format « directory » est aussi le seul format à permettre les
sauvegardes parallélisées.
Lors de l'exécution de pg_dump, il est utile de surveiller les messages d'avertissement (affichés sur la sortie erreur standard), en particulier en ce qui concerne les limitations indiquées ci-dessous.
Les options suivantes de la ligne de commande contrôlent le contenu et le format de la sortie.
nom_base
Le nom de la base de données à sauvegarder. En l'absence de précision,
la variable d'environnement PGDATABASE
est utilisée. Si
cette variable n'est pas positionnée, le nom de l'utilisateur de la
connexion est utilisé.
-a
--data-only
Seules les données sont sauvegardées, pas le schéma (définition des données). Les données des tables, les Large Objects, et les valeurs des séquences sont sauvegardées.
Cette option est similaire à --section=data
mais, pour
des raisons historiques, elle n'est pas identique.
-b
--blobs
Inclut les objets larges dans la sauvegarde. C'est le comportement par
défaut, sauf si une des options suivantes est ajoutée :
--schema
, --table
ou
--schema-only
. L'option -b
n'est de
ce fait utile que pour ajouter des Large Objects aux sauvegardes pour
lesquelles un schéma particulier ou une table particulière a été
demandée. Notez que les Large Objects sont considérés comme des données
et, de ce fait, seront inclus si --data-only
est
utilisé, mais pas quand --schema-only
l'est.
-B
--no-blobs
Exclure les objets larges de la sauvegarde.
Quand à la fois les options -b
et -B
sont fournies, le comportement est de produire les objets larges, quand
les données sont sauvegardées, voir la documentation de
-b
.
-c
--clean
Les commandes de suppression (DROP
) des objets de la
base sont écrites avant les commandes de création.
Cette option est utile quand la restauration écrase une base existante.
Si un des objets n'existe pas dans la base de destination, des messages
d'erreur, à ignorer, seront renvoyées lors de la restauration sauf si
l'option --if-exists
est aussi précisée.
Cette option n'a d'intérêt que pour le format texte. Pour les formats
archive, l'option est précisée à l'appel de
pg_restore
.
-C
--create
La sortie débute par une commande de création de la base de données et
de connexion à cette base. Peu importe, dans ce cas, la base de données
de connexion à la restauration. De plus, si --clean
est aussi spécifié, le script supprime puis crée de nouveau la base de
données cible avant de s'y connecter.
Avec --create
, la sortie inclut aussi le commentaire
de la base de données, s'il a été configuré, et toute variable de
configuration spécifique à cette base de données, configurée via les
commandes ALTER DATABASE ... SET ...
et
ALTER ROLE ... IN DATABASE ... SET ...
mentionnant
cette base. Les droits d'accès à la base elle-même sont aussi
sauvegardés, sauf si --no-acl
est indiqué.
Cette option n'a d'intérêt que pour le format texte. Pour les formats
archive, l'option est précisée à l'appel de
pg_restore
.
-f fichier
--file=fichier
La sortie est redirigée vers le fichier indiqué. Ce paramètre peut être
omis pour les sorties en mode fichier, dans ce cas la sortie standard
sera utilisée. Par contre, il doit être fourni pour le format
'directory' (répertoire), où il spécifie le répertoire cible plutôt
qu'un fichier. Dans ce cas, le répertoire est créé par
pg_dump
et ne doit pas exister auparavant.
-e motif
--extension=motif
Ne sauvegarde que les extensions correspondant au
motif
indiqué.
Sans cette option, seront sauvées toutes les extensions non système
de la base sauvegardée. Plusieurs extensions peuvent être sélectionnées à l'aide
de plusieurs paramètres -e
.
Le motif
est interprété
suivant les mêmes règles que la commande \d
de psql (voir Motifs) ;
ainsi plusieurs extensions peuvent être sélectionnées à l'aide de jokers
dans le motif. Dans ce cas, prenez soin d'encadrer le motif de
guillemets simples au besoin, pour empêcher le shell de les interpréter.
Toute configuration de table enregistrée dans
pg_extension_config_dump
est incluse dans la
sauvegarde si l'extension est spécifiée dans --extension
.
Quand -e
est spécifié, pg_dump
ne cherche pas à sauvegarder tout autre objet dont l'extension pourrait
dépendre. En conséquence, il n'y a pas de garantie que le résultat
d'une sauvegarde en précisant les extensions puisse être restauré
dans une base propre.
-E codage
--encoding=codage
La sauvegarde est créée dans l'encodage indiqué. Par défaut, la
sauvegarde utilise celui de la base de données. Le même résultat peut
être obtenu en positionnant la variable d'environnement
PGCLIENTENCODING
avec le codage désiré pour la
sauvegarde. The supported encodings are
described in Section 24.3.1.
-F format
--format=format
Le format de la sortie. format
correspond à
un des éléments suivants :
p
Fichier de scripts SQL en texte simple (défaut).
c
archive personnalisée utilisable par pg_restore. Avec le format de sortie répertoire, c'est le format le plus souple, car il permet la sélection manuelle et le réordonnancement des objets archivés au moment de la restauration. Ce format est aussi compressé par défaut.
d
directory
Produire une archive au format répertoire utilisable en entrée de pg_restore. Cela créera un répertoire avec un fichier pour chaque table et blob exporté, ainsi qu'un fichier appelé Table of Contents (Table des matières) décrivant les objets exportés dans un format machine que pg_restore peut lire. Une archive au format répertoire peut être manipulée avec des outils Unix standard; par exemple, les fichiers d'une archive non-compressée peuvent être compressés avec l'outil gzip. Ce format est compressé par défaut et supporte les sauvegardes parallélisées.
t
Archive tar
utilisable par
pg_restore. Le format tar est compatible
avec le format répertoire; l'extraction d'une archive au format tar
produit une archive au format répertoire valide. Toutefois, le
format tar ne supporte pas la compression. Par ailleurs, lors de
l'utilisation du format tar, l'ordre de restauration des données
des tables ne peut pas être changé au moment de la restauration.
-j njobs
--jobs=njobs
Exécute une sauvegarde parallélisée en sauvegardant njobs
tables simultanément. Cette
option réduit la durée de la sauvegarde mais elle augmente aussi la
charge sur le serveur de base de données. Vous ne pouvez utiliser cette
option qu'avec le format de sortie répertoire car c'est le seul format
où plusieurs processus peuvent écrire leur données en même temps.
pg_dump ouvrira njobs
+ 1 connexions à la base de
données. Assurez-vous donc que la valeur de max_connections est configurée suffisamment haut pour
permettre autant de connexions.
Réclamer des verrous exclusifs sur les objets de la base lors de
l'exécution d'une sauvegarde parallélisée peut causer l'échec de la
sauvegarde. La raison en est que le processus principal de
pg_dump réclame des verrous partagés
(ACCESS SHARE) sur les
objets que les processus fils vont sauvegarder plus tard pour s'assurer
que personne ne les supprime pendant la sauvegarde. Si un autre client
demande alors un verrou exclusif sur une table, ce verrou ne sera pas
accepté mais mis en queue, en attente du relâchement du verrou partagé
par le processus principal. En conséquence, tout autre accès à la table ne
sera pas non plus accepté. Il sera lui-aussi mis en queue, après la
demande de verrou exclusif. Cela inclut le processus fils essayant de
sauvegarder la table. Sans autre précaution, cela résulterait en un
classique « deadlock ». Pour détecter ce conflit, le processus fils
pg_dump réclame un nouveau verrou partagé en
utilisant l'option NOWAIT
. Si le processus fils
n'obtient pas ce verrou, quelqu'un d'autre doit avoir demandé un verrou
exclusif entre temps, et il n'existe donc aucun moyen de continuer la
sauvegarde. pg_dump n'a d'autre choix que
d'annuler la sauvegarde.
Pour réaliser une sauvegarde cohérente, le serveur de la base de
données a besoin de supporter les images (« snapshots ») synchronisées.
Cette fonctionnalité a été introduite avec
PostgreSQL version 9.2 pour les serveurs
primaires et version 10 pour les serveurs secondaires. Avec cette
fonctionnalité, les clients de la base de données peuvent s'assurer de
voir le même ensemble de données, même s'ils utilisent des connexions
différentes. pg_dump -j
utilise plusieurs connexions
à la base de données ; il se connecte une première fois en tant
que processus principal et une fois encore par processus fils. Sans la
fonctionnalité d'images synchronisées, les différent processus ne
pourraient pas garantir de voir les mêmes données sur chaque connexion,
ce qui aurait pour résultat une sauvegarde incohérente.
Si vous voulez exécuter une sauvegarde parallélisée à partir d'un
serveur antérieur à la version 9.2, vous devez vous assurer que le
contenu de la base ne change pas entre le moment où le processus principal
se connecte à la base de données et celui où le dernier processus fils se
connecte à la même base de données. La façon la plus simple est de
mettre en pause tout processus de modification (DDL et DML) qui a eu
accès à la base avant le début de la sauvegarde. Vous aurez besoin
d'utiliser l'option --no-synchronized-snapshots
si
vous exécutez pg_dump -j
sur une version de
PostgreSQL antérieure à la 9.2.
-n motif
--schema=motif
Sauvegarde uniquement les schémas correspondant à schema
; la sélection se fait à la
fois sur le schéma et sur les objets qu'il contient. Quand cette option
n'est pas indiquée, tous les schémas non système de la base cible sont
sauvegardés. Plusieurs schémas peuvent être indiqués en utilisant
plusieurs fois l'option -n
. De plus, le paramètre
motif
est interprété
comme un modèle selon les règles utilisées par les commandes
\d
de psql (voir Motifs). Du coup, plusieurs schémas peuvent être
sélectionnés en utilisant des caractères joker dans le modèle. Lors de
l'utilisation de ces caractères, il faut faire attention à placer le
modèle entre guillemets, si nécessaire, pour empêcher le shell de
remplacer les jokers ; voir Exemples.
Quand -n
est indiqué,
pg_dump ne sauvegarde aucun autre objet de
la base que ceux dont les schémas sélectionnés dépendent. Du coup, il
n'est pas garanti que la sauvegarde d'un schéma puisse être restaurée
avec succès dans une base vide.
Les objets qui ne font pas partie du schéma comme les objets larges ne
sont pas sauvegardés quand -n
est précisé. Ils
peuvent être rajoutés avec l'option --blobs
.
-N motif
--exclude-schema=motif
Ne sauvegarde pas les schémas correspondant au modèle motif
. Le modèle est interprété selon
les même règles que -n
. -N
peut aussi
être indiqué plus d'une fois pour exclure des schémas correspondant à
des modèles différents.
Quand les options -n
et -N
sont
indiquées, seuls sont sauvegardés les schémas qui correspondent à au
moins une option -n
et à aucune option
-N
. Si -N
apparaît sans
-n
, alors les schémas correspondant à
-N
sont exclus de ce qui est une sauvegarde normale.
-O
--no-owner
Les commandes d'initialisation des possessions des objets au regard de
la base de données originale ne sont pas produites. Par défaut,
pg_dump engendre des instructions
ALTER OWNER
ou SET SESSION
AUTHORIZATION
pour fixer ces possessions. Ces instructions
échouent lorsque le script n'est pas lancé par un super-utilisateur (ou
par l'utilisateur qui possède tous les objets de ce script). L'option
-O
est utilisée pour créer un script qui puisse être
restauré par n'importe quel utilisateur. En revanche, c'est cet
utilisateur qui devient propriétaire de tous les objets.
Cette option n'a d'intérêt que pour le format texte. Pour les formats
archive, l'option est précisée à l'appel de
pg_restore
.
-R
--no-reconnect
Cette option, obsolète, est toujours acceptée pour des raisons de compatibilité ascendante.
-s
--schema-only
Seule la définition des objets (le schéma) est sauvegardée, pas les données.
Cette option est l'inverse de --data-only
. Elle est
similaire, mais pas identique (pour des raisons historiques), à
--section=pre-data --section=post-data
.
(Ne pas la confondre avec l'option --schema
qui
utilise le mot « schema » dans un contexte différent.)
Pour exclure les données de la table pour seulement un sous-ensemble
des tables de la base de données, voir
--exclude-table-data
.
-S nom_utilisateur
--superuser=nom_utilisateur
Le nom du super-utilisateur à utiliser lors de la désactivation des
triggers. Cela n'a d'intérêt que si l'option
--disable-triggers
est précisée. (En règle générale,
il est préférable de ne pas utiliser cette option et de lancer le
script produit en tant que super-utilisateur.)
-t motif
--table=motif
Sauvegarde seulement les tables dont le nom correspond à motif
. Plusieurs tables sont sélectionnables
en utilisant plusieurs fois l'option -t
. De plus, le
paramètre motif
est
interprété comme un modèle suivant les règles utilisées par les
commandes \d
de psql
(voir Motifs). Du coup, plusieurs tables
peuvent être sélectionnées en utilisant des caractères joker dans le
modèle. Lors de l'utilisation de ces caractères, il faut faire
attention à placer le modèle entre guillemets, si nécessaire, pour
empêcher le shell de remplacer les jokers ; voir Exemples.
Conçue pour les tables, cette option peut être utilisée pour
sauvegarder la définition des vues, vues matérialisées, tables externes
et séquences correspondantes. Elle ne sauvegardera pas le contenu des
vues et des vues matérialisées. Le contenu des tables externes ne sera
sauvegardé que si le serveur distant correspondant est précisé avec
l'option --include-foreign-data
.
Les options -n
et -N
n'ont aucun
effet quand l'option -t
est utilisée car les tables
sélectionnées par -t
sont sauvegardées quelle que soit
la valeur des options relatives aux schémas. Les objets qui ne sont pas
des tables ne sont pas sauvegardés.
Quand -t
est indiqué,
pg_dump ne sauvegarde aucun autre objet de
la base dont la (ou les) table(s) sélectionnée(s) pourrai(en)t
dépendre. Du coup, il n'est pas garanti que la sauvegarde spécifique
d'une table puisse être restaurée avec succès dans une base vide.
-T motif
--exclude-table=motif
Ne sauvegarde pas les tables correspondant au modèle motif
. Le modèle est interprété selon
les même règles que -t
. -T
peut aussi
être indiqué plusieurs pour exclure des tables correspondant à des
modèles différents.
Quand les options -t
et -T
sont
indiquées, seules sont sauvegardées les tables qui correspondent à au
moins une option -t
et à aucune option
-T
. Si -T
apparaît sans
-t
, alors les tables correspondant à
-T
sont exclues de ce qui est une sauvegarde normale.
-v
--verbose
Mode verbeux. pg_dump affiche des commentaires détaillés sur les objets et les heures de début et de fin dans le fichier de sauvegarde. Des messages de progression sont également affichés sur la sortie d'erreur standard. Répéter l'option entraîne l'apparition de messages de débogage supplémentaires sur la sortie d'erreur standard.
-V
--version
Affiche la version de pg_dump puis quitte.
-x
--no-privileges
--no-acl
Les droits d'accès (commandes grant/revoke) ne sont pas sauvegardés.
-Z 0..9
--compress=0..9
Indique le niveau de compression à utiliser. Zéro signifie sans compression. Pour le format d'archive personnalisé et le format répertoire, cela signifie la compression des segments individuels des données des tables. Par défaut, la compression se fait à un niveau modéré. Pour le format texte, indiquer une valeur différente de zéro implique une compression du fichier complet, comme s'il était passé à gzip ; mais par défaut, la sortie n'est pas compressée. Le format d'archive tar ne supporte pas du tout la compression.
--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 futures versions sans avertissement.
--column-inserts
--attribute-inserts
Extraire les données en tant que commandes INSERT
avec des noms de colonnes explicites (INSERT INTO
). 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. Toute erreur lors du
rechargement causera la perte uniquement des lignes faisant partie du
table
(colonne
,
...) VALUES ...INSERT
problématique, et pas du contenu complet de
la table.
--disable-dollar-quoting
Cette option désactive l'utilisation du caractère dollar comme délimiteur de corps de fonctions, et force leur délimitation en tant que chaîne SQL standard.
--disable-triggers
Cette option ne s'applique que dans le cas d'une extraction de données seules. Ceci demande à pg_dump d'inclure des commandes pour désactiver temporairement les triggers sur les tables cibles pendant que les données sont rechargées. Utilisez ceci si, sur les tables, vous avez des contraintes d'intégrité ou des triggers que vous ne voulez pas invoquer pendant le rechargement.
À l'heure actuelle, les commandes émises pour
--disable-triggers
doivent être exécutées en tant que
super-utilisateur. Par conséquent, vous devez aussi spécifier un nom de
super-utilisateur avec -S
, ou préférablement faire
attention à lancer le script résultat en tant que super-utilisateur.
Cette option n'a de sens que pour le format texte simple. Pour les
formats d'archive, vous pouvez spécifier cette option quand vous
appelez pg_restore
.
--enable-row-security
Cette option est seulement adéquate lors de la sauvegarde du contenu d'une table disposant du mode de sécurité niveau ligne. Par défaut, pg_dump configurera row_security à off pour s'assurer que toutes les données de la table soient sauvegardées. Si l'utilisateur n'a pas les droits suffisant pour contourner la sécurité niveau ligne, alors une erreur est renvoyée. Ce paramètre force pg_dump à configurer row_security à on, permettant à l'utilisateur de ne sauvegarder que le contenu auquel il a le droit d'accéder.
Notez que si vous utilisez cette option actuellement, vous serez
certainement intéressé à faire une sauvegarde au format
INSERT
car les politiques de sécurité ne sont pas
respectées par l'instruction COPY FROM
.
--exclude-table-data=motif
Ne sauvegarde pas les données pour toute table correspondant au motif
indiqué par motif
. Le
motif est interprété selon les même règles que pour l'option
-t
. --exclude-table-data
peut être
utilisé plusieurs fois pour exclure des tables dont le nom correspond à
des motifs différents. Cette option est utile quand vous avez besoin de
la définition d'une table particulière mais pas de ses données.
Pour exclure les données de toutes les tables de la base, voir
--schema-only
.
--extra-float-digits=nchiffres
Utilise la valeur spécifiée pour extra_float_digits
lors de la
sauvegarde de valeurs en virgule flottante, au lieu de la précision
maximale disponible. Les sauvegardes de routine ne devraient pas
utiliser cette option.
--if-exists
Utilise des commandes DROP ... IF EXISTS
pour
supprimer des objets dans le mode --clean
. Cela
permet de supprimer les erreurs « does not exist » qui
seraient sinon renvoyées. Cette option n'est pas valide sauf si
--clean
est aussi indiquée.
--include-foreign-data=foreignserver
Sauvegarde les données de toute table externe ayant comme serveur
distant foreignserver
.
Plusieurs serveurs distants peuvent être sélectionnés en utilisant
plusieurs fois l'options --include-foreign-data
. De
plus, le paramètre foreignserver
est interprété comme un
motif suivant les mêmes règles que celles utilisées par les commandes
\d
de psql (voir Motifs ci-dessous), donc plusieurs serveurs
distants peuvent aussi être sélectionnés en écrivant des caractères
joker dans le motif. Lors de l'utilisation des jokers, faites
attention à placer le motif entre guillemets pour empêcher le shell de
les prendre en compte ; voir Exemples
ci-dessous. Le seule exception est qu'un motif vide est interdit.
L'utilisation de jokers dans --include-foreign-data
pourrait donner accès à des serveurs distants inattendus. De plus,
pour utiliser cette option en toute sécurité, assurez-vous que le serveur
nommé a un propriétaire de confiance.
Quand --include-foreign-data
est précisé,
pg_dump ne vérifie pas que la table
externe est accessible en écriture. De ce fait, il n'y a pas de
garantie que la sauvegarde des données de la table distante pourra
être restaurée sans erreurs.
--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. Toute erreur lors du
rechargement fera que seules les lignes comprises dans le
INSERT
problématique seront perdues, plutôt que le
contenu entier de la table. Notez que la restauration pourrait échouer
si vous avez modifié l'ordre des colonnes. L'option
--column-inserts
protège contre les changements
d'ordre des colonnes au prix de lenteurs supplémentaires.
--load-via-partition-root
Lors de l'export de données d'une partition, faire que les instructions
COPY
ou INSERT
ciblent la racine
du partitionnement qui contient cette partition, plutôt que la
partition elle-même. Ceci fait que la partition appropriée soit
re-déterminée pour chaque ligne au moment du chargement. Ceci peut être
utile quand le rechargement des données se fait sur un serveur où les
lignes ne tomberont pas forcément dans les mêmes partitions que celles
du serveur original. Ceci pourrait arriver si la colonne de
partitionnement est de type text et que les deux systèmes ont une
définition différente du collationnement utilisé pour tier la colonne
de partitionnement.
--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
indiqué. L'expiration peut
être spécifié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.
--no-comments
Ne pas sauvegarder les commentaires.
--no-publications
Ne pas sauvegarder les publications.
--no-security-labels
Ne pas sauvegarder les labels de sécurité.
--no-subscriptions
Ne pas sauvegarder les souscriptions.
--no-sync
Par défaut, pg_dump
attendra que tous les fichiers
aient été écrits de manière sûre sur disque. Cette option force
pg_dump
à rendre la main sans attendre, ce qui est
plus rapide, mais signifie qu'un arrêt brutal du serveur survenant
après la sauvegarde peut laisser la sauvegarde dans un état corrompu.
De manière générale, cette option est utile durant les tests mais ne
devrait pas être utilisée dans un environnement de production.
--no-synchronized-snapshots
Cette option permet l'exécution de pg_dump -j
sur un
serveur de version antérieure à la 9.2. Voir la documentation sur le
paramètre -j
pour plus de détails.
--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.
Cette option n'a de sens que pour le format texte simple. Pour les
formats d'archive, vous pouvez spécifier cette option quand vous
appelez pg_restore
.
--no-toast-compression
Ne génère pas de commandes pour définir les méthodes de compression TOAST. Avec cette option, toutes les colonnes seront restaurées avec la méthode de compression par défaut en vigueur au moment de la restauration.
--no-unlogged-table-data
Ne pas exporter le contenu des tables non journalisées (unlogged). Cette option n'a aucun effet sur le fait que la définition (schéma) des tables soit exportée ou non; seul l'export des données de la table est supprimé. Les données des tables non journalisées sont toujours exclues lors d'une sauvegarde à partir d'un serveur en standby.
--on-conflict-do-nothing
Ajouter ON CONFLICT DO NOTHING
aux commandes
INSERT
. Cette option n'est seulement valide que si
--inserts
, --column-inserts
ou
--rows-per-insert
est aussi utilisée.
--quote-all-identifiers
Force la mise entre guillemets de tous les identifiants. Cette option
est recommandée lors de la sauvegarde d'un serveur
PostgreSQL dont la version majeure est
différente de celle du pg_dump ou quand le
résultat est prévu d'être rechargé dans une autre version majeure. Par
défaut, pg_dump met entre guillemets
uniquement les identifiants qui sont des mots réservés dans sa propre
version majeure. Ceci peut poser parfois des problèmes de compatibilité
lors de l'utilisation de serveurs de versions différentes qui auraient
des ensembles différents de mots clés. Utiliser
--quote-all-identifiers
empêche ce type de problèmes
au prix d'un script résultant plus difficile à lire.
--rows-per-insert=nlignes
Sauvegarde les données sous la forme de commandes
INSERT
(plutôt qu'avec COPY
).
Contrôle le nombre maximum de lignes par commande
INSERT
. La valeur indiquée doit être strictement
positive. Toute erreur lors du rechargement provoquera uniquement la
perte des lignes faisant partie du INSERT
problématique, et non pas le contenu complet de la table.
--section=nom_section
Sauvegarde seulement la section nommée. Le nom de la section peut être
pre-data
, data
ou
post-data
. Cette option peut être spécifiée plus d'une
fois pour sélectionner plusieurs sections. La valeur par défaut est
toutes les sections.
La section data contient toutes les données des tables ainsi que la définition des Large Objects et les valeurs des séquences. Les éléments post-data incluent la définition des index, triggers, règles et contraintes (autres que les contraintes de vérification). Les éléments pre-data incluent en tous les autres éléments de définition.
--serializable-deferrable
Utiliser une transaction sérialisable
pour l'export,
pour garantir que l'instantané utilisé est cohérent avec les états
futurs de la base; mais ceci est effectué par l'attente d'un point dans
le flux des transactions auquel aucune anomalie ne puisse être
présente, afin qu'il n'y ait aucun risque que l'export échoue ou cause
l'annulation d'une autre transaction pour erreur de
sérialisation
. Voyez Chapitre 13 pour davantage
d'informations sur l'isolation des transactions et le contrôle d'accès
concurrent.
Cette option est inutile pour une sauvegarde qui ne sera utilisée qu'en cas de récupération après sinistre. Elle pourrait être utile pour une sauvegarde utilisée pour charger une copie de la base pour du reporting ou toute autre activité en lecture seule tandis que la base originale continue à être mise à jour. Sans cela, la sauvegarde serait dans un état incohérent avec l'exécution sérielle des transactions qui auront été finalement validées. Par exemple, si un traitement de type batch est exécuté, un batch pourrait apparaître comme terminé dans la sauvegarde sans que tous les éléments du batch n'apparaissent.
Cette option ne fera aucune différence si aucune transaction en lecture-écriture n'est active au lancement de pg_dump. Si des transactions en lecture-écriture sont actives, le démarrage de la sauvegarde pourrait être retardé pour une durée indéterminée. Une fois qu'il sera démarré, la performance est identique à celle de la sauvegarde sans cette option.
--snapshot=nom_snapshot
Utilise l'image de base de données synchronisée spécifiée lors de la sauvegarde d'une base de données (voir Tableau 9.90 pour plus de détails).
Cette option est utile lorsqu'il est nécessaire de synchroniser la sauvegarde avec un slot de réplication logique (voir Chapitre 49) ou avec une session concurrente.
Dans le cas d'une sauvegarde parallèle, le nom de l'image défini par cette option est utilisé plutôt que de prendre une nouvelle image de base.
--strict-names
Implique que chaque qualificateur d'extension (-e
/
--extension
), de schéma(-n
/--schema
)
et de table (-t
/--table
)
corresponde à au moins un ou une extension/schéma/table dans la base à
sauvegarder.
Notez que, si aucun motif d'extension/schéma/table ne trouve une correspondance,
pg_dump générera une erreur, y compris sans
--strict-names
.
Cette option n'a pas d'effet sur -N
/
--exclude-schema
, -T
/
--exclude_table
et
--exclude-table-date
. Tout échec de correspondance
pour un motif d'exclusion n'est pas considéré comme une erreur.
--use-set-session-authorization
Émettre des commandes SQL standard SET SESSION
AUTHORIZATION
à la place de commandes ALTER
OWNER
pour déterminer l'appartenance d'objet. Ceci rend
l'extraction davantage compatible avec les standards, mais, suivant
l'historique des objets de l'extraction, peut ne pas se restaurer
correctement. Par ailleurs, une extraction utilisant SET
SESSION AUTHORIZATION
nécessitera certainement des droits
super-utilisateur pour se restaurer correctement, alors que
ALTER OWNER
nécessite des droits moins élevés.
-?
--help
Affiche l'aide sur les arguments en ligne de commande de pg_dump, puis quitte
Les options de ligne de commande suivantes gèrent les paramètres de connexion :
-d nom_base
--dbname=nom_base
Indique le nom de la base de données de connexion. Ceci revient à
spécifier nom_base
comme
premier argument sans option sur la ligne de commande. Ce nom de base
peut être remplacé par une chaîne de
connexion. Dans ce cas, les paramètres de la chaîne de connexion
surchargeront toutes les options en ligne de commande conflictuelles.
-h hôte
--host hôte
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. La valeur par
défaut est fournie par la variable d'environnement
PGHOST
, si elle est initialisée. Dans le cas contraire,
une connexion sur la socket de domaine Unix est tentée.
-p port
--port port
Le port TCP ou le fichier local de socket de domaine Unix sur lequel le
serveur écoute les connexions. La valeur par défaut est fournie par la
variable d'environnement PGPORT
, si elle est
initialisée. Dans le cas contraire, il s'agit de la valeur fournie à la
compilation.
-U nomutilisateur
--username nomutilisateur
Le nom d'utilisateur utilisé pour 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_dump à demander un mot de passe avant la connexion à une base de données.
Cette option n'est jamais nécessaire car
pg_dump demande automatiquement un mot de
passe si le serveur exige une authentification par mot de passe.
Néanmoins, pg_dump perd une tentative de
connexion pour tester si le serveur demande un mot de passe. Dans
certains cas, il est préférable d'ajouter l'option -W
pour éviter la tentative de connexion.
--role=nomrole
Spécifie un rôle à utiliser pour créer l'extraction. Avec cette option,
pg_dump é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_dump 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 super-utilisateur, et
l'utilisation de cette option permet que les extractions soient faites
sans violer cette politique.
PGDATABASE
PGHOST
PGOPTIONS
PGPORT
PGUSER
Paramètres de connexion par défaut.
PG_COLOR
Indique s'il faut utiliser la couleur dans les messages de diagnostic.
Les valeurs possibles sont always
,
auto
, never
.
Cet outil, comme la plupart des autres outils PostgreSQL, utilise les variables d'environnement supportées par la bibliothèque libpq (voir Section 34.15).
pg_dump exécute intrinsèquement des instructions
SELECT
. Si des problèmes apparaissent à l'exécution de
pg_dump, psql peut être
utilisé pour s'assurer qu'il est possible de sélectionner des informations
dans la base de données. De plus, tout paramètre de connexion par défaut et
toute variable d'environnement utilisé par la bibliothèque
libpq s'appliquent.
L'activité générée par pg_dump dans la base de
données est normalement collectée par le collecteur de statistiques. Si
c'est gênant, vous pouvez positionner le paramètre
track_counts
à false via PGOPTIONS
ou la
commande ALTER USER
.
Si des ajouts locaux à la base template1
ont été
effectués, il est impératif de s'assurer que la sortie de
pg_dump est effectivement restaurée dans une
base vide ; dans le cas contraire, il est fort probable que la
duplication des définitions des objets ajoutés engendre des erreurs. Pour
obtenir une base vide de tout ajout local, on utilise
template0
à la place de template1
comme modèle. Par exemple :
CREATE DATABASE foo WITH TEMPLATE template0;
Quand une sauvegarde des seules données est sélectionnée et que l'option
--disable-triggers
est utilisée,
pg_dump engendre des commandes de désactivation
des déclencheurs sur les tables utilisateur avant l'insertion des données,
puis après coup, des commandes de réactivation après l'insertion. Si la
restauration est interrompue, il se peut que les catalogues systèmes
conservent cette position.
Le fichier de sauvegarde produit par pg_dump ne
contient pas les statistiques utilisées par l'optimiseur pour la
planification des requêtes. Il est donc conseillé, pour assurer des
performances optimales, de lancer ANALYZE
après la
restauration d'une sauvegarde ; voir Section 25.1.3 et Section 25.1.6 pour plus
d'informations.
Parce que pg_dump est utilisé pour transférer
des données vers des nouvelles versions de
PostgreSQL, la sortie de
pg_dump devra pouvoir se charger dans les
versions du serveur PostgreSQL plus récentes que
la version de pg_dump.
pg_dump peut aussi extraire des données de
serveurs PostgreSQL plus anciens que sa propre
version. (À l'heure actuelle, les versions de serveurs supportées vont
jusqu'à la 8.0.) Toutefois, pg_dump ne peut pas
réaliser d'extraction de serveurs PostgreSQL
plus récents que sa propre version majeure ; il refusera même
d'essayer, plutôt que de risquer de fournir une extraction invalide. Par
ailleurs, il n'est pas garanti que la sortie de
pg_dump puisse être chargée dans un serveur
d'une version majeure plus ancienne -- pas même si l'extraction a
été faite à partir d'un serveur dans cette version. Charger un fichier
d'extraction dans un serveur de version plus ancienne pourra requérir une
édition manuelle du fichier pour supprimer les syntaxe incomprises de
l'ancien serveur. L'utilisation de l'option
--quote-all-identifiers
est recommendée lors de
l'utilisation avec des versions différentes, car cela permet d'empêcher la
venue de problèmes provenant de listes de mots clés dans différentes
versions de PostgreSQL.
Lors de la sauvegarde des souscription de réplication logique,
pg_dump générera des commandes CREATE
SUBSCRIPTION
qui utilisent l'option connect =
false
, afin que la restauration des souscriptions ne fasse pas de
connexions distantes pour créer un slot de réplication ou pour la copie
initiale de table. De cette façon, la sauvegarde peut être restaurée sans
avoir besoin d'un accès réseau aux serveurs distants. Il est alors à la
charge de l'utilisateur de réactiver les souscriptions de manière adaptée.
Si les hôtes impliquées ont changés, l'information de connexion pourrait
nécessiter d'être changée. Il pourrait également être approprié de
tronquer les tables cibles avant de lancer une nouvelle copie complète des
tables.
Sauvegarder une base appelée ma_base
dans un script
SQL :
$
pg_dump ma_base > base.sql
Pour sauvegarder une base de données dans une archive au format répertoire :
$
pg_dump -Fd ma_base -f rep_sauve
Charger ce script dans une base nouvellement créée et nommée
nouvelle_base
:
$
psql -d nouvelle_base -f base.sql
Sauvegarder une base dans un fichier au format personnalisé :
$
pg_dump -Fc ma_base > base.dump
Pour sauvegarder une base de données en utilisant le format répertoire et en activant la parallélisation sur cinq jobs :
$
pg_dump -Fd ma_base -j 5 -f rep_sauvegarde
Charger un fichier d'archive dans une nouvelle base nommée
nouvelle_base
:
$
pg_restore -d nouvelle_base base.dump
Pour recharger un fichier archive dans la même base de données, annuler le contenu actuel de cette base :
$
pg_restore -d postgres --clean --create db.dump
Sauvegarder la table nommée mytab
:
$
pg_dump -t ma_table ma_base > base.sql
Sauvegarder toutes les tables du schéma detroit
et dont
le nom commence par emp
sauf la table nommée
traces_employes
:
$
pg_dump -t 'detroit.emp*' -T detroit.traces_employes ma_base > base.sql
Sauvegarder tous les schémas dont le nom commence par
est
ou ouest
et se termine par
gsm
, en excluant les schémas dont le nom contient le mot
test
:
$
pg_dump -n 'est*gsm' -n 'ouest*gsm' -N '*test*' ma_base > base.sql
Idem mais en utilisant des expressions rationnelles dans les options :
$
pg_dump -n '(est|ouest)*gsm' -N '*test*' ma_base > base.sql
Sauvegarder tous les objets de la base sauf les tables dont le nom commence
par ts_
:
$
pg_dump -T 'ts_*' ma_base > base.sql
Pour indiquer un nom qui comporte des majuscules dans les options
-t
et assimilées, il faut ajouter des guillemets
doubles ; sinon le nom est converti en minuscules (voir Motifs). Les guillemets doubles sont interprétés par
le shell et doivent donc être placés entre guillemets. Du coup, pour
sauvegarder une seule table dont le nom comporte des majuscules, on utilise
une commande du style :
$
pg_dump -t "\"NomAMajuscule\"" ma_base > ma_base.sql