Name
pg_restore -- restaure une base
PostgreSQL depuis un fichier
archive créé par pg_dump
Synopsis
pg_restore [ -a ] [ -c ] [ -C ] [ -d dbname ] [ -f output-file ] [ -F format ] [ -i index ] [ -l ] [ -L contents-file ] [ -N | -o | -r ] [ -O ] [ -P function-name ] [ -R ] [ -s ] [ -S ] [ -t table ] [ -T trigger ] [ -v ] [ -x ] [ -X keyword] [ -h host ] [ -p port ] [ -U username ] [ -W ] [ archive-file ]
Description
pg_restore est un utilitaire pour restaurer une base
PostgreSQL sepuis une archive créée par
pg_dump
(1) dans un des formats non texte.
Il générera les commandes nécessaires pour régénérer tous les types
utilisateurs, fonctions, tables, indexes, agrégats, et opérateurs,
aussi bien que les données dans les tables.
Les fichiers archives contiennent l'information pour
pg_restore pour reconstruire la base, mais aussi
permet à pg_restore de sélectionner ce qui sera
restauré, ou même pour réordonnancer les items avant d'être restaurés.
Les fichiers archive seront modélisés pour pouvoir être portables
sur diverses architectures.
pg_restore peut opérer en deux modes : si un nom
de base est spécifié, l'archive est restaurée directement dans la base.
Sinon, un script contenant les commandes SQL nécesasires pour reconstruire
la base est créé (et écrit dans un fichier ou une sortie standard), similaire
à ceux créés par
pg_dump en format texte. Certaines des options
contrôlant la sorite script sont donc analogues aux options de
pg_dump.
Évidemment, pg_restore ne peut restaurer l'information
qui n'est pas présente dans le fichier archive; par exemple, si l'archive
est produite en utilisant l'option "sauvegarde des données comme
INSERT",
pg_restore ne sera pas capable de charger les données
utilisant les instructions COPY.
Options
pg_restore accepte les arguments en ligne de commande
suivants :
(Les options de formes longues ne sont disponibles que sur certaines
plate-formes).
- archive-name
Spécifie l'endroit où le fichier archive sera restauré.
Si non spécifié, l'entrée standard sera utilisée.
- -a, --data-only
Restaure seulement les données, pas le schéma (définitions).
- -c, --clean
Supprime (drop) les objets de la base avant de les recréer.
- -C, --create
Crée la base avant de restaurer dans celle-ci.
(Quand ce commutateur apparaît, la base nommée avec -d
est utilisée seulement pour produire la commande initiale
CREATE DATABASE. Toutes les données sont restaurées dans le nom de base
qui apparaît dans l'archive).
- -d dbname, --dbname=dbname
Connecte à la base dbname et restaure directement dans la base. Les objets longs peut seulement
être restaurés en utilisant une connexion directe à la base.
- -f filename, --file=filename
Spécifie le fichier de sortie pour le script généré, ou pour le
listing quand utilisé avec l'option -l. Par défaut
c'est la sortie standard.
- -F format, --format=format
Spécifie le format de l'archive.
Il n'est pas nécessaire de spécifier le format, car
pg_restore déterminera automatiquement le format.
Si spécifié, il peut être :
- t
L'archive est une archive tar. Utiliser ce
format permet le ré-ordonnancement 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
L'archive est en format spécial de pg_dump. c'est
le format le plus souple en ce qu'il permet le ré-ordonnancement de données
chargées aussi bien qu'éléments de schéma. Ce format est aussi compressé
par défaut.
- -i index, --index=index
Restaure la définition des indexes nommés seulement.
- -l, --list
Liste le contenu de l'archive. La sortie de cette commande
peut être utilisée avec l'option -L
pour restreindre et réordonner les items à restaurer.
- -L list-file, --use-list=list-file
Restaure les éléments dans list-file seulement, et dans l'ordre dans lequel ils apparaissent dans le
fichier.
Les lignes peuvent être déplacées et aussi décommentées en
plaçant un ; au début de la ligne.
- -N, --orig-order
Restaure les items dans l'ordre d'origine de la sauvegarde.
Par défaut pg_dump sauvegardera les items dans un ordre
pratique pour pg_dump, ensuite sauvegarde l'archive
dans un ordre d'OID modifié. Les options outrepassent l'ordonnancement OID.
- -o, --oid-order
Restaure les items dans l'ordre OID. Par défaut pg_dump restaurera les items dans un ordre pratique pour
pg_dump, ensuite sauvegarde l'archive dans un ordre
d'OID modifié. Cette option renforce l'ordonnancement OID strict.
- -O, --no-owner
Évite les tentatives de restauration des droits d'origine
de l'objet. Les objets seront la propriété du nom d'utilisateur qui sert
pour s'attacher à cette base.
- -P function-name, --function=function-name
Spécifie une procédure ou une fonction à restaurer.
- -r, --rearrange
Restaure les items dans un ordre OID modifié. Par défaut pg_dump restaurera les items dans un ordre convenant à
pg_dump, ensuite sauvegarde l'archive dans un ordre
OID modifié. La plupart des objets seront restaurés dans un ordre OID, mais
certaines choses (ex., règles et indexes) seront restaurées à la fin
du processus sans respect pour leurs OID.
C'est l'option par défaut.
- -R, --no-reconnect
Lors de la restauration d'une archive, pg_restore
doit se reconnecter à la base plusieurs fois avec différents noms
d'utilisateurs pour mettre en place les droits corrects des objets créés.
Si ceci n'est pas désiré (ex., à cause des interactions manuelles
(mot-de-passe) qui seraient nécessaires pour chaque reconnexion), cette option
évite à pg_restore d'envoyer des commandes de reconnexion.
(Une requête de connexion en mode texte, non connectée à une base,
est faite par une commande psql(1) \connect).
Cependant, cette option est un peu un instrument émoussé car il fait
que pg_restore perd toute l'information sur les
droits des objets, sauf si vous utilisez l'option
-X use-set-session-authorization.
- -s, --schema-only
Restaure le schéma (définitions), pas les données. Les valeurs
de séquences seront replacées.
- -S username, --superuser=username
Spécifie le nom de superutilisateur à utiliser lors de la désactivation
des déclencheurs et/ou du placement des droits des éléments du schéma.
Par défaut, pg_restore utilisera le nom de
l'utilisateur courant comme superutilisateur.
- -t table, --table=table
Restaure le(s) shcéma/données pour table seulement.
- -T trigger, --trigger=trigger
Restaure la définition du trigger seulement.
- -v, --verbose
Spécifie le mode verbeux.
- -x, --no-privileges, --no-acl
Évite la restauration des droits d'accès (commandes grant/revoke).
- -X use-set-session-authorization, --use-set-session-authorization
Normalement, si la restauration d'une archive nécessite de modifier
l'utilisateur courant de la base (ex., pour placer les bons droits
sur les objets), une nouvelle connexion à la base doit être ouverte,
laquelle requiert une intervention manuelle (ex., mots-de-passe). Si
vous utilisez l'option
-X use-set-session-authorization,
alors pg_restore sera utilisé à la place de la
commande SET SESSION AUTHORIZATION. Celle-ci a le même effet,
mais nécessite que l'utilisateur qui restaure l'archive soit
un superutilisateur de la base. Cette option outrepasse l'option
-R.
pg_restore accepte aussi les arguments en ligne de
commande suivants pour les paramètres de connexion :
- -h host, --host=host
Spécifie le nom d'hôte de la machine sur laquelle le serveur tourne.
Si l'hôte débute avec un slash, il est utilisé comme répertoire
d'un socket de domaine Unix.
- -p port, --port=port
Spécifie le port Internet TCP/IP ou l'extension de fichier socket de
domaine Unix sur lequel le serveur est en attente de connexions.
Le port par défaut est le 5432,
ou la valeur de la variable d'environnement PGPORT
(si elle est placée).
- -U username
Connecte avec le nom d'utilisateur donné.
- -W
Force le prompt de mot-de-passe. Ceci peut se faire automatiquement
si le serveur nécessite une 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_restore ne peut s'attacher au processus
postmaster
sur le port et l'hôte spécifié. Si vous voyez ce message
assurez vous que le serveur tourne sur le bon hôte et que vous avez
spécifié le bon port.
Si votre site utilise un système d'authentification, assurez vous
que vous avez les droits nécessaires pour l'authentification.
 | Quand une connexion directe à la base est spécifiée par l'option -d
pg_restore
exécute en interne les instructions SQL. Si vous avez
des problèmes pour lancer
pg_restore,
assurez vous que vous avez les droits de sélection d'information sur
la base utilisée, par exemple, psql.
|
Notes
Les limitations de pg_restore sont détaillées ci-dessous.
Lors de la restauration de données dans une table, pg_restore emet des requêtes pour désactiver les déclencheurs sur les tables
utilisateur avant d'insérer les données et ensuite emet des requêtes pour les
réactiver après que les données aient été insérées. Si la restauration est
arrêtée au milieu, les catalogues système peuvent être laissés dans cet
état d'erreur.
pg_restore ne restaure pas les objets longs pour une
table unique. Si une archive contient des objets longs, tous ces objets longs
seront restaurés.
Voir la documentation de pg_dump
(1) pour les détails sur
la limitation pg_dump.
Exemples
Pour sauvegarder une base :
Pour recharger cette base :
$ psql -d database -f db.out |
Pour sauvegarder une base appelée mydb contenant des
objets longs vers un 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 |
Pour ré-ordonnancer les items de la base, il est nécessaire en premier de
seuvegarder la table des contenus de l'archive :
$ pg_restore -l archive.file > archive.list |
Le fichier listing consiste en un en-tête et une ligne pour chaque item, ex.
;
; 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 sont des délimiteurs de commentaires, et les chiffre en
début de ligne se réfèrent à l'ID interne de l'archive assigné à chaque item.
Les lignes dans le fichier peuvent être décommentées, supprimées ou
ré-ordonnancé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 |
peuvent être utilisés comme entrée de
pg_restore et
ne restaureront que les items 10 et 6, dans cet ordre.
$ pg_restore -L archive.list archive.file |
Historique
L'utilitaire pg_restore est apparu pour la première fois
dans PostgreSQL 7.1.