pg_restore — restaure une base de données PostgreSQL à partir d'un fichier d'archive créé par pg_dump
pg_restore
[option_connexion
...] [option
...] [nom_fichier
]
pg_restore est un outil pour restaurer une base de données PostgreSQL à partir d'une archive créée par pg_dump dans un des formats non textuel. Il lance les commandes nécessaires pour reconstruire la base de données dans l'état où elle était au moment de sa sauvegarde. Les fichiers d'archive permettent aussi à pg_restore d'être sélectif sur ce qui est restauré ou même de réordonner les éléments à restaurer. Les fichiers d'archive sont conçus pour être portables entre les architectures.
pg_restore peut opérer dans deux modes. Si un nom de base de données est spécifié, pg_restore se connecte à cette base de données et restaure le contenu de l'archive directement dans la base de données. Sinon, un script contenant les commandes SQL nécessaires pour reconstruire la base de données est créé et écrit dans un fichier ou sur la sortie standard. La sortie du script est équivalente à celles créées par le format en texte plein de pg_dump. Quelques-unes des options contrôlant la sortie sont du coup analogues aux options de pg_dump.
De toute évidence, pg_restore ne peut pas
restaurer l'information qui ne se trouve pas dans le fichier d'archive.
Par exemple, si l'archive a été réalisée en utilisant l'option donnant les
« données sauvegardées par des commandes
INSERT
», pg_restore ne
sera pas capable de charger les données en utilisant des instructions
COPY
.
pg_restore accepte les arguments suivants en ligne de commande.
nom_fichier
Spécifie l'emplacement du fichier d'archive (ou du répertoire pour une archive au format « directory ») à restaurer. S'il n'est pas spécifié, l'entrée standard est utilisée.
-a
--data-only
Restaure seulement les données, pas les schémas (définitions des données). Les données des tables, les Large Objects, et les valeurs des séquences sont restaurées si elles sont présentes dans l'archive.
Cette option est similaire à --section=data
mais, pour
des raisons historiques, elle n'est pas identique.
-c
--clean
Avant de restaurer les objets de la base, lance des commandes SQL
DROP
pour supprimer tous les objets à restaurer.
Cette option est utile pour surcharger une base existante. Si un
des objets n'existe pas dans la base de destination, des messages
d'erreurs, à ignorer, seront renvoyées sauf si l'option
--if-exists
est aussi indiquée.
-C
--create
Crée la base de données avant de la restaurer. Si l'option
--clean
est aussi indiquée, supprime puis crée de
nouveau la base de données cible avant de s'y connecter.
Avec --create
, pg_restore
restaure aussi le commentaire de la base de données, s'il a été
configuré, et toutes variables de configuration spécifiques à cette
base, autrement dit toutes les commandes ALTER DATABASE ...
SET ...
et ALTER ROLE ... IN DATABASE ... SET
...
qui mentionnent cette base. Les droits d'accès à la base
elle-même sont aussi restaurés sauf si --no-acl
est
spécifié.
Quand cette option est utilisée, la base de données nommée via l'option
-d
est utilisée seulement pour exécuter les commandes
DROP DATABASE
et CREATE DATABASE
.
Toutes les données sont restaurées dans la base dont le nom se trouve
dans l'archive.
-d nom_base
--dbname=nom_base
Se connecte à la base de données nom_base
et restaure directement dans
la base de données. 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.
-e
--exit-on-error
Quitte si une erreur est rencontrée lors de l'envoi des commandes SQL à la base de données. La valeur par défaut est de continuer et d'afficher le nombre d'erreurs à la fin de la restauration.
-f nom_fichier
--file=filename
Spécifie le fichier en sortie pour le script généré ou pour la liste
lorsqu'elle est utilisée avec -l
. Utilisez
-
pour stdout.
-F format
--format=format
Spécifie le format de l'archive. Il n'est pas nécessaire de le spécifier car pg_restore détermine le format automatiquement. Si spécifié, il peut être un des suivants :
c
custom
L'archive est dans le format personnalisé de pg_dump.
d
directory
L'archive est un répertoire (directory).
t
tar
L'archive est une archive tar
.
-I index
--index=index
Restaure uniquement la définition des index nommés. Plusieurs index
peuvent être donnés en utilisant autant de fois l'option
-I
.
-j nombre-de-jobs
--jobs=nombre-de-jobs
Exécute les parties les plus consommatrices en temps de
pg_restore -- celles des chargements de
données, créations d'index et créations de contraintes -- en
parallèle, utilisant jusqu'à nombre-de-jobs
sessions parallèles.
Cette option peut réduire de beaucoup le temps pour restaurer une
grosse base de données pour un serveur fonctionnant sur une machine
multi-processus. Cette option est ignorée lors de la création d'un
script, plutôt que lors d'une connexion directe à un serveur de bases
de données.
Chaque job est un processus ou un thread, suivant le système d'exploitation, et utilise une connexion séparée au serveur.
La valeur optimale pour cette option dépend de la configuration matérielle du serveur, du client et du réseau. Les facteurs incluent le nombre de cœurs CPU et la configuration disque. Un bon moyen pour commencer est le nombre de cœurs CPU du serveur, mais une valeur plus grande que ça peut amener des temps de restauration encore meilleurs dans de nombreux cas. Bien sûr, les valeurs trop hautes apporteront des performances en baisse.
Seuls les formats d'archivage personnalisé et répertoire sont supportés
avec cette option. Le fichier en entrée doit être un fichier standard
(pas un tube, pas l'entrée standard). De plus,
plusieurs jobs ne peuvent pas être utilisés ensemble si vous voulez
l'option --single-transaction
.
-l
--list
Liste le contenu de l'archive. Le résultat de cette opération peut être
utilisé en entrée de l'option -L
. Notez que, si vous
utilisez des options de filtre telles que -n
ou
-t
avec l'option -l
, elles
restreignent les éléments listés.
-L fichier_liste
--use-list=fichier_liste
Restaure seulement les objets qui sont listés dans le fichier
fichier_liste
, et les
restaure dans l'ordre où elles apparaissent dans le fichier. Notez que,
si des options de filtre comme -n
et
-t
sont utilisées avec -L
, elles
ajouteront cette restriction aux éléments restaurés.
fichier_liste
est
normalement créé en éditant la sortie d'une précédente opération
-l
. Les lignes peuvent être déplacées ou supprimées,
et peuvent aussi être mise en commentaire en ajoutant un point-virgule
(;
) au début de la ligne. Voir ci-dessous pour des
exemples.
-n nom_schema
--schema=nom_schema
Restaure seulement les objets qui sont dans le schéma nommé. Plusieurs
schémas peuvent être donnés en utilisant autant de fois l'option
-n
. Elle peut être combinée avec l'option
-t
pour ne restaurer qu'une seule table.
-N nom_schema
--exclude-schema=nom_schema
Ne pas restaurer les objets qui sont dans le schéma nommé. Plusieurs
schémas à exclure peuvent être spécifiés grâce à de multiples
commutateurs -N
.
Si les commutateurs -n
et -N
sont
tous deux présents pour le même schéma, le commutateur
-N
sera prépondérant et le schéma exclu.
-O
--no-owner
Ne pas donner les commandes initialisant les propriétaires des objets
pour correspondre à la base de données originale. Par défaut,
pg_restore lance des instructions
ALTER OWNER
ou SET SESSION
AUTHORIZATION
pour configurer le propriétaire des éléments du
schéma créé. Ces instructions échouent sauf si la connexion initiale à
la base de données est réalisée par un superutilisateur (ou le même
utilisateur que le propriétaire des objets du script). Avec
-O
, tout nom d'utilisateur peut être utilisé pour la
connexion initiale et cet utilisateur est le propriétaire des objets
créés.
-P nom_fonction(argtype [,
...])
--function=nom_fonction(argtype [,
...])
Restaure seulement la fonction nommée. Faites attention à épeler le nom
de la fonction et les arguments exactement comme ils apparaissent dans
la table des matières du fichier de sauvegarde. Plusieurs fonctions
peuvent être données en utilisant autant de fois l'option
-P
.
-r
--no-reconnect
Cette option est obsolète mais est toujours acceptée pour des raisons de compatibilité ascendante.
-s
--schema-only
Restaure seulement le schéma (autrement dit, la définition des données), mais pas les données, à condition que cette définition est présente dans l'archive.
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.)
-S nom_utilisateur
--superuser=nom_utilisateur
Spécifie le nom d'utilisateur du superutilisateur à utiliser pour
désactiver les triggers. Ceci est seulement nécessaire si
--disable-triggers
est utilisé.
-t table
--table=table
Restaure la définition et/ou les données de la table nommée uniquement.
Dans ce cadre, « table » inclut les vues, les vues
matérialisées, les séquences et les tables distantes. Plusieurs tables
peuvent être sélectionnées en ajoutant plusieurs options
-t
. Cette option peut être combinée avec l'option
-n
pour indiquer les tables d'un schéma particulier.
Quand l'option -t
est indiquée,
pg_restore ne tente pas de restaurer les
autres objets de la base de données qui pourraient être liés à la
table sélectionnée. De ce fait, il n'y a aucune garantie qu'une
restauration d'une table spécifique dans une base propre réussira.
Cette option ne se comporte pas de la même façon que l'option
-t
de pg_dump. Il n'existe
pas actuellement de support pour la recherche de motifs dans
pg_restore. De plus, vous ne pouvez pas
inclure un nom de schéma dans -t
. Et, pendant que
l'option -t
de pg_dump
sauvegardera aussi les objets liés (comme les index) des tables
sélectionnées, l'option -t
de
pg_restore n'incluera pas les objets liés.
Dans les versions de PostgreSQL antérieures à la 9.6, cette option correspondant seulement aux tables, pas aux autres types de relation.
-T trigger
--trigger=trigger
Restaure uniquement le trigger nommé. Plusieurs triggers peuvent être
donnés en utilisant autant de fois l'option -T
..
-v
--verbose
Spécifie le mode verbeux. Ceci aura pour conséquence que pg_restore affichera des commentaires détaillés sur les objets, ainsi que les heures de début et de fin dans le fichier en sortie, et des messages de progression sur la sortie des erreurs. Répéter cette option cause l'apparition de messages supplémentaires de débuggage sur la sortie des erreurs.
-V
--version
Affiche la version de pg_restore, puis quitte.
-x
--no-privileges
--no-acl
Empêche la restauration des droits d'accès (commandes grant/revoke).
-1
--single-transaction
Exécute la restauration en une seule transaction (autrement dit, toutes
les commandes de restauration sont placées entre un
BEGIN
et un COMMIT
). Ceci assure
l'utilisateur que soit toutes les commandes réussissent, soit aucun
changement n'est appliqué. Cette option implique
--exit-on-error
.
--disable-triggers
Cette option n'est pertinente que lors d'une restauration des données seules. Elle demande à pg_restore d'exécuter des commandes pour désactiver temporairement les triggers sur les tables cibles pendant que les données sont rechargées. Utilisez ceci si vous avez des vérifications d'intégrité référentielle sur les tables que vous ne voulez pas appeler lors du rechargement des données.
Actuellement, les commandes émises pour
--disable-triggers
doivent être exécutées par un
superutilisateur. Donc, vous devriez aussi spécifier un nom de
superutilisateur avec -S
ou, de préférence, lancer
pg_restore en tant que superutilisateur
PostgreSQL.
--enable-row-security
Cette option n'est adéquate que lors de la restauration du contenu du table disposant de l'option RLS. Par défaut, pg_restore configurera row_security à off, pour s'assurer que toutes les données sont restaurées dans la table. Si l'utilisateur n'a pas les droits nécessaires pour contourner la sécurité au niveau ligne, alors une erreur est levée. Ce paramètre demande à pg_restore de configurer row_security à on, permettant à l'utilisateur d'essayer de restaurer le contenu de la table avec la sécurité au niveau ligne activée. Ceci pourrait échouer si l'utilisateur n'a pas le droit d'insérer des lignes dans la table.
Notez que cette option requiert aussi actuellement que la sauvegarde
soit au format INSERT
car COPY
FROM
n'est pas supportée par la sécurité au niveau ligne.
--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.
--no-comments
Ne génère pas les commande de restauration des commentaires même si l'archive les contient.
--no-data-for-failed-tables
Par défaut, les données de la table sont restaurées même si la commande de création de cette table a échoué (par exemple parce qu'elle existe déjà). Avec cette option, les données de cette table seront ignorées. Ce comportement est utile si la base cible contient déjà des données pour cette table. Par exemple, les tables supplémentaires des extensions de PostgreSQL comme PostGIS pourraient avoir déjà été créées et remplies sur la base cible ; indiquer cette option empêche l'ajout de données dupliquées ou obsolètes.
Cette option est seulement efficace lors de la restauration directe d'une base, pas lors de la réalisation d'une sortie de script SQL.
--no-publications
Ne pas afficher les commandes pour restaurer les publications, même si l'archive les contient.
--no-security-labels
Ne récupère pas les commandes de restauration des labels de sécurité, même si l'archive les contient.
--no-subscriptions
Ne pas afficher les commandes pour restaurer les souscriptions, même si l'archive les contient.
--no-table-access-method
Ne pas afficher les commandes pour sélectionner les méthodes d'accès aux tables. Avec cette option, tous les objets seront créés avec la méthode d'accès par défaut lors de la restauration.
--no-tablespaces
Ne sélectionne pas les tablespaces. Avec cette option, tous les objets seront créés dans le tablespace par défaut lors de la restauration.
--section=nom_section
Restaure 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. Les éléments post-data consistent en la définition des index, triggers, règles et contraintes (autres que les contraintes de vérification). Les éléments pre-data consistent en tous les autres éléments de définition.
--strict-names
Requiert que chaque qualificateur de schéma (-n
/
--schema
) et table (-t
/
--table
) correspond à au moins un schéma/table dans le
fichier de sauvegarde.
--use-set-session-authorization
Affiche les commandes SET SESSION AUTHORIZATION
du
standard SQL à la place des commandes ALTER OWNER
pour déterminer le propriétaire de l'objet. Ceci rend la sauvegarde
plus compatible avec les standards mais, suivant l'historique des
objets dans la sauvegarde, pourrait ne pas restaurer correctement.
-?
--help
Affiche l'aide sur les arguments en ligne de commande de pg_restore, puis quitte.
pg_restore accepte aussi les arguments suivants en ligne de commande pour les paramètres de connexion :
-h hôte
--host=hôte
Spécifie le nom d'hôte de la machine sur lequel le serveur est en cours
d'exécution. Si la valeur commence par un slash, elle est utilisée
comme répertoire du socket de domaine Unix. La valeur par défaut est
prise dans la variable d'environnement PGHOST
, si elle
est initialisée, sinon une connexion socket de domaine Unix est tentée.
-p port
--port=port
Spécifie le port TCP ou l'extension du fichier socket de domaine Unix
sur lequel le serveur écoute les connexions. Par défaut, l'outil
utilise la variable d'environnement PGPORT
, si elle est
configurée, sinon il utilise la valeur indiquée à la compilation.
-U
nom_utilisateur
--username=nom_utilisateur
Se connecte en tant que cet utilisateur
-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_restore à demander un mot de passe avant la connexion à une base de données.
Cette option n'est jamais obligatoire car
pg_restore demandera automatiquement un mot
de passe si le serveur exige une authentification par mot de passe.
Néanmoins, pg_restore perdra une tentative
de connexion pour trouver que le serveur veut un mot de passe. Dans
certains cas, il est préférable d'ajouter l'option -W
pour éviter la tentative de connexion.
--role=nom_rôle
Indique un nom de rôle utilisé pour la restauration. Cette option fait
que pg_restore exécute un SET
ROLE
nom_rôle
après connexion à la base de données. C'est utile quand l'utilisateur
authentifié (indiqué par l'option -U
) n'a pas les
droits demandés par pg_restore, mais peut
devenir le rôle qui a les droits requis. Certaines installations ont une
politique contre la connexion en superutilisateur directement, et
utilisent cette option pour permettre aux restaurations de se faire
sans violer cette règle.
PGHOST
PGOPTIONS
PGPORT
PGUSER
Paramètres de connexion par défaut
PG_COLOR
Indique s'il faut utiliser les couleurs dans les messages de diagnostic.
Les valeurs possibles sont always
,
auto
, never
.
Cet outil, comme la plupart des autres outils
PostgreSQL, utilise aussi les variables
d'environnement supportées par la bibliothèque
libpq (voir Section 34.15).
Néanmoins, il ne lit pas la variable PGDATABASE
quand le nom
d'une base n'est pas fournie.
Quand une connexion directe à la base de données est spécifiée avec
l'option -d
, pg_restore exécute
en interne des instructions SQL. Si vous avez des
problèmes en exécutant pg_restore, assurez-vous
d'être capable de sélectionner des informations à partir de la base de
données en utilisant, par exemple à partir de psql.
De plus, tout paramètre de connexion par défaut et toute variable
d'environnement utilisé par la bibliothèque
libpq s'appliqueront.
Si votre installation dispose d'ajouts locaux à la base de données
template1
, faites attention à charger la sortie de
pg_restore dans une base de données réellement
vide ; sinon, vous avez des risques d'obtenir des erreurs dûes aux
définitions dupliquées des objets ajoutés. Pour créer une base de données
vide sans ajout local, copiez à partir de template0
, et
non pas de template1
, par exemple :
CREATE DATABASE foo WITH TEMPLATE template0;
Les limitations de pg_restore sont détaillées ci-dessous.
Lors de la restauration des données dans une table pré-existante et que
l'option --disable-triggers
est utilisée,
pg_restore émet des commandes pour désactiver
les triggers sur les tables utilisateur avant d'insérer les données,
puis émet les commandes pour les réactiver après l'insertion des
données. Si la restauration est stoppée en plein milieu, les catalogues
système pourraient être abandonnés dans le mauvais état.
pg_restore ne peut pas restaurer les « large
objects » de façon sélective, par exemple seulement ceux d'une table
précisée. Si une archive contient des « large objects », alors tous les
« large objects » seront restaurées (ou aucun s'ils sont exclus avec
l'option -L
, l'option -t
ou encore
d'autres options.
Voir aussi la documentation de pg_dump pour les détails sur les limitations de pg_dump.
Une fois la restauration terminée, il est conseillé de lancer
ANALYZE
sur chaque table restaurée de façon à ce que
l'optimiseur dispose de statistiques utiles. Voir Section 25.1.3 et Section 25.1.6 pour
plus d'informations.
Supposons que nous avons sauvegardé une base nommée
ma_base
dans un fichier de sauvegarde au format
personnalisé :
$
pg_dump -Fc ma_base > ma_base.dump
Pour supprimer la base et la re-créer à partir de la sauvegarde :
$
dropdb ma_base
$
pg_restore -C -d postgres ma_base.dump
La base nommée avec l'option -d
peut être toute base de
données existante dans le cluster ;
pg_restore l'utilise seulement pour exécuter la
commande CREATE DATABASE
pour
ma_base
. Avec -C
, les données sont
toujours restaurées dans le nom de la base qui apparaît dans le fichier de
sauvegarde.
Pour charger la sauvegarde dans une nouvelle base nommée
nouvelle_base
:
$
createdb -T template0 nouvelle_base
$
pg_restore -d nouvelle_base db.dump
Notez que nous n'utilisons pas -C
et que nous nous sommes
connectés directement sur la base à restaurer. De plus, notez que nous
clonons la nouvelle base à partir de template0
et non
pas de template1
, pour s'assurer qu'elle est vide.
Pour réordonner les éléments de la base de données, il est tout d'abord nécessaire de sauvegarder la table des matières de l'archive :
$
pg_restore -l ma_base.dump > ma_base.liste
Le fichier de liste consiste en un en-tête et d'une ligne par élément, par exemple :
; ; Archive created at Mon Sep 14 13:55:39 2009 ; dbname: DBDEMOS ; TOC Entries: 81 ; Compression: 9 ; Dump Version: 1.10-0 ; Format: CUSTOM ; Integer: 4 bytes ; Offset: 8 bytes ; Dumped from database version: 8.3.5 ; Dumped by pg_dump version: 8.3.8 ; ; ; Selected TOC Entries: ; 3; 2615 2200 SCHEMA - public pasha 1861; 0 0 COMMENT - SCHEMA public pasha 1862; 0 0 ACL - public pasha 317; 1247 17715 TYPE public composite pasha 319; 1247 25899 DOMAIN public domain0 pasha
Les points virgules commencent un commentaire et les numéros au début des lignes se réfèrent à l'ID d'archive interne affectée à chaque élément.
Les lignes dans le fichier peuvent être commentées, supprimées et réordonnées. Par exemple :
10; 145433 TABLE map_resolutions postgres ;2; 145344 TABLE species postgres ;4; 145359 TABLE nt_header postgres 6; 145402 TABLE species_records postgres ;8; 145416 TABLE ss_old postgres
peut être utilisé en entrée de pg_restore et ne restaure que les éléments 10 et 6 dans cet ordre :
$
pg_restore -L mabase.liste mabase.fichier