9.20. Fonctions d'administration système

Le Tableau 9.45, « Fonctions de paramétrage de configuration » affiche les fonctions disponibles pour connaître ou modifier les paramètres de configuration en exécution.

Tableau 9.45. Fonctions de paramétrage de configuration

Nom Type de retour Description
current_setting (nom_paramètre) text valeur actuelle du paramètre
set_config (nom_paramètre, , nouvelle_valeur, , est_locale) text configure le paramètre et renvoie la nouvelle valeur

La fonction current_setting renvoie la valeur courante du paramètre nom_paramètre. Elle correspond à la commande SQL SHOW. Un exemple :

SELECT current_setting('datestyle');

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

set_config configure le paramètre nom_paramètre avec nouvelle_valeur. Si est_locale vaut true, la nouvelle valeur s'appliquera seulement à la transaction en cours. Si vous voulez que la nouvelle valeur s'applique à la session en cours, utilisez false à la place. La fonction correspond à la commande SQL SET. Un exemple :

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

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

Les fonctions montrées dans le Tableau 9.46, « Fonctions d'envoi de signal aux serveurs » envoient des signaux de contrôle aux autres processus serveur. L'utilisation de ces fonctions est restreinte aux superutilisateurs.

Tableau 9.46. Fonctions d'envoi de signal aux serveurs

Nom Type de retour Description
pg_cancel_backend (pid int) boolean Annule la requête en cours du serveur
pg_reload_conf() boolean Cause le chargement des fichiers de configuration par les processus serveur
pg_rotate_logfile() boolean Demande une rotation du journal des traces du serveur

Chacune de ces fonctions renvoient true en cas de succès, false en cas d'échec.

pg_cancel_backend envoie un signal demandant l'annulation de la requête (SIGINT) à un processus serveur identifié par l'ID du processus. L'identifiant du processus d'un serveur actif peut se trouver à partir de la colonne procpid dans la vue pg_stat_activity ou en listant les processus postgres sur le serveur avec ps.

pg_reload_conf envoie un signal SIGHUP au serveur impliquant un nouveau chargement des fichiers de configuration pour tous les processus serveur.

pg_rotate_logfile signale au gestionnaire de journaux de trace de basculer immédiatement vers un nouveau fichier de sortie. Ceci fonctionne seulement quand redirect_stderr est utilisé pour les traces, sinon il n'y a pas de sous-processus de gestion des traces.

Les fonctions montrées dans le Tableau 9.47, « Fonctions de contrôle de la sauvegarde » aident à l'exécution de sauvegardes à chaud. L'utilisation d'une des trois premières fonctions est restreinte aux superutilisateurs.

Tableau 9.47. Fonctions de contrôle de la sauvegarde

Nom Type de retour Description
pg_start_backup (label text) text Début de la sauvegarde à chaud
pg_stop_backup() text Fin de la sauvegarde à chaud
pg_switch_xlog() text Force le passage à un nouveau journal de transactions
pg_current_xlog_location() text Obtient l'emplacement d'écriture du journal de transactions en cours
pg_current_xlog_insert_location() text Obtient l'emplacement d'insertion du journal de transactions en cours
pg_xlogfile_name_offset(location text) text, integer Convertit la chaîne de l'emplacement du journal de transactions en nom de fichier et le décalage décimal d'octets dans le fichier
pg_xlogfile_name(location text) text Convertit la chaîne de l'emplacement du journal de transactions en nom de fichier

pg_start_backup accepte un seul paramètre qui est un label défini arbitrairement par l'utilisateur pour la sauvegarde (typiquement, cela sera le nom sous lequel le fichier de sauvegarde sera stocké). La fonction écrit un fichier label dans le répertoire de données du groupe, puis renvoie le décalage du journal de transactions de début de sauvegarde au format texte (l'utilisateur n'a pas besoin de faire attention à la valeur du résultat mais il est fourni au cas où il pourrait être utile).

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

pg_stop_backup supprime le fichier label créé par pg_start_backup et crée, à la place, un fichier historique dans l'emplacement des archives des journaux de transactions. Ce fichier inclut le label donné à pg_start_backup, les emplacements de début et de fin des journaux de transactions pour la sauvegarde ainsi que les heures de début et de fin de la sauvegarde. La valeur en retour est l'emplacement du journal de transactions de fin (qui a de nouveau peu d'intérêt). Après avoir noté l'emplacement de fin, le point d'insertion du journal de transactions actuel est automatiquement avancé au prochain journal de transactions, de façon à ce que le journal de transactions en fin de vie puisse être archivé immédiatement pour terminer la sauvegarde.

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

pg_switch_xlog déplace le prochain journal de transactions, permettant l'archivage du journal en cours (en supposant que vous utilisez l'archivage continu). Le résultat est l'emplacement de fin du journal de transaction à l'intérieur du journal de transaction tout juste terminé. S'il n'y a pas eu d'activité dans les journaux de transactions depuis le dernier changement des journaux de transactions, pg_switch_xlog ne fait rien et renvoie l'emplacement de fin du journal de transactions précédent.

pg_current_xlog_location affiche l'emplacement 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 du 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. L'emplacement d'écriture est la fin de ce qui peut être examiné de l'extérieur du serveur et est habituellement ce que vous souhaitez si vous êtes intéressé dans l'archivage des journaux de transactions partiels. Le point d'insertion est rendu disponible principalement pour des raisons de débogage du serveur. Ce sont des opérations de lecture seule et ne nécessitent pas les droits du superutilisateur.

Vous pouvez utiliser pg_xlogfile_name_offset pour extraire le nom du journal de transactions correspondant et le décalage en octets à partir des résultats des fonctions 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 extrait seulement le nom du journal de transactions. Quand l'emplacement du journal de transactions donné est exactement sur une limite du journal de transactions, les deux fonctions renvoient le nom du journal de transactions précédent. C'est généralement le comportement souhaité pour gérer le comportement de l'archivage des journaux de transactions car le fichier précédent est le dernier qui a besoin d'être archivé.

Les fonctions montrées dans le Tableau 9.48, « Fonctions de calcul de 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.

Tableau 9.48. Fonctions de calcul de taille des objets de la base de données

Nom Code de retour Description
pg_column_size(any) int Nombre d'octets utilisé pour stocker une valeur particulière (pouvant être compressée)
pg_database_size(oid) bigint Espace disque utilisé par la base de données dont l'OID est spécifié
pg_database_size(name) bigint Espace disque utilisé par la base de données dont le nom est spécifié
pg_relation_size(oid) bigint Espace disque utilisé par la table ou l'index dont l'OID est spécifié
pg_relation_size(text) bigint Espace disque utilisé par la table ou l'index dont le nom est spécifié. Ce dernier peut être qualifié avec un nom de schéma
pg_size_pretty(bigint) text Convertit une taille en octets en un format lisible par un humain avec des unités de taille
pg_tablespace_size(oid) bigint Espace disque utilisé par le tablespace dont l'OID est indiqué
pg_tablespace_size(name) bigint Espace disque utilisé par le tablespace dont le nom est indiqué
pg_total_relation_size(oid) bigint Espace disque occupé par la table dont l'OID est spécifié, en incluant les index et les données stockées par les tables TOAST
pg_total_relation_size(text) bigint Espace disque total utilisé par la table dont le nom est spécifié, en incluant les index et les données stockées dans les tables TOAST. Le nom de la table peut être qualifié avec un nom de schéma

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

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

pg_size_pretty peut être utilisé pour formater le résultat d'une des autres fonctions d'une façon lisible par un être humain, c'est-à-dire en utilisant kB, MB, GB ou TB lorsque cela est approprié.

pg_total_relation_size accepte l'OID ou le nom d'une table ou d'une table toast, et renvoie la taille en octets des données et de tous les index et tables toast associées.

Les fonctions montrées dans le Tableau 9.49, « Fonctions d'accès générique aux fichiers » fournissent un accès natif aux du serveur. Seuls les fichiers contenus dans le répertoire du groupe de la base de donénes et ceux du répertoire log_directory sont accessibles. Utilisez un chemin relatif pour les fichiers du répertoire du groupe et un chemin correspondant à la configuration du paramètre log_directory pour les journaux de trace. L'utilisation de ces fonctions sont restreintes aux superutilisateurs.

Tableau 9.49. Fonctions d'accès générique aux fichiers

Nom Code de retour Description
pg_ls_dir(nom_répertoire text) setof text Liste le contenu d'un répertoire
pg_read_file(nom_fichier text, décalage bigint, longueur bigint) text renvoie le contenu d'un fichier texte
pg_stat_file(nom_fichier text) record renvoie des informations sur un fichier

pg_ls_dir renvoie tous les noms du répertoire spécifié sauf les 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.

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

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

Les fonctions affichées dans Tableau 9.50, « Fonctions des verrous informatifs » gèrent les verrous informatifs. Pour les détails sur le bon usage de ces fonctions, voir Section 12.3.4, « Verrous informatifs ».

Tableau 9.50. Fonctions des verrous informatifs

Nom Type renvoyé Description
pg_advisory_lock(key bigint) void Obtient un verrou informatif exclusif
pg_advisory_lock(key1 int, key2 int) void Obtient un verrou informatif exclusif
pg_advisory_lock_shared(key bigint) void Obtient un verrou informatif partagé
pg_advisory_lock_shared(key1 int, key2 int) void Obtient un verrou informatif partagé
pg_try_advisory_lock(key bigint) boolean Obtient un verrou informatif exclusif si disponible
pg_try_advisory_lock(key1 int, key2 int) boolean Obtient un verrou informatif exclusif si disponible
pg_try_advisory_lock_shared(key bigint) boolean Obtient un verrou informatif partagé si disponible
pg_try_advisory_lock_shared(key1 int, key2 int) boolean Obtient un verrou informatif partagé si disponible
pg_advisory_unlock(key bigint) boolean Relâche un verrou informatif exclusif
pg_advisory_unlock(key1 int, key2 int) boolean Relâche un verrou informatif exclusif
pg_advisory_unlock_shared(key bigint) boolean Relâche un verrou informatif partagé
pg_advisory_unlock_shared(key1 int, key2 int) boolean Relâche un verrou informatif partagé
pg_advisory_unlock_all() void Relâche tous les verrous informatifs détenus par la session en cours

pg_advisory_lock verrouille une ressource définie par l'application qui peut être identifiée soit par une valeur de clé sur 64 bits soit par deux valeurs de clé sur 32 bits (notez que les deux espaces de clé ne se surchargent pas). Si une autre session détient déjà un verrou sur la même ressource, la fonction attendra jusqu'à ce que la ressource devienne disponible. Le verrou est exclusif. Les demandes de verrous s'empilent pour 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. Seuls les demandes de verrous exclusifs sont bloqués.

pg_try_advisory_lock est similaire à pg_advisory_lock sauf que la fonction n'attendra pas la disponibilité du verrou. Soit il obtiendra le verrou immédiatement et renverra true, soit il ne l'obtiendra pas et il renverra false.

pg_try_advisory_lock_shared fonctionne de la même façon que pg_try_advisory_lock sauf s'il tente d'acquérir un verrou partagé au lieu d'un verrou exclusif.

pg_advisory_unlock lâchera un verrou informatif exclusif précédemment acquis. Il renverra true si le verrou est relaché avec succès. Si le verrou n'était pas détenu, false sera renvoyé. De plus, un message d'avertissement SQL sera émis par le serveur.

pg_advisory_unlock_shared fonctionne de la même façon que pg_advisory_unlock sauf pour relacher un verrou informatif partagé.

pg_advisory_unlock_all relachera tous les verrous informatifs 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 d'une mauvaise façon.)