pg_restore
pg_restore — restaure une base de données PostgreSQL™ à partir d'un fichier
d'archive créé par pg_dump
Synopsis
pg_restore [
option
...] [
nom_fichier
]
Description
pg_restore est un outil pour
restaurer une base de données PostgreSQL™ à partir d'une archive créée
par
pg_dump(1) 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é, l'archive est
restaurée 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
.
Options
pg_restore accepte les arguments
suivants en ligne de commande.
-
nom_fichier
-
Spécifie l'emplacement du fichier d'archive à 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).
-
-c,
--clean
-
Nettoie (supprime) les objets de la base de données avant de
les créer.
-
-C,
--create
-
Crée la base de données avant de la restaurer. (Quand cette
option est utilisée, la base de données nommée avec
-d est utilisée seulement pour lancer
la commande initiale
CREATE
DATABASE
. Toutes les données sont restaurées
dans le nom de la base de données qui apparaît 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.
-
-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. Par défaut, il s'agit de la sortie
standard.
-
-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 :
-
t,
tar
-
L'archive est une archive
tar
. Utiliser ce
format d'archive permet le réordonnancement et/ou
l'exclusion d'éléments de schéma au moment de la
restauration de la base de données. Il est aussi
possible de limiter les données à recharger au moment
de la restauration.
-
c,
custom
-
L'archive est dans le format personnalisé de
pg_dump. Ceci est le
format le plus flexible dans le fait qu'il permet le
réordonnancement du chargement des données ainsi que
des éléments de schéma. Ce format est aussi compressé
par défaut.
-
-i,
--ignore-version
-
Ignore la vérification de version de la base de données.
-
-I
index
,
--index=
index
-
Restaure uniquement la définition des index nommés.
-
-l,
--list
-
Liste le contenu de l'archive. La sortie de cette opération
peut être utilisée avec l'option -L
pour restreindre et réordonner les éléments à restaurer.
-
-L
fichier_liste
,
--use-list=
fichier_liste
-
Restaure seulement les éléments dans
fichier_liste
et dans leur ordre
d'apparition dans le fichier. Les lignes peuvent être
déplacées et peuvent aussi être commentées en plaçant un
; au début de la ligne. (Voir les
exemples ci-dessous.)
-
-n
nom_schema
,
--schema=
nom_schema
-
Restaure seulement les objets qui sont dans le schéma nommé.
Elle peut être combinée avec l'option -t pour ne restaurer qu'une seule table.
-
-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.
-
-r,
--no-reconnect
-
Cette option est obsolète mais est toujours acceptée pour des
raisons de compatibilité ascendante.
-
-s,
--schema-only
-
Restaure uniquement le schéma (définition des données), et
non pas les données elles-même (contenu de la table). Les
valeurs actuelles des séquences ne seront pas restaurées. À
ne pas confondre avec l'option --schema qui utilise le mot schéma avec une
autre signification).
-
-S
nom_utilisateur
,
--superuser=
nom_utilisateur
-
Spécifie le nom d'utilisateur du superutilisateur à utiliser
pour désactiver les déclencheurs. Ceci est seulement
nécessaire si --disable-triggers est
utilisé.
-
-t
table
,
--table=
table
-
Restaure uniquement la définition et/ou les données de la
table nommée.
-
-T
trigger
,
--trigger=
trigger
-
Restaure uniquement le déclencheur nommé.
-
-v,
--verbose
-
Spécifie le mode verbeux.
-
-x,
--no-privileges,
--no-acl
-
Empêche la restauration des droits d'accès (commandes
grant/revoke).
-
--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 déclencheurs 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™.
-
--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 restaurer correctement.
-
--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 quand
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.
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
-
Se connecte en tant que cet utilisateur
-
-W
-
Force une demande de mot de passe. Ceci devrait arriver
automatiquement si le serveur requiert une authentification
par mot de passe.
-
-1,
--single-transaction
-
Exécute la restauration en une seule transaction
(c'est-à-dire qu'elle entoure les commandes de restauration
par les commandes
BEGIN
/
COMMIT
). Ceci vous assure
que soit toutes les commandes terminent avec succès soit
aucune modification n'a lieu. Cette option implique
--exit-on-error.
Environnement
-
PGHOST,
PGPORT,
PGUSER
-
Paramètres de connexion par défaut
Cet outil, comme la plupart des autres outils PostgreSQL™, utilise aussi les variables
d'environnement supportées par la bibliothèque libpq (voir Section 29.12,
« Variables d'environnement »).
Diagnostiques
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(1). De plus, tout paramètre de connexion
par défaut et toute variable d'environnement utilisé par la
bibliothèque libpq s'appliqueront.
Notes
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 déclencheurs 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 restaure pas
les objets larges pour une seule table. Si une archive
contient des objets larges, alors ils sont tous restaurés.
Voir aussi la documentation de
pg_dump(1) 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.
Exemples
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 newdb
$ pg_restore -d newdb 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 Fri Jul 28 22:28:36 2000
; dbname: ma_base
; TOC Entries: 74
; Compression: 0
; Dump Version: 1.4-0
; Format: CUSTOM
;
;
; Selected TOC Entries:
;
2; 145344 TABLE species postgres
3; 145344 ACL species
4; 145359 TABLE nt_header postgres
5; 145359 ACL nt_header
6; 145402 TABLE species_records postgres
7; 145402 ACL species_records
8; 145416 TABLE ss_old postgres
9; 145416 ACL ss_old
10; 145433 TABLE map_resolutions postgres
11; 145433 ACL map_resolutions
12; 145443 TABLE hs_old postgres
13; 145443 ACL hs_old
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
Historique
L'outil pg_restore est apparu dans
PostgreSQL™ version 7.1.
pg_dumpall
