PostgreSQLLa base de données la plus sophistiquée au monde.

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_connexion...] [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é, 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.

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.

c, custom

L'archive est dans le format personnalisé de pg_dump.

-i, --ignore-version

Une option obsolète qui est maintenant ignorée.

-I index, --index=index

Restaure uniquement la définition des index nommés.

-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 utilisant plusieurs jobs concurrents. 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-processeus.

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.

Seul le format d'archivage personnalisé est supporté avec cette option. Le fichier en entrée doit être un fichier standard (pas un tube par exemple). Cette option est ignorée lors de la création d'un script plutôt qu'une connexion à la base de données. 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é. 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.

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

-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. Ceci est combinable avec l'option -n pour spécifier un schéma.

-T trigger, --trigger=trigger

Restaure uniquement le déclencheur nommé.

-v, --verbose

Spécifie le mode verbeux.

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

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

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

-?, --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. Certains installations ont une politique contre la connexion en super-utilisateur directement, et utilisent cette option pour permettre aux restaurations de se faire sans violer cette règle.

Environnement

PGHOST, PGOPTIONS, 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 31.13, « 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 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(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 ; voir Section 23.1.3, « Maintenir les statistiques du planificateur » et Section 23.1.5, « Le démon auto-vacuum » pour plus d'informations.

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

Voir aussi

pg_dump(1), pg_dumpall(1), psql(1)