9.26. Fonctions d'administration syst�me

Le Tableau 9.57, � Fonctions agissant sur les param�tres de configuration � affiche les fonctions disponibles pour consulter et modifier les param�tres de configuration en exécution.

La fonction current_setting renvoie la valeur courante du param�tre nom_param�tre. Elle correspond � la commande SQL SHOW. Par exemple :

SELECT current_setting('datestyle');

 current_setting
-----------------
ISO, MDY
(1 row)

set_config positionne le param�tre nom_param�tre � nouvelle_valeur. Si est_local vaut true, la nouvelle valeur s'applique uniquement � la transaction en cours. Si la nouvelle valeur doit s'appliquer � la session en cours, on utilise false. La fonction correspond � la commande SQL SET. Par exemple :

SELECT set_config('log_statement_stats', 'off', false);

 set_config
------------
off
(1 row)

Les fonctions présentées dans le Tableau 9.58, � Fonctions d'envoi de signal au serveur � envoient des signaux de contr�le aux autres processus serveur. L'utilisation de ces fonctions est habituellement restreinte aux superutilisateurs, sauf dans certains cas spécifiquement notés.

Ces fonctions renvoient true en cas de succ�s, false en cas d'échec.

pg_cancel_backend et pg_terminate_backend envoie un signal (respectivement SIGINT ou SIGTERM) au processus serveur identifié par l'ID du processus. L'identifiant du processus serveur actif peut �tre trouvé dans la colonne pid dans la vue pg_stat_activity ou en listant les processus postgres sur le serveur avec ps sur Unix ou le Gestionnaire des t�ches sur Windows™. Le r�le d'un processus serveur actif est récupérable � partir de la colonne usename de la vue pg_stat_activity.

pg_reload_conf envoie un signal SIGHUP au serveur, ce qui impose le rechargement des fichiers de configuration par tous les processus serveur.

pg_rotate_logfile signale au gestionnaire de journaux de trace de basculer immédiatement vers un nouveau fichier de sortie. Cela ne fonctionne que lorsque le collecteur de traces interne est actif, puisqu'il n'y a pas de sous-processus de gestion des fichiers journaux dans le cas contraire.

Les fonctions présentées dans le Tableau 9.59, � Fonctions de contr�le de la sauvegarde � aident � l'exécution de sauvegardes � chaud. Ces fonctions ne peuvent pas �tre exécutées lors d'une restauration (sauf pg_xlog_location_diff).

pg_start_backup accepte un label utilisateur de la sauvegarde (typiquement, le nom du fichier d'enregistrement de la sauvegarde). La fonction écrit un fichier de label (backup_label) dans le répertoire de données du cluster, réalise un point de retournement, et renvoie la position du début de la sauvegarde dans le journal de transactions au format texte. Ce résultat ne nécessite pas qu'on s'y intéresse, mais il est fourni dans cette éventualité.

postgres=# select pg_start_backup('le_label_ici');
 pg_start_backup
-----------------
 0/D4445B8
(1 row)

Il existe un second param�tre booléen optionnel. Si true, il précise l'exécution de pg_start_backup aussi rapidement que possible. Cela force un point de retournement immédiat qui causera un pic dans les opérations d'entrées/sorties, ralentissant toutes les requ�tes exécutées en parall�le.

pg_stop_backup supprime le fichier de label créé par pg_start_backup et crée, � la place, un fichier d'historique dans l'aire de stockage des archives des journaux de transactions. Ce fichier contient le label passé � pg_start_backup, les emplacements de début et de fin des journaux de transactions correspondant � la sauvegarde et les heures de début et de fin de la sauvegarde. La valeur de retour est l'emplacement du journal de la transaction de fin de sauvegarde (de peu d'intér�t, l� encore). Apr�s notification de l'emplacement de fin, le point d'insertion courant du journal de transactions est automatiquement avancé au prochain journal de transactions, de fa�on � ce que le journal de transactions de fin de sauvegarde puisse �tre archivé immédiatement pour terminer la sauvegarde.

pg_switch_xlog bascule sur le prochain journal de transactions, ce qui permet d'archiver le journal courant (en supposant que l'archivage continu soit utilisé). La fonction retourne l'emplacement de la transaction finale + 1 dans le journal ainsi terminé. S'il n'y a pas eu d'activité dans les journaux de transactions depuis le dernier changement de journal, pg_switch_xlog ne fait rien et renvoie l'emplacement de fin du journal de transactions en cours.

pg_create_restore_point crée un enregistrement dans les journaux de transactions, pouvant �tre utilisé comme une cible de restauration, et renvoie l'emplacement correspondant dans les journaux de transactions. Le nom donné peut ensuite �tre utilisé avec recovery_target_name pour spécifier la fin de la restauration. �vitez de créer plusieurs points de restauration ayant le m�me nom car la restauration s'arr�tera au premier nom qui correspond � la cible de restauration.

pg_current_xlog_location affiche la position d'écriture du journal de transactions en cours dans le m�me format que celui utilisé dans les fonctions ci-dessus. De fa�on similaire, pg_current_xlog_insert_location affiche le point d'insertion dans le journal de transactions courant. Le point d'insertion est la fin � logique � du journal de transactions � tout instant alors que l'emplacement d'écriture est la fin de ce qui a déj� été écrit � partir des tampons internes du serveur. La position d'écriture est la fin de ce qui peut �tre examiné extérieurement au serveur. C'est habituellement l'information nécessaire � qui souhaite archiver des journaux de transactions partiels. Le point d'insertion n'est donné principalement que pour des raisons de débogage du serveur. Il s'agit l� d'opérations de lecture seule qui ne nécessitent pas de droits superutilisateur.

pg_xlogfile_name_offset peut �tre utilisée pour extraire le nom du journal de transactions correspondant et le décalage en octets � partir du résultat de n'importe quelle fonction ci-dessus. Par exemple :

postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
        file_name         | file_offset 
--------------------------+-------------
 00000001000000000000000D |     4039624
(1 row)

De fa�on similaire, pg_xlogfile_name n'extrait que le nom du journal de la transaction. Quand la position dans le journal de la transaction donnée est exactement sur une limite de journal, les deux fonctions renvoient le nom du journal précédent. C'est généralement le comportement souhaité pour gérer l'archivage des journaux, car le fichier précédent est le dernier � devoir �tre archivé.

pg_xlog_location_diff calcule la différence en octets entre deux emplacements dans les journaux de transactions. Cette fonction peut �tre utilisée avec pg_stat_replication ou avec les fonctions indiquées dans Tableau 9.59, � Fonctions de contr�le de la sauvegarde � pour obtenir le retard de la réplication.

Pour les détails sur le bon usage de ces fonctions, voir la Section 24.3, � Archivage continu et récupération d'un instantané (PITR) �.

Les fonctions affichées dans Tableau 9.60, � Fonctions d'information sur la restauration � fournissent des informations sur le statut actuel du serveur en attente. Ces fonctions peuvent �tre utilisées lors d'une restauration mais aussi lors d'un fonctionnement normal.

Les fonctions affichées dans Tableau 9.61, � Fonctions de contr�le de la restauration � contr�lent la progression de la restauration. Ces fonctions sont seulement exécutables pendant la restauration.

Quand la restauration est en pause, aucune modification de la base n'est appliquée. Si le serveur se trouve en Hot Standby, toutes les nouvelles requ�tes verront la m�me image cohérente de la base et aucun conflit de requ�tes ne sera rapporté jusqu'� la remise en route de la restauration.

Si la réplication en flux est désactivée, l'état pause peut continuer indéfiniment sans probl�me. Si elle est activée, les enregistrements des journaux continueront � �tre re�us, ce qui peut éventuellement finir par remplir l'espace disque disponible, suivant la durée de la pause, le taux de génération des journaux et l'espace disque disponible.

PostgreSQL™ permet aux sessions de la base de synchroniser leur vue de la base (appelée aussi image ou snapshot). Le snapshot détermine les données visibles pour la transaction qui utilise le snapshot. Les snapshots synchronisés sont nécessaires quand deux sessions ou plus ont besoin de voir un contenu identique dans la base. Si deux sessions commencent leur transactions indépendamment, il existe toujours une possibilité pour qu'une troisi�me transaction enregistre des données entre l'exécution des deux commandes START TRANSACTION, ce qui aurait pour conséquence qu'une des transactions verrait les effets de cet enregistrement et pas la deuxi�me.

Pour résoudre ce probl�me, PostgreSQL™ permet � une transaction d'exporter le snapshot qu'elle utilise. Aussi longtemps que la transaction reste ouverte, les autres transactions peuvent importer son snapshot et ont ainsi la garantie qu'elles voient exactement les m�mes données que la transaction qui a fait l'export. Notez cependant que toute modification réalisée par une de ses transactions restera invisible aux autres transactions, ce qui est le comportement standard des transactions non validées. Donc les transactions sont synchronisées pour ce qui concernent les données pré-existantes, mais agissent normalement pour les modifications qu'elles font.

Les snapshots sont exportés avec la fonction pg_export_snapshot, montrée dansTableau 9.62, � Fonction de synchronisation de snapshot �, et importés avec la commande SET TRANSACTION(7).

La fonction pg_export_snapshot sauvegarde le snapshot courant et renvoie une cha�ne de type text identifiant le snapshot. Cette cha�ne doit �tre passée (en dehors de la base de données) aux clients qui souhaitent importer le snapshot. Ce dernier est disponible en import jusqu'� la fin de la transaction qui l'a exporté. Une transaction peut exporter plus d'un snapshot si nécessaire. Notez que ceci n'est utile que dans le mode d'isolation READ COMMITTED car, dans le mode REPEATABLE READ et les niveaux d'isolation plus importants, les transactions utilisent le m�me snapshot tout au long de leur vie. Une fois qu'une transaction a exporté des snapshots, il ne peut plus �tre préparé avec PREPARE TRANSACTION(7).

Voir SET TRANSACTION(7) pour des détails sur l'utilisation d'un snapshot exporté.

Les fonctions présentées dans le Tableau 9.63, � Fonctions de calcul de la taille des objets de la base de données � calculent l'utilisation de l'espace disque par les objets de la base de données.

pg_column_size affiche l'espace utilisé pour stocker toute valeur individuelle.

pg_total_relation_size accepte en argument l'OID ou le nom d'une table ou d'une table TOAST. Elle renvoie l'espace disque total utilisé par cette table, incluant les index associés. Cette fonction est équivalente � pg_table_size + pg_indexes_size.

pg_table_size accepte en argument l'OID ou le nom d'une table et renvoie l'espace disque nécessaire pour cette table, � l'exclusion des index (espace des données TOAST, carte des espaces libres et carte de visibilité inclus.)

pg_indexes_size accepte en argument l'OID ou le nom d'une table et renvoie l'espace disque total utilisé par tous les index attachés � cette table.

pg_database_size et pg_tablespace_size acceptent l'OID ou le nom d'une base de données ou d'un tablespace et renvoient l'espace disque total utilisé.

pg_relation_size accepte l'OID ou le nom d'une table, d'un index ou d'une table toast et renvoie la taille sur disque en octets. Indiquer 'main' ou laisser le second argument renvoie la taille du morceau de données principal de la relation. Indiquer 'fsm' renvoie la taille de la carte des espaces libres (voir Section 56.3, � Carte des espaces libres �) associée � cette relation. Indiquer 'vm' renvoie la taille de la carte de visibilité (voir Section 56.4, � Carte de visibilité �) associée avec la relation. Notez que cette fonction affiche la taille d'un seul fichier ; dans la plupart des cas, c'est plus simple � utiliser que les fonctions de haut-niveau comme pg_total_relation_size ou pg_table_size.

pg_size_pretty peut �tre utilisé pour formater le résultat d'une des autres fonctions de fa�on interprétable par l'utilisateur, en utilisant kB, MB, GB ou TB suivant le cas.

Les fonctions ci-dessus qui op�rent sur des tables ou des index acceptent un argument regclass, qui est simplement l'OID de la table ou de l'index dans le catalogue syst�me pg_class. Vous n'avez pas � rechercher l'OID manuellement. Néanmoins, le convertisseur de type de données regclass fera ce travail pour vous. �crivez simplement le nom de la table entre guillements simples pour qu'il ressemble � une constante littérale. Pour compatibilité avec la gestion des noms SQL standards, la cha�ne sera convertie en minuscule sauf si elle est entourée de guillemets doubles.

Si un OID qui ne représente pas un objet existant est passé en tant qu'argument � une des fonctions ci-dessus, NULL est renvoyé.

Les fonctions affichées dans Tableau 9.64, � Fonctions de récupération de l'emplacement des objets de la base de données � facilitent l'identification des fichiers associées aux objets de la base de données.

pg_relation_filenode accepte l'OID ou le nom d'une table, d'un index, d'une séquence ou d'une table TOAST. Elle renvoie le numéro � filenode � qui lui est affecté. Ce numéro est le composant de base du nom de fichier utilisé par la relation (voir Section 56.1, � Emplacement des fichiers de la base de données � pour plus d'informations). Pour la plupart des tables, le résultat est identique � pg_class.relfilenode mais pour certains catalogues syst�me, relfilenode vaut zéro et cette fonction doit �tre utilisée pour obtenir la bonne valeur. La fonction renvoie NULL si l'objet qui lui est fourni est une relation qui n'a pas de stockage, par exemple une vue.

pg_relation_filepath est similaire � pg_relation_filenode mais elle renvoie le chemin complet vers le fichier (relatif au répertoire des données de l'instance, PGDATA) de la relation.

Les fonctions présentées dans le Section 9.26.7, � Fonctions génériques d'acc�s aux fichiers � fournissent un acc�s natif aux fichiers situés sur le serveur. Seuls les fichiers contenus dans le répertoire du cluster et ceux du répertoire log_directory sont accessibles. On utilise un chemin relatif pour les fichiers contenus dans le répertoire du cluster et un chemin correspondant � la configuration du param�tre log_directory pour les journaux de trace. L'utilisation de ces fonctions est restreinte aux superutilisateurs.

pg_ls_dir renvoie tous les noms contenus dans le répertoire indiqué, � l'exception des entrées spéciales � . � et � .. �.

pg_read_file renvoie une partie d'un fichier texte, débutant au décalage indiqué, renvoyant au plus longueur octets (moins si la fin du fichier est atteinte avant). Si le décalage est négatif, il est relatif � la fin du fichier. Si offset et length sont omis, le fichier entier est renvoyé. Les octets lus � partir de ce fichier sont interprétés comme une cha�ne dans l'encodage du serveur. Une erreur est affichée si l'encodage est mauvais.

pg_read_binary_file est similaire � pg_read_file, sauf que le résultat est une valeur de type bytea ; du coup, aucune vérification d'encodage n'est réalisée. Avec la fonction convert_from, cette fonction peut �tre utilisée pour lire un fichier dans un encodage spécifié :

SELECT convert_from(pg_read_binary_file('fichier_en_utf8.txt'), 'UTF8');

pg_stat_file renvoie un enregistrement contenant la taille du fichier, les date et heure de dernier acc�s, les date et heure de derni�re modification, les date et heure de dernier changement de statut (plateformes Unix seulement), les date et heure de création (Windows seulement) et un booléen indiquant s'il s'agit d'un répertoire. Les usages habituels incluent :

SELECT * FROM pg_stat_file('nomfichier');
SELECT (pg_stat_file('nomfichier')).modification;

Les fonctions présentées dans Tableau 9.66, � Fonctions de verrous consultatifs � g�rent les verrous consultatifs. Pour les détails sur le bon usage de ces fonctions, voir Section 13.3.4, � Verrous informatifs �.

pg_advisory_lock verrouille une ressource applicative qui peut �tre identifiée soit par une valeur de clé sur 64 bits soit par deux valeurs de clé sur 32 bits (les deux espaces de clé ne se surchargent pas). Si une autre session détient déj� un verrou sur le m�me identifiant de ressource, la fonction attend que la ressource devienne disponible. Le verrou est exclusif. Les demandes de verrou s'empilent de sorte que, si une m�me ressource est verrouillée trois fois, elle doit �tre déverrouillée trois fois pour �tre disponible par les autres sessions.

pg_advisory_lock_shared fonctionne de fa�on identique � pg_advisory_lock sauf que le verrou peut �tre partagé avec d'autres sessions qui réclament des verrous partagés. Seules les demandes de verrou exclusif sont bloquées.

pg_try_advisory_lock est similaire � pg_advisory_lock sauf que la fonction n'attend pas la disponibilité du verrou. Si le verrou peut �tre obtenu immédiatement, la fonction renvoie true, sinon, elle renvoie false.

pg_try_advisory_lock_shared fonctionne de la m�me fa�on que pg_try_advisory_lock sauf qu'elle tente d'acquérir un verrou partagé au lieu d'un verrou exclusif.

pg_advisory_unlock rel�che un verrou consultatif exclusif précédemment acquis au niveau session. Elle retourne true si le verrou est relaché avec succ�s. Si le verrou n'était pas détenu, false est renvoyé et un message d'avertissement SQL est émis par le serveur.

pg_advisory_unlock_shared fonctionne de la m�me fa�on que pg_advisory_unlock mais pour rel�cher un verrou partagé au niveau session.

pg_advisory_unlock_all rel�che tous les verrous consultatifs au niveau session détenus par la session courante. (Cette fonction est appelée implicitement � la fin de la session, m�me si le client se déconnecte brutalement.)

pg_advisory_xact_lock fonctionne de la m�me fa�on que pg_advisory_lock, sauf que le verrou est automatiquement rel�ché � la fin de la transaction courante et ne peut pas �tre rel�ché de fa�on explicite.

pg_advisory_xact_lock_shared fonctionne de la m�me fa�on que pg_advisory_lock_shared, sauf que le verrou est automatiquement rel�ché � la fin de la transaction courante et ne peut pas �tre rel�ché de fa�on explicite.

pg_try_advisory_xact_lock fonctionne de la m�me fa�on que pg_try_advisory_lock, sauf que le verrou, s'il est acquis, est automatiquement rel�ché � la fin de la transaction courante et ne peut pas �tre rel�ché de fa�on explicite.

pg_try_advisory_xact_lock_shared fonctionne de la m�me fa�on que pg_try_advisory_lock_shared, sauf que le verrou, s'il est acquis, est automatiquement rel�ché � la fin de la transaction courante et ne peut pas �tre rel�ché de fa�on explicite.