pg_restore

Documentation PostgreSQL 7.4.29
Précédent	Arrière rapide		Avance rapide	Suivant

Description

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 lancera 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 avant d'être restauré. Les fichiers d'archive sont conçus pour être portables au travers des 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. (Les gros objets peuvent seulement être restaurés en utilisant une connexion directe à 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), similaire à ceux créés par le format en texte plein de pg_dump. Quelques-unes des options contrôlant la sortie du script 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 suivant 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 le schéma (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.

-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éterminera le format automatiquement. Si spécifié, il peut être un des suivants :

t: L'archive est une archive tar. Utiliser ce format d'archive permet le réordonnancement et/ou l'exclusion des éléments du 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: 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 du 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 pourraient aussi être commentées en plaçant un ; au début de la ligne. (Voir ci-dessous pour des exemples.)

-N --orig-order

Restaure les éléments dans l'ordre où ils ont été générés au départ avec pg_dump. Cette option n'a pas d'utilisation pratique connue car pg_dump génère les éléments dans l'ordre qui l'arrange, ce qui a peu de chances d'être le bon ordre pour les restaurer. (Ce n'est pas l'ordre dans lequel les éléments sont listés dans la table des matières de l'archive.) Voir aussi -r.

-o --oid-order

Restaure les éléments dans l'ordre des OID. Cette option a une utilité limitée car les OID sont seulement une indication approximative de l'ordre de création originale. Cette option surcharge -N si les deux sont spécifiés. Voir aussi -r.

-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 SET SESSION AUTHORIZATION pour configurer le propriétaire des éléments du schéma créé. Ces instructions échoueront 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 sera 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 --rearrange

Réarrange les éléments par type d'objet (ceci survient après le tri spécifié par -N ou -o, au cas où ils seraient indiqués). Le réarrangement a pour but de donner les meilleures performances pour la restauration.

Quand aucune des options -N, -o et -r n'apparaisse, pg_restore restaure les éléments dans l'ordre où ils apparaissent dans la table des matières de la sauvegarde ou dans l'ordre où ils apparaissent dans le fichier_liste si -L est spécifié. La combinaison de -o et -r duplique le tri effectué par pg_dump avant de créer la table des matières de la sauvegarde. Du coup, il n'est normalement pas nécessaire de le spécifier.

-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. Les valeurs de séquence seront réinitialisées.

-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).

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

Cette option est obsolète mais est toujours acceptée pour des raisons de compatibilité ascendante. pg_restore se comporte maintenant toujours de la façon précédemment sélectionnée par cette option.

-X disable-triggers --disable-triggers

Cette option est seulement intéressante lors de l'unique restauration des données. Elle demande à pg_restore d'exécuter des commandes pour désactiver temporairement les déclencheurs sur les tables cibles pendant que la donnée est rechargée. 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.

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 de l'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 elle utilise la valeur compilée.
-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.

Environnement

PGHOST PGPORT PGUSER: Paramètres de connexion par défaut

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 l'information à partir de la base de données utilisée, par exemple à partir de psql.

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 un mauvais état.
pg_restore ne restaurera pas les objets larges pour une seule table. Si une archive contient des objets larges, alors ils seront restaurés.

Voir aussi la documentation de pg_dump pour les détails sur les limitations de pg_dump.

Une fois restaurée, il est conseillé de lancer ANALYZE sur chaque table restaurée de façon à ce que l'optimiseur dispose de statistiques utiles.

Exemples

Pour sauvegarder une base de données appelée ma_base, contenant des objets larges dans un fichier tar :

$ pg_dump -Ft -b ma_base > base.tar

Pour recharger cette base de données (avec les objets larges) dans une base de données existante appelée nouvelle_base :

$ pg_restore -d nouvelle_base base.tar

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 archive.fichier > archive.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: birds
;     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

pourrait être utilisé en entrée de pg_restore et pourrait seulement restaurer les éléments 10 et 6 dans cet ordre :

$ pg_restore -L archive.liste archive.fichier

Historique

L'outil pg_restore est d'abord apparu dans PostgreSQL, version 7.1.

Voir aussi

pg_dump, pg_dumpall, psql