Documentation PostgreSQL 14.22 » Langage SQL » Fonctions et opérateurs » Fonctions d'administration système

Précédent | Niveau supérieur | Suivant
9.26. Fonctions et opérateurs d'information sur le système | Sommaire | 9.28. Fonctions trigger

## 9.27. Fonctions d'administration système

Les fonctions décrites dans cette section sont utilisées pour contrôler et superviser une installation PostgreSQL.

### 9.27.1. Fonctions de configuration

Tableau 9.85 liste les fonctions disponibles pour requêter et modifier les paramètres de configuration.

Tableau 9.85. Fonctions de configuration

Fonction Description Exemple(s)
`current_setting` ( `setting_name` `text` [, `missing_ok` `boolean` ] ) → `text` Renvoie la valeur actuelle du paramètre `setting_name`. Si ce paramètre n'existe pas, `current_setting` renvoie une erreur sauf si `missing_ok` est renseigné et vaut `true` (auquel cas NULL est renvoyé). Cette fonction correspond à la commande SQL SHOW. `current_setting('datestyle')` → `ISO, MDY`
`set_config` ( `setting_name` `text`, `new_value` `text`, `is_local` `boolean` ) → `text` Configure le paramètre `setting_name` à `new_value`, et renvoie cette valeur. Si `is_local` vaut `true`, la nouvelle valeur s'appliquera uniquement durant la transaction en cours. Si vous voulez que la nouvelle valeur s'applique pour le reste de la session courante, utilisez `false` à la place. Cette fonction correspond à la commande SQL SET. `set_config('log_statement_stats', 'off', false)` → `off`

### 9.27.2. Fonctions d'envoi de signaux

Les fonctions listées dans Tableau 9.86 envoient des signaux de contrôle aux autres processus serveur. L'utilisation de ces fonctions est restreinte aux super-utilisateurs par défaut, mais un accès peut être fourni aux utilisateurs en utilisant la commande `GRANT`, avec quelques exceptions notables.

Chacune de ces fonctions renvoient `true` si le signal a bien été envoyé et `false` si l'envoi du signal a échoué.

Tableau 9.86. Fonctions d'envoi de signaux

Fonction Description
`pg_cancel_backend` ( `pid` `integer` ) → `boolean` Annule la requête en cours de la session du processus serveur dont l'identifiant de processus a été donné. Ceci est aussi autorisé si le rôle appelant est un membre de `pg_signal_backend`. Néanmoins, seuls les super-utilisateurs peuvent annuler les processus des super-utilisateurs.
`pg_log_backend_memory_contexts` ( `pid` `integer` ) → `boolean` Demande le traçage des contextes mémoire du processus dont l'identifiant est spécifié. Ces contextes mémoire seront tracés au niveau `LOG`. Ils apparaîtront dans les traces du serveur selon la configuration (voir Section 20.8 pour plus d'informations), mais ne seront pas envoyés au client, comme indiqué dans client_min_messages. Seul un super-utilisateur peut demander le traçage des contextes mémoire.
`pg_reload_conf` () → `boolean` Cause le rechargement des fichiers de configurations par tous les processus du serveur PostgreSQL. (Ceci se fait en envoyant un signal SIGHUP au processus postmaster qui, à son tour, envoie un signal SIGHUP à chacun de ses processus fils.) Vous pouvez utiliser les vues `pg_file_settings` et `pg_hba_file_rules` pour vérifier d'éventuelles erreurs dans les fichiers de configuration, avant leur rechargement.
`pg_rotate_logfile` () → `boolean` Signale au collecteur de traces qu'il doit changer de fichier de trace immédiatement. Ceci fonctionne seulement quand le collecteur de trace natif est en cours d'exécution.
`pg_terminate_backend` ( `pid` `integer`, `timeout` `bigint` `DEFAULT` `0` ) → `boolean` Termine la session pour le processus serveur dont l'identifiant de processus a été donné. Ceci est aussi autorisé si le rôle appelant est un membre du rôle dont le processus est en cours d'arrêt ou si le rôle appelant est membre de `pg_signal_backend`. Néanmoins, seuls les super-utilisateurs peuvent terminer les processus des super-utilisateurs. Si `timeout` n'est pas précisé ou vaut zéro, cette fonction renvoie `true`, que le processus actuel se termine ou pas, confirmant simplement l'envoi correct du signal. Si `timeout` est précisé (en millisecondes) et que sa valeur est supérieure à zéro, la fonction attend que le processus se termine effectivement ou que le temps soit dépassé. Si le processus est terminé, la fonction retourne `true`. Si le temps est dépassé, un avertissement est émis et la fonction retourne `false`.

`pg_cancel_backend` et `pg_terminate_backend` envoient des signaux (respectivement SIGINT et SIGTERM) aux processus serveurs identifiés par leur PID. Le PID d'un processus serveur actif est disponible dans la colonne `pid` de la vue `pg_stat_activity` ou en listant les processus `postgres` sur le serveur (en utilisant ps sur Unix ou le Task Manager sur Windows). Le rôle d'un processus serveur actif est disponible dans la colonne `usename` de la vue `pg_stat_activity`.

`pg_log_backend_memory_contexts` peut être utilisée pour tracer les contextes mémoires de processus en arrière-plan. Par exemple :

    postgres=# SELECT pg_log_backend_memory_contexts(pg_backend_pid());
     pg_log_backend_memory_contexts
    --------------------------------
     t
    (1 row)

Un message pour chaque contexte mémoire sera tracé. Par exemple :

    LOG:  logging memory contexts of PID 10377
    STATEMENT:  SELECT pg_log_backend_memory_contexts(pg_backend_pid());
    LOG:  level: 0; TopMemoryContext: 80800 total in 6 blocks; 14432 free (5 chunks); 66368 used
    LOG:  level: 1; pgstat TabStatusArray lookup hash table: 8192 total in 1 blocks; 1408 free (0 chunks); 6784 used
    LOG:  level: 1; TopTransactionContext: 8192 total in 1 blocks; 7720 free (1 chunks); 472 used
    LOG:  level: 1; RowDescriptionContext: 8192 total in 1 blocks; 6880 free (0 chunks); 1312 used
    LOG:  level: 1; MessageContext: 16384 total in 2 blocks; 5152 free (0 chunks); 11232 used
    LOG:  level: 1; Operator class cache: 8192 total in 1 blocks; 512 free (0 chunks); 7680 used
    LOG:  level: 1; smgr relation table: 16384 total in 2 blocks; 4544 free (3 chunks); 11840 used
    LOG:  level: 1; TransactionAbortContext: 32768 total in 1 blocks; 32504 free (0 chunks); 264 used
    ...
    LOG:  level: 1; ErrorContext: 8192 total in 1 blocks; 7928 free (3 chunks); 264 used
    LOG:  Grand total: 1651920 bytes in 201 blocks; 622360 free (88 chunks); 1029560 used

S'il y a plus de 100 contextes fils sous le même parent, les 100 premiers contextes fils sont tracés, le reste des contextes étant résumé. Notez que des appels fréquents à cette fonction peut produire une surchage significative, parce qu'elle génère un grand nombre de messages dans les traces.

### 9.27.3. Fonctions de contrôle de la sauvegarde

Les fonctions listées dans Tableau 9.87 aident à la réalisation de sauvegardes en ligne. Ces fonctions ne peuvent pas être exécutées lors de la restauration (sauf pour `pg_start_backup` en mode non exclusif, `pg_stop_backup` en mode non exclusif, `pg_is_in_backup`, `pg_backup_start_time` et `pg_wal_lsn_diff`).

Pour les détails sur l'utilisation correcte de ces fonctions, voir Section 26.3.

Tableau 9.87. Fonctions de contrôle de la sauvegarde

Fonction Description
`pg_create_restore_point` ( `name` `text` ) → `pg_lsn` Crée un enregistrement marqueur nommé dans le journal de transactions. Ce marqueur peut ensuite être utilisé comme cible de restauration et renvoie l'emplacement correspondant dans le journal de transactions. Le nom donné peut être utilisé avec recovery_target_name pour indiquer le point final de restauration. Évitez de créer plusieurs points de restauration de même nom car la restauration s'arrêtera au premier marqueur rencontré dont le nom correspond à la cible de restauration. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_current_wal_flush_lsn` () → `pg_lsn` Renvoie l'emplacement actuel de vidage du journal de transaction (voir les notes ci-dessous).
`pg_current_wal_insert_lsn` () → `pg_lsn` Renvoie l'emplacement actuel d'insertion du journal de transaction (voir les notes ci-dessous).
`pg_current_wal_lsn` () → `pg_lsn` Renvoie l'emplacement actuel d'écriture du journal de transaction (voir les notes ci-dessous).
`pg_start_backup` ( `label` `text` [, `fast` `boolean` [, `exclusive` `boolean` ]] ) → `pg_lsn` Prépare le serveur à commencer une sauvegarde en ligne. Le seul paramètre requi est un label arbitraire défini par l'utilisateur. (Typiquement, ce serait nom sous lequel le fichier de sauvegarde sera stocké.) Si le deuxième paramètre optionnel est donné à `true`, il demande l'exécution aussi rapide que possible de `pg_start_backup`. Ceci force un checkpoint immédiat ce qui va cause un pic dans les opérations disques, ralentissant les requêtes en cours d'exécution. Le troisième paramètre, optionnel, indique s'il faut réaliser une sauvegarde exclusive ou non (par défaut exclusive). Lors d'une sauvegarde exclusive, cette fonction écrit le fichier label (`backup_label`) et, s'il existe des liens dans le répertoire `pg_tblspc/`, un fichier de correspondance des tablespaces (`tablespace_map`) dans le répertoire des données principal de l'instance, puis exécute un checkpoint et enfin renvoie l'emplacement actuel du journal de transactions pour le début de la sauvegarde. (L'utilisateur peut ignorer la valeur en résultat mais elle est fournie au cas où elle serait utile.) Quand il s'agit d'une sauvegarde en mode non exclusif, le contenu de ces fichiers est renvoyé par la fonction `pg_stop_backup` et doit être copié dans l'espace de sauvegarde par l'utilisateur. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_stop_backup` ( `exclusive` `boolean` [, `wait_for_archive` `boolean` ] ) → `setof record` ( `lsn` `pg_lsn`, `labelfile` `text`, `spcmapfile` `text` ) Termine la réalisation d'une sauvegarde en ligne exclusive ou non. Le paramètre `exclusive` doit correspondre à celui du précédent appel à `pg_start_backup`. Pour une sauvegarde exclusive, `pg_stop_backup` supprime le fichier label et, s'il existe, le fichier de correspondance des tablespaces créés par `pg_start_backup`. Pour une sauvegarde non exclusive, le contenu de ces fichiers est renvoyé en résultat de cette fonction et doit être écrit dans des fichiers à placer dans l'espace de sauvegarde (et non pas dans le répertoire des données). Il existe un deuxième paramètre optionnel de type `boolean`. À false, la fonction se terminera immédiatement après la fin de sauvegarde, sans attendre l'archivage des journaux de transactions. Ce comportement est seulement utile pour les logiciels de sauvegarde qui surveillent indépendamment l'archivage des journaux de transactions. Sinon, les journaux requis pour rendre la sauvegarde cohérente pourraient manquer et rendre la sauvegarde inutilisable. Par défaut ou quand ce paramètre vaut true, `pg_stop_backup` attendra l'archivage des journaux de transactions si l'archivage est activé. (Sur un serveur secondaire, cela signifie qu'elle attendra que si `archive_mode` est configuré à `always`. Si l'activité en écriture est faible sur le serveur primaire, il pourrait être utile d'exécuter un `pg_switch_wal` sur le serveur primaire pour forcer un changement de journal.) Lors d'une exécution sur un serveur primaire, cette option crée aussi un fichier d'historique de sauvegarde dans la zone d'archivage des journaux de transactions. Le fichier d'historique inclut un label donné par `pg_start_backup`, les emplacements de début et de fin de la sauvegarde, et les dates et heures de début et de fin de la sauvegarde. Après l'enregistrement de l'emplacement de fin, le point d'insertion actuel dans les journaux de transactions est automatiquement avancé au prochain journal, pour que le journal de fin de sauvegarde soit immédiatement archivé pour terminer la sauvegarde. Le résultat de la fonction est un simple enregistrement. La colonne `lsn` détient l'emplacement de la fin de la sauvegarde dans les journaux de transactions (qui peut de nouveau être ignoré). La deuxième et la troisième colonne valent `NULL` à la fin d'une sauvegarde exclusive ; après une sauvegarde non exclusive, elles contiennent le contenu désiré des fichiers label et de correspondance de tablespaces. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_stop_backup` () → `pg_lsn` Termine la réalisation d'une sauvegarde en ligne exclusive. Cette version simplifiée est équivalente à `pg_stop_backup(true, true)`, sauf qu'elle n'envoie que le résultat de `pg_lsn`. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_is_in_backup` () → `boolean` Renvoie true si une sauvegarde en ligne exclusive est en cours.
`pg_backup_start_time` () → `timestamp with time zone` Renvoie l'heure de début de la sauvegarde en ligne exclusive si une sauvegarde est en cours. Sinon, renvoie `NULL`.
`pg_switch_wal` () → `pg_lsn` Force le serveur à utiliser un nouveau journal de transactions, ce qui permet au journal actuel d'être archivé (en supposant que vous utilisez l'archivage continu). Le résultat est l'emplacement de fin du journal plus 1 dans le journal tout juste terminé. S'il n'y a pas eu d'activité d'écriture depuis le dernier changement de journal, `pg_switch_wal` ne fait rien et renvoie l'emplacement de début du journal actuellement utilisé. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_walfile_name` ( `lsn` `pg_lsn` ) → `text` Convertit un emplacement d'un journal de transaction par le nom du fichier du journal de transaction détenant cet emplacement.
`pg_walfile_name_offset` ( `lsn` `pg_lsn` ) → `record` ( `file_name` `text`, `file_offset` `integer` ) Convertit un emplacement d'un journal de transaction par le nom du fichier du journal de transaction détenant cet emplacement et le décalage en octets pour aller sur cet emplacement.
`pg_wal_lsn_diff` ( `lsn1` `pg_lsn`, `lsn` `pg_lsn2` ) → `numeric` Calcule la différence en octets (`lsn1` - `lsn2`) entre deux emplacements dans les journaux de transactions. Cette fonction peut être utilisée avec `pg_stat_replication` ou certaines des fonctions listées dans Tableau 9.87 pour obtenir le retard de réplication.

`pg_current_wal_lsn` affiche l'emplacement actuel d'écriture dans le journal de transaction en cours, dans le même format que celui utilisé par les fonctions ci-dessus. De même, `pg_current_wal_insert_lsn` affiche l'emplacement d'insertion actuel et `pg_current_wal_flush_lsn` affiche l'emplacement de vidage actuel. L'emplacement d'insertion est la fin « logiqie » du journal de transaction à n'importe quel moment, alors que l'emplacement d'écriture est la fin de ce qui a été réellement écrit à partir des caches internes du serveur, et l'emplacement de vidage est le dernier emplacement connu pour avoir été réellement écrit sur disque. L'emplacement d'écriture est la fin de ce qui doit être examiné en dehors du serveur et est habituellement ce que vous voulez si vous êtes intéressé par l'archivage des journaux partiellement complets. Les emplacements d'insertion et de vidage sont rendus disponibles principalement dans un but de débogage. Ce sont des opérations de lecture seule et ne nécessite pas l'attribut super-utilisateur.

Vous pouvez utiliser `pg_walfile_name_offset` pour extrait le nom du fichier et le décalage en octet du journal de transaction correspondant à partir d'une valeur `pg_lsn`. Par exemple :

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

De la même façon, `pg_walfile_name` extrait juste le nom du fichier du journal de transactions. Quand l'emplacement donné est exactement à la limite du fichier, ces deux fonctions renvoient le nom du journal précédent. Ceci est généralement le comportement souhaité pour gérer l'archivage car le fichier précédent est le dernier qui doit être archivé.

### 9.27.4. Fonctions de contrôle de la restauration

Les fonctions listées dans Tableau 9.88 fournissent des informations sur le statut actuel d'un serveur secondaire. Ces fonctions peuvent être exécutées pendant une restauration et pendant une exécution normale.

Tableau 9.88. Fonctions d'information sur la restauration

Fonction Description
`pg_is_in_recovery` () → `boolean` Renvoie true si la restauration est toujours en cours.
`pg_last_wal_receive_lsn` () → `pg_lsn` Renvoie le dernier emplacement des journaux de transactions, reçu et synchronisé sur disque par la réplication en flux. Tant que la réplication en flux est en cours, ceci augmentera de façon monotique. Si la restauration s'est terminée, alors cela restera statique à l'emplacement du dernier enregistrement reçu et synchronisé sur disque lors de la restauration. Si la réplication en flux est désactivée ou qu'elle n'a pas commencé, la fonction renvoie `NULL`.
`pg_last_wal_replay_lsn` () → `pg_lsn` Renvoie le dernier emplacement des journaux de transactions, rejoué lors de la restauration. Si la restauration est toujours en cours, ceci augmentera de façon monotique. Si la restauration s'est terminée, alors cela restera statique à l'emplacement du dernier enregistrement appliqué lors de la restauration. Quand le serveur a été démarré normalement sans restauration, la fonction renvoie `NULL`.
`pg_last_xact_replay_timestamp` () → `timestamp with time zone` Renvoie l'horodatage de la dernière transaction rejouée pendant la restauration. C'est le moment où l'enregistrement de validation ou d'annulation a été généré sur le serveur promaire. Si aucune transaction n'a été rejouée pendant la restauration, la fonction renvoie `NULL`. Sinon, si la restauration est toujours en cours, ceci augmentera de façon monotonique. Si la restauration s'est terminée, alors cela restera statique à partir du moment de la dernière transaction appliquée à la restauration. Quand le serveur est démarré normalement sans restauration, la fonction renvoie `NULL`.

Les fonctions listées dans Tableau 9.89 contrôlent la progression de la restauration. Ces fonctions peuvent seulement être exécutées lors d'une restauration.

Tableau 9.89. Fonctions de contrôle de la restauration

Fonction Description
`pg_is_wal_replay_paused` () → `boolean` Renvoie true si la pause de la restauration est demandée.
`pg_get_wal_replay_pause_state` () → `text` Renvoie l'état de la pause de restauration. Les valeurs retournées sont `not paused` si aucune pause n'est requise, `pause requested` si une pause est requise, mais que la restauration n'est pas en pause, et `paused` si la restauration est effectivement en pause.
`pg_promote` ( `wait` `boolean` `DEFAULT` `true`, `wait_seconds` `integer` `DEFAULT` `60` ) → `boolean` Promeut un serveur secondaire au statut primaire. Avec `wait` configuré à `true` (la valeur par défaut), la fonction attend jusqu'à ce que la promotion soit terminée ou jusqu'à ce que `wait_seconds` se soient écoulées, et renvoie `true` si la promotion a réussi. Elle renvoie `false` dans les autres cas. Si `wait` est configuré à `false`, la fonction renvoie `true` immédiatement après avoir envoyé le signal `SIGUSR1` au postmaster pour déclencher sa promotion. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_wal_replay_pause` () → `void` Demande la mise en pause de la restauration. Une demande ne signifie pas que la restauration va effectivement s'arrêter. Si vous voulez vérifier que la restauration s'est effectivement arrêtée, vous devez vérifier l'état de la pause de restauration retournée par `pg_get_wal_replay_pause_state()`. Notez que `pg_is_wal_replay_paused()` retourne si oui ou non une demande est faite. Pendant que la restauration est en pause, plus aucune modification ne peut être faite sur la base de données. Si aucun hot standby n'est actif, toutes les requêtes verront le même instantané consistant de la base de données, et plus aucun conflit de requête ne sera généré jusqu'à ce que la restauration redémarre. Cette fonction est par défaut restreinte aux super-utilisateurs, mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.
`pg_wal_replay_resume` () → `void` Relance la restauration si elle était en pause. Cette fonction est par défaut restreinte aux super-utilisateurs mais les autres utilisateurs peuvent se voir donner le droit EXECUTE pour exécuter cette fonction.

`pg_wal_replay_pause` et `pg_wal_replay_resume` ne peuvent pas être exécutés quand une promotion est en cours. Si une promotion est déclenchée alors que la restauration est en pause, l'état de pause se termine et la promotion continue.

Si la réplication en flux est désactivé, l'état de pause peut continuer indéfiniment sans problème. Si la réplication en flux est en cours, alors les enregistrements des journaux de transactions continuent à être rçus, ce qui finira par remplir l'espace disque disponible, suivant la durée de la pause, le taux de génération des journaux de transactions et l'espace disque disponible.

### 9.27.5. Fonctions de synchronisation d'image

PostgreSQL permet aux sessions des bases de données de synchroniser leur image de base. Une image de base (ou snapshot) détermine les données visibles pour la transaction utilisant l'image. Les images synchronisées sont nécessaires quand deux sessions ou plus ont besoin de voir un contenu identique de la base de données. Si deux sessions démarrent leur transaction indépendamment, il existe toujours une possibilité qu'une autre transaction valid entre l'exécution des deux commandes `START TRANSACTION`, de telle façon qu'une session voit l'effet de cette transaction alors que l'autre ne la voit pas.

Pour résoudre ce problème, PostgreSQL autorise une transaction à exporter l'image qu'elle utilise. Tant que la transaction exportée reste ouverte, les autres transactions peuvent importer son image et, de ce fait, garantir qu'elles partagent exactement la même vue de la base que la première transaction. Mais notez que tout changement effectué par une de ces transactions reste invisible aux autres transactions, comme d'habitude pour les modifications réalisées par des transactions non validées. Donc les transactions sont synchronisées suivant les données pré-existantes, mais agissent normalement pour les modifications qu'elles réalisent.

Les images sont exportées avec la fonction `pg_export_snapshot`, affichée dans Tableau 9.90, et importées avec la commande SET TRANSACTION.

Tableau 9.90. Fonctions de synchronisation d'image

Fonction Description
`pg_export_snapshot` () → `text` Sauvegarde l'image actuelle de la transaction et renvoie une donnée de type `text` identifiant l'image. Cette chaîne doit être fournie (en dehors de la base) aux clients qui veulent importer l'image. L'image est disponible à l'import seulement jusqu'à la fin de la transaction qui l'a exporté. Une transaction peut exporter plus d'une image, si nécessaire. Notez que faire cela n'est utile que pour les transactions en niveau `READ COMMITTED` car, dans les niveaux d'isolation `REPEATABLE READ` et supérieurs, les transactions utilisent la même image tout au long de leur vie. Une fois qu'une transaction a export une image, elle ne peut pas être préparée avec PREPARE TRANSACTION.

### 9.27.6. Fonctions de gestion de la réplication

Les fonctions listées dans Tableau 9.91 sont pour le contrôle et l'interaction avec les fonctionnalités de réplication. Voir Section 27.2.5, Section 27.2.6 et Chapitre 50 pour des informations sur les fonctionnalités sous-jacentes. L'utilisation de fonctions pour l'origine de réplication est seulement autorisée aux super-utilisateurs par défaut, mais peut être autorisée aux autres utilisateurs en utilisant la commande `GRANT`. L'utilisation des fonctions pour les slots de réplication est restreinte aux super-utilisateurs et aux utilisateurs ayant l'attribut `REPLICATION`.

La plupart de ces fonctions ont des commandes équivalentes dans le protocole de réplication ; voir Section 53.4.

Les fonctions décrites dans Section 9.27.3, Section 9.27.4 et Section 9.27.5 sont aussi adéquates pour la réplication.

Tableau 9.91. Fonctions de gestion de la réplication

Fonction Description
`pg_create_physical_replication_slot` ( `slot_name` `name` [, `immediately_reserve` `boolean`, `temporary` `boolean`, `twophase` `boolean` ] ) → `record` ( `slot_name` `name`, `lsn` `pg_lsn` ) Crée un nouveau slot de réplication physique nommé `slot_name`. Le deuxième paramètre, optionnel, indique, quand il vaut `true`, que le LSN pour ce slot de réplication doit être réservé immédiatement. Dans le cas contraire, le LSN est réservé lors de la première connexion à partir d'un client de réplication de flux. Les changements en flux d'un slot de réplication sont seulement possible avec le protocole de réplication de flux -- voir Section 53.4. Le troisième argument, optionnel, nommé `temporary`, indique, quand il vaut true, que le slot ne doit pas être enregistré de façon permanente sur disque et qu'il a seulement pour but d'être utilisé dans la session en cours. Les slots temporaires sont aussi supprimés dès qu'une erreur survient. Le quatrième paramètre optionnel, `twophase`, quand il vaut true, indique que le décodage des transactions préparées est autorisé pour ce slot. Cette fonction correspond à la commande `CREATE_REPLICATION_SLOT ... PHYSICAL` du protocole de réplication.
`pg_drop_replication_slot` ( `slot_name` `name` ) → `void` Supprime le slot de réplication physique ou logique nommé `slot_name`. Elle est identique à la commande `DROP_REPLICATION_SLOT` du protocole de réplication.
`pg_create_logical_replication_slot` ( `slot_name` `name`, `plugin` `name` [, `temporary` `boolean`, `twophase` `boolean` ] ) → `record` ( `slot_name` `name`, `lsn` `pg_lsn` ) Crée un nouveau slot de réplication logique (décodage) nommé `slot_name` en utilisant le plugin de sortie `plugin`. Le troisième paramètre, optionnel, nommé `temporary` indique, quand il vaut true, que le slot ne devrait pas être stockée de façon permanente sur disque et a seulement pour but d'être utilisé par la session en cours. Les slots temporaires sont aussi supprimés en cas d'erreur. Un appel à cette fonction a le même effet que la commande `CREATE_REPLICATION_SLOT ... LOGICAL` du protocole de réplication.
`pg_copy_physical_replication_slot` ( `src_slot_name` `name`, `dst_slot_name` `name` [, `temporary` `boolean` ] ) → `record` ( `slot_name` `name`, `lsn` `pg_lsn` ) Copie un slot de réplication physique existant, nommé `src_slot_name`, en un slot de réplication physique nommé `dst_slot_name`. Le slot physique copié commencera à réserver les journaux de transactions à partir du même LSN que celui du slot copié. Le paramètre `temporary` est en option. Si `temporary` est omis, la valeur du slot source est utilisée.
`pg_copy_logical_replication_slot` ( `src_slot_name` `name`, `dst_slot_name` `name` [, `temporary` `boolean` [, `plugin` `name` ]] ) → `record` ( `slot_name` `name`, `lsn` `pg_lsn` ) Copie un slot existant de réplication logique nommé named `src_slot_name` en un slot de réplication logique nommé `dst_slot_name`, en changeant en option son plugin de sortie et sa persistence. Le slot logique copié commence à partir du même LSN que celui du slot logique source. Les paramètres `temporary` et `plugin` sont optionnels ; s'ils sont omis, leur valeur sur le slot source est utilisée.
`pg_logical_slot_get_changes` ( `slot_name` `name`, `upto_lsn` `pg_lsn`, `upto_nchanges` `integer`, `VARIADIC` `options` `text[]` ) → `setof record` ( `lsn` `pg_lsn`, `xid` `xid`, `data` `text` ) Renvoie les changements dans le slot `slot_name`, en commençant à partir du point où les changements ont été consommés en dernier. Si `upto_lsn` et `upto_nchanges` sont NULL, le décodage logique continuera jusqu'à la fin des journaux de transactions. Si `upto_lsn` n'est pas NULL, le décodage incluera seulement les transactions dont la validation date d'avant le LSN indiqué. Si `upto_nchanges` n'est pas NULL, le décodage stoppera quand le nombre de lignes produites par le décodage dépasse la valeur indiquée. Cependant, notez que le nombre réel de lignes renvoyées pourrait être plus important car cette limite est seulement vérifiée après l'ajout des lignes produites lors du décodage de chaque nouvelle validation de transaction.
`pg_logical_slot_peek_changes` ( `slot_name` `name`, `upto_lsn` `pg_lsn`, `upto_nchanges` `integer`, `VARIADIC` `options` `text[]` ) → `setof record` ( `lsn` `pg_lsn`, `xid` `xid`, `data` `text` ) Se comporte comme la fonction `pg_logical_slot_get_changes()`, sauf que les changements ne sont pas consommés ; autrement dit, ils sont de nouveau renvoyés lors des prochains appels.
`pg_logical_slot_get_binary_changes` ( `slot_name` `name`, `upto_lsn` `pg_lsn`, `upto_nchanges` `integer`, `VARIADIC` `options` `text[]` ) → `setof record` ( `lsn` `pg_lsn`, `xid` `xid`, `data` `bytea` ) Se comporte comme la fonction `pg_logical_slot_get_changes()`, sauf que les changements sont renvoyés comme des `bytea`.
`pg_logical_slot_peek_binary_changes` ( `slot_name` `name`, `upto_lsn` `pg_lsn`, `upto_nchanges` `integer`, `VARIADIC` `options` `text[]` ) → `setof record` ( `lsn` `pg_lsn`, `xid` `xid`, `data` `bytea` ) Se comporte comme la fonction `pg_logical_slot_peek_changes()`, sauf que les modifications sont renvoyées sous la forme de `bytea`.
`pg_replication_slot_advance` ( `slot_name` `name`, `upto_lsn` `pg_lsn` ) → `record` ( `slot_name` `name`, `end_lsn` `pg_lsn` ) Avance la position confirmée actuelle pour le slot de réplication nommé `slot_name`. Le slot ne sera pas déplacé en arrière, et il ne sera pas déplacé après l'emplacement d'insertion actuel. Renvoie le nom du slot et la position où il a été réellement avancé. L'information mise à jour de position du slot est écrite dans le prochain checkpoint si l'avance a été possible. Dans le cas d'un crash, le slot pourrait retourner à une position précédente.
`pg_replication_origin_create` ( `node_name` `text` ) → `oid` Crée une origine de réplication avec le nom externe donné, et renvoie l'identifiant interne qui lui a été affecté.
`pg_replication_origin_drop` ( `node_name` `text` ) → `void` Supprime une origine de réplication précédemment créée, incluant toute progression de rejeu associée.
`pg_replication_origin_oid` ( `node_name` `text` ) → `oid` Recherche une origine de réplication par son nom et renvoie son identifiant interne. Si cette origine de réplication n'existe pas, `NULL` est renvoyée.
`pg_replication_origin_session_setup` ( `node_name` `text` ) → `void` Marque la session en cours comme rejouant à partir de l'origine donnée, en autorisant le traçage de la progression du rejeu. Peut seulement être utilisée si aucune origine n'est actuellement sélectionnée. Utilisez `pg_replication_origin_session_reset` pour annuler.
`pg_replication_origin_session_reset` () → `void` Annule les effets de `pg_replication_origin_session_setup()`.
`pg_replication_origin_session_is_setup` () → `boolean` Renvoie true si une origine de réplication a été sélectionnée dans la session en cours.
`pg_replication_origin_session_progress` ( `flush` `boolean` ) → `pg_lsn` Renvoie l'emplacement de rejeu pour l'origine de réplication sélectionnée dans la session en cours. Le paramètre `flush` détermine si la transaction locale correspondance sera garantie d'être vidée sur disque ou pas.
`pg_replication_origin_xact_setup` ( `origin_lsn` `pg_lsn`, `origin_timestamp` `timestamp with time zone` ) → `void` Marque la transaction en cours comme rejouant une transaction qui a été validée au LSN et à l'horodatage donnés. Peut être appelé quand une origine de réplication a été sélectionnée en utilisant `pg_replication_origin_session_setup`.
`pg_replication_origin_xact_reset` () → `void` Annule les effets de `pg_replication_origin_xact_setup()`.
`pg_replication_origin_advance` ( `node_name` `text`, `lsn` `pg_lsn` ) → `void` Configure la progression de la réplication pour le nœud donné à l'emplacement donné. Ceci est principalement utile pour configurer l'emplacement initial ou pour configurer un nouvel emplacement après des changements de configuration ou similaires. Faites attention qu'une mauvaise utilisation de cette fonction peut amener à des données répliquées de façon incohérente.
`pg_replication_origin_progress` ( `node_name` `text`, `flush` `boolean` ) → `pg_lsn` Renvoie l'emplacement de rejeu pour l'origine de réplication donnée. Le paramètre `flush` détermine si la transaction locale correspondante sera garantie d'être vidée sur disque ou pas.
`pg_logical_emit_message` ( `transactional` `boolean`, `prefix` `text`, `content` `text` ) → `pg_lsn` `pg_logical_emit_message` ( `transactional` `boolean`, `prefix` `text`, `content` `bytea` ) → `pg_lsn` Émet un message de décodage logique. Cela peut être utilisé pour passer des messages génériques aux plugins de décodage logique via les journaux de transactions. Le paramètre `transactional` indique si le message devrait faire partie de la transaction en cours ou s'il devrait être écrit immédiatement et décodé dès que le décodeur logique lit l'enregistrement. Le paramètre `prefix` est un préfixe textuel qui peut être utilisé par les plugins de décodage logique pour reconnaître facilement les messages qui les intéressent. Le paramètre `content` est le contenu du message, donné soit au format texte soit au format binaire.

### 9.27.7. Fonctions de gestion des objets de la base

Les fonctions listées dans Tableau 9.92 calculent l'utilisation de l'espace disque des objets de la base, ou assistent dans la présentation ou la compréhension de ces résultats. Les résultats du type `bigint` correspondent à la taille mesurée en octets. `NULL` est renvoyé si un OID qui ne représente pas un objet existant est fourni à une de ces fonctions.

Tableau 9.92. Fonctions de taille des objets

Fonction Description
`pg_column_size` ( `"any"` ) → `integer` Affiche le nombre d'octets utilisés pour enregistrer une valeur individuelle. Si elle est appliquée directement à une valeur d'une colonne de la table, cela représente la compression effectuée.
`pg_column_compression` ( `"any"` ) → `text` Montre l'algorithme de compression utilisé pour compresser une valeur individuelle. Retourne `NULL` si la valeur n'est pas compressée.
`pg_database_size` ( `name` ) → `bigint` `pg_database_size` ( `oid` ) → `bigint` Calcule l'espace disque total utilisé par la base dont le nom ou l'OID est indiqué. Pour utiliser cette fonction, vous devez avoir le droit `CONNECT` sur la base (qui est donné par défaut) ou être un membre du rôle `pg_read_all_stats`.
`pg_indexes_size` ( `regclass` ) → `bigint` Calcule l'espace disque total utilisé par les index attachés à une table spécifique.
`pg_relation_size` ( `relation` `regclass` [, `fork` `text` ] ) → `bigint` Calcule l'espace disque utilisé par un « élément » de la relation indiquée. (Notez que, dans la plupart des cas, il est préférable d'utiliser les fonctions `pg_total_relation_size` et `pg_table_size`, qui additionnent les tailles de tous les éléments d'une relation.) Avec un argument, ceci renvoie la taille de l'élément principal de la relation. Le second argument permet de préciser l'élément à examiner : `main` renvoie la taille de l'élément principal de la relation. `fsm` renvoie la taille de la carte des espaces libres (voir Section 70.3) associée à cette relation. `vm` renvoie la taille de la carte de visibilité (voir Section 70.4) associée à cette relation. `init` renvoie la taille de l'élément d'initialisation, si elle existe, associée à cette relation.
`pg_size_bytes` ( `text` ) → `bigint` Convertit la taille indiquée dans un format lisible par un humain (tel qu'il est donné par `pg_size_pretty`) en un nombre d'octets.
`pg_size_pretty` ( `bigint` ) → `text` `pg_size_pretty` ( `numeric` ) → `text` Convertit une taille indiquée en octets dans un format plus facilement lisible par un humain avec des unités (bytes, kB, MB, GB ou TB suivant le cas). Notez que les unités sont des puissances de 2, plutôt que des puissances de 10, donc 1kB vaut 1024 octets, 1MB vaut 10242 = 1048576 octets, et ainsi de suite.
`pg_table_size` ( `regclass` ) → `bigint` Calcule l'espace disque utilisé par la table indiquée, en excluant les index (mais en incluant la table TOAST si elle existe, la carte des espaces libres et la carte de visibilité).
`pg_tablespace_size` ( `name` ) → `bigint` `pg_tablespace_size` ( `oid` ) → `bigint` Calcule l'espace disque total utilisé dans le tablespace indiqué par son nom ou son OID. Pour utiliser cette fonction, vous devez avoir le droit `CREATE` sur le tablespace ou être un membre du rôle `pg_read_all_stats`, sauf s'il s'agit du tablespace par défaut de la base actuelle.
`pg_total_relation_size` ( `regclass` ) → `bigint` Calcule l'espace disque utilisé par la table indiquée, en incluant tous les index et les données TOAST. Le résultat est équivalent à `pg_table_size` `+` `pg_indexes_size`.

Les fonctions ci-dessus qui opèrent sur les tables et sur les index acceptent un argument `regclass`, qui est simplement l'OID de la table ou de l'index dans le catalogue système `pg_class`. Néanmoins, vous n'avez pas besoin de rechercher manuellement l'OID comme le convertisseur en entrée du type de données `regclass` fera ce travail pour vous. Voir Section 8.19 pour les détails.

Les fonctions listées dans Tableau 9.93 assistent à l'identification des fichiers spécifiques associés aux objets de la base.

Tableau 9.93. Fonctions d'emplacement des objets de la base

Fonction Description
`pg_relation_filenode` ( `relation` `regclass` ) → `oid` Renvoie le numéro « filenode » actuellement affecté à la relation indiquée. Ce numéro est le composant de base du nom du fichier utilisé pour la relation (voir Section 70.1 pour plus d'informations). Pour la plupart des relations, le résultat est identique à `pg_class`.`relfilenode`, mais pour certains catalogues systèmes, le `relfilenode` vaut zéro et cette fonction doit être utilisée pour obtenir la valeur correcte. La fonction renvoie NULL si on lui passe une relation qui n'a pas de stockage, comme une vue.
`pg_relation_filepath` ( `relation` `regclass` ) → `text` Renvoie le chemin complet avec le nom du fichier pour cette relation (chemin relatif au répertoire principal des données de l'instance, `PGDATA`).
`pg_filenode_relation` ( `tablespace` `oid`, `filenode` `oid` ) → `regclass` Renvoie l'OID d'une relation d'après l'OID de son tablespace et son filenode. Ceci est la correspondance inverse de `pg_relation_filepath`. Pour une relation dans le tablespace par défaut de la base, le tablespace peut être indiqué par un zéro. Renvoie `NULL` si aucune relation n'est associée aux valeurs données dans la base en cours ou s'il s'agit d'une relation temporaire.

Tableau 9.94 liste les fonctions utilisées pour gérer les collations.

Tableau 9.94. Fonctions de gestion des collations

Fonction Description
`pg_collation_actual_version` ( `oid` ) → `text` Renvoie la version actuelle de l'objet collation tel qu'il est installé sur le système d'exploitation. S'il est différent de la valeur dans `pg_collation`.`collversion`, alors les objets dépendant de la collation doivent être reconstruits. Voir aussi ALTER COLLATION.
`pg_import_system_collations` ( `schema` `regnamespace` ) → `integer` Ajoute des collations dans le catalogue système `pg_collation` basé sur toutes les locales trouvées dans le système d'exploitation. Ceci est ce que `initdb` utilise ; voir Section 24.2.2 pour plus de détails. Si les locales supplémentaires sont installées plus tard dans le système d'exploitation, cette fonction doit être de nouveau exécutée pour ajouter des collations pour les nouvelles locales. Les locales correspondant à des entrées existantes dans `pg_collation` seront ignorées. (Mais les objets de collation basés sur des locales qui ne sont plus présentes au niveau du système d'exploitation ne sont pas supprimées par cette fonction.) Le paramètre `schema` sera typiquement `pg_catalog`, mais ce n'est pas obligatoire ; les collations peuvent être installés dans d'autres schémas. La fonction renvoie le nombre des nouveaux objets collations créés. L'utilisation de cette fonction est restreinte aux super-utilisateurs.

Tableau 9.95 liste les fonctions qui fournissent des informations sur la structure des tables partitionnées.

Tableau 9.95. Fonctions d'information sur le partitionnement

Fonction Description
`pg_partition_tree` ( `regclass` ) → `setof record` ( `relid` `regclass`, `parentrelid` `regclass`, `isleaf` `boolean`, `level` `integer` ) Liste les tables ou index dans l'arbre de partitionnement de la table ou de l'index partitionné indiqué, avec une ligne pour chaque partition. Les informations fournies incluent l'OID de la partition, l'OID de son parent immédiat, une valeur booléenne indiquant si la partition est une feuille et un entier indiquant son niveau dans la hiérarchie. Le niveau 0 correspond à la table ou l'index en entrée, 1 pour ses partitions immédiates, 2, pour leurs partitions, et ainsi de suite. Ne renvoie aucune ligne si la relation n'existe pas ou s'il ne s'agit ni d'une table partitionnée ni d'une partition.
`pg_partition_ancestors` ( `regclass` ) → `setof regclass` Liste les relations ancêtres d'une partition donnée, y compris cette relation. Ne renvoie aucune ligne si la relation n'existe pas ou s'il ne s'agit ni d'une table partitionnée ni d'une partition.
`pg_partition_root` ( `regclass` ) → `regclass` Renvoie le parent de plus haut niveau de l'arbre de partition à laquelle appartient la relation donnée. Renvoie `NULL` si la relation n'existe pas ou s'il ne s'agit ni d'une table partitionnée ni d'une partition.

Par exemple, pour vérifier la taille totale de la donnée contenue dans une table partitionnée `measurement`, il est possible d'utiliser la requête suivante :

    SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
      FROM pg_partition_tree('measurement');

### 9.27.8. Fonctions de maintenance des index

Tableau 9.96 liste les fonctions disponibles pour les tâches de maintenance d'index. (Notez que ces tâches de maintenance sont normalement réalisés par l'autovacuum ; l'utilisation de ces fonctions est seulement requise dans des cas particuliers.) Ces fonctions ne peuvent pas être exécutées lors de la restauration. L'utilisation de ces fonctions est restreinte aux super-utilisateurs et au propriétaire de l'index donné.

Tableau 9.96. Fonctions de maintenance des index

Fonction Description
`brin_summarize_new_values` ( `index` `regclass` ) → `integer` Parcourt l'index BRIN spécifié pour trouver les intervalles de blocs da la table qui ne sont pas actuellement résumés par l'index ; pour chaque intervalle, il crée un nouvel enregistrement de résumé dans l'index en parcourant ces blocs dans la table. Renvoie le nombre de nouveaux résumés d'intervalle de blocs insérés dans l'index.
`brin_summarize_range` ( `index` `regclass`, `blockNumber` `bigint` ) → `integer` Résume l'intervalle de blocs couvrant le bloc donné, s'il n'est pas déjà résumé. Cela ressemble à `brin_summarize_new_values`, sauf qu'il traite seulement l'intervalle de blocs qui couvre le numéro de bloc de la table donnée.
`brin_desummarize_range` ( `index` `regclass`, `blockNumber` `bigint` ) → `void` Supprime l'enregistement de l'index BRIN qui résume l'intervalle de blocs couvrant le bloc de la table donnée, s'il y en a un.
`gin_clean_pending_list` ( `index` `regclass` ) → `bigint` Supprime la liste « pending » de l'index GIN spécifié en déplaçant les enregistrements à l'intérieur, en masse, vers la structure principale de données GIN. Renvoie le nombre de blocs supprimés dans la liste d'attente. Si l'argument est un index GIN construit avec l'option `fastupdate` désactivée, aucun nettoyage ne survient et le résultat vaut zéro car l'index n'a pas de liste d'attente. Voir Section 67.4.1 et Section 67.5 pour les détails sur la liste d'attente et l'option `fastupdate`.

### 9.27.9. Fonctions génériques d'accès aux fichiers

Les fonctions listées dans Tableau 9.97 fournissent des accès natifs aux fichiers du serveur gérant le serveur. Seuls les fichiers à l'intérieur du répertoire d'instance de la base et ceux ciblés par le paramètre `log_directory` peuvent être accédés, que l'utilisateur est un super-utilisateur ou s'est vu donné le rôle `pg_read_server_files`. Utilisez un chemin relatif pour les fichiers du répertoire principal des données, et un chemin correspondant à la configuration du paramètre `log_directory` pour les fichiers de trace.

Notez que donner aux utilisateurs le droit EXECUTE sur `pg_read_file()`, ou les fonctions relatives, les autorise à lire tout fichier du serveur que le processus serveur peut lire. Ces fonctions contournent toutes les vérifications de droit d'accès à la base. Ceci signifie que, pour un exemple, un utilisateur avec un tel accès est capable de lire le contenu de la table `pg_authid` où l'information d'authentification est stockée dans les données de la table de la base. De ce fait, donner l'accès à ces fonctions devrait être considéré avec attention.

Certaines de ces fonctions prennent un paramètre `missing_ok` qui modifie le comportement quand le fichier ou le répertoire n'existe pas. Si `true`, la fonction renvoie `NULL` ou un ensemble vide de résultats, comme approprié. Si `false`, une erreur est levée. La valeur par défaut est `false`.

Tableau 9.97. Fonctions génériques d'accès aux fichiers

Fonction Description
`pg_ls_dir` ( `dirname` `text` [, `missing_ok` `boolean`, `include_dot_dirs` `boolean` ] ) → `setof text` Renvoie le nom de tous les fichiers (et répertoires et autres fichiers spéciaux) dans le répertoire donné. Le paramètre `include_dot_dirs` indique si les pseudo-répertoires « . » et « .. » sont à inclure dans le résultat ; par défaut, ils sont exclus. Les inclure peut être utile dans `missing_ok` vaut `true` pour distinguer un répertoire vide d'un répertoire inexistant. Cette fonction est restreinte par défaut aux super-utilisateurs, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.
`pg_ls_logdir` () → `setof record` ( `name` `text`, `size` `bigint`, `modification` `timestamp with time zone` ) Renvoie le nom, la taille et l'horodatage de la dernière modification de chaque fichier ordinaire dans le répertoire des traces du serveur. Les fichiers dont le nom commence avec un point, les répertoires et les autres fichiers spéciaux sont exclus. Cette fonction est restreinte par défaut aux super-utilisateurs et aux utilisateurs membres du rôle `pg_monitor`, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.
`pg_ls_waldir` () → `setof record` ( `name` `text`, `size` `bigint`, `modification` `timestamp with time zone` ) Renvoie le nom, la taille et l'horodatage de la dernière modification de chaque fichier ordinaire dans le répertoire des journaux de transactions. Les fichiers dont le nom commence avec un point, les répertoires et les autres fichiers spéciaux sont exclus. Cette fonction est restreinte par défaut aux super-utilisateurs et aux utilisateurs membres du rôle `pg_monitor`, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.
`pg_ls_archive_statusdir` () → `setof record` ( `name` `text`, `size` `bigint`, `modification` `timestamp with time zone` ) Renvoie le nom, la taille et l'horodatage de la dernière modification de chaque fichier ordinaire dans le répertoire des statuts d'archivage. Les fichiers dont le nom commence avec un point, les répertoires et les autres fichiers spéciaux sont exclus. Cette fonction est restreinte par défaut aux super-utilisateurs et aux utilisateurs membres du rôle `pg_monitor`, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.
`pg_ls_tmpdir` ( [ `tablespace` `oid` ] ) → `setof record` ( `name` `text`, `size` `bigint`, `modification` `timestamp with time zone` ) Renvoie le nom, la taille et l'horodatage de la dernière modification de chaque fichier ordinaire dans le répertoire des fichiers temporaires pour le `tablespace` indiqué. Si `tablespace` est omis, le tablespace `pg_default` est examiné. Les fichiers dont le nom commence avec un point, les répertoires et les autres fichiers spéciaux sont exclus. Cette fonction est restreinte par défaut aux super-utilisateurs et aux utilisateurs membres du rôle `pg_monitor`, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.
`pg_read_file` ( `filename` `text` [, `offset` `bigint`, `length` `bigint` [, `missing_ok` `boolean` ]] ) → `text` Renvoie tout ou partie d'un fichier texte, en commençant à l'octet indiqué par `offset`, en renvoyant au plus `length` octets (moins si la fin du fichier est atteinte avant). Si `offset` est négatif, il est relatif à la fin du fichier. Si `offset` et `length` sont omis, le fichier entier est renvoyé. Les octets lus dans le fichier sont interprétés comme une chaîne dans l'encodage de la base ; une erreur est renvoyée s'ils ne sont pas valides pour cet encodage. Cette fonction est restreinte par défaut aux super-utilisateurs, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.
`pg_read_binary_file` ( `filename` `text` [, `offset` `bigint`, `length` `bigint` [, `missing_ok` `boolean` ]] ) → `bytea` Renvoie tout ou partie d'un fichier. Cette fonction est identique à `pg_read_file` sauf qu'elle peut lire toute donnée binaire, en renvoyant le résultat sous la forme d'un `bytea`, et non pas d'un `text` ; de ce fait, aucune vérification d'encodage n'est réalisée. Cette fonction est restreinte par défaut aux super-utilisateurs, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction. En combinant avec la fonction `convert_from`, cette fonction peut être utilisée pour lire un fichier texte dans un encodage spécial et le convertir dans l'encodage de la base :
    SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');
`pg_stat_file` ( `filename` `text` [, `missing_ok` `boolean` ] ) → `record` ( `size` `bigint`, `access` `timestamp with time zone`, `modification` `timestamp with time zone`, `change` `timestamp with time zone`, `creation` `timestamp with time zone`, `isdir` `boolean` ) Renvoie un enregistement contenant la taille du fichier, son horodatage de dernier accès, celui de dernière modification, celui de dernier changement de statut (plateformes Unix uniquement), l'horodatage de création (Windows uniquement), et un drapeau indiquant si c'est un répertoire. Cette fonction est restreinte par défaut aux super-utilisateurs, mais d'autres utilisateurs peuvent se voir donner le droit EXECUTE pour cette fonction.

### 9.27.10. Fonctions sur les verrous consultatifs

Les fonctions listées dans Tableau 9.98 gèrent les verrous consultatifs. Pour les détails sur une utilisation correcte de ces fonctions, voir Section 13.3.5.

Toutes ces fonctions ont pour but d'être utilisées pour verrouiller des ressources définies par l'application, qui peuvent être identifiées soit par une valeur de clé sur 64 bits, soit par deux valeurs de clés sur 32 bits (notez que ces deux espaces de clés ne se surchargent pas). Si une autre session détient déjà un verrou conflictuel sur le même identifiant de ressource, les fonctions devront soit attendre que la ressource devienne disponible, soit renvoyer un résultat `false`, comme approprié pour la fonction. Les verrous peuvent être soit partagés soit exclusifs ; un verrou partagé n'entre pas en conflit avec d'autres verrous partagés sur la même ressource, mais entre en conflit avec les verrous exclusifs. Les verrous peuvent se prendre au niveau de la session (pour qu'ils soient détenus jusqu'à leur suppression ou jusqu'à la fin de la session) ou au niveau de la transaction (pour qu'ils soient détenus jusqu'à la fin de la transaction ; il n'existe pas de moyen pour les supprimer manuellement). Les demandes multiples de verrou au niveau session s'empilent, pour que, si le même identifiant de ressource est verrouillé trois fois, alors il doit y avoir trois demandes de déverrouillage pour relâcher la ressource avant que la session se termine.

Tableau 9.98. Fonctions pour les verrous informatifs

Fonction Description
`pg_advisory_lock` ( `key` `bigint` ) → `void` `pg_advisory_lock` ( `key1` `integer`, `key2` `integer` ) → `void` Obtient un verrou informatif exclusif niveau session, en attendant si nécessaire.
`pg_advisory_lock_shared` ( `key` `bigint` ) → `void` `pg_advisory_lock_shared` ( `key1` `integer`, `key2` `integer` ) → `void` Obtient un verrou informatif partagé niveau session, en attendant si nécessaire.
`pg_advisory_unlock` ( `key` `bigint` ) → `boolean` `pg_advisory_unlock` ( `key1` `integer`, `key2` `integer` ) → `boolean` Relâche un verrou informatif exclusif niveau session précédemment acquis. Renvoie `true` si le verrou a été relâché avec succès. Si le verrou n'était pas détenu, `false` est renvoyé et, en plus, un message d'avertissement SQL est reporté au serveur.
`pg_advisory_unlock_all` () → `void` Relâche tous les verrous informatifs niveau session détenus par la session en cours. (Cette fonction est appelée implicitement à la fin d'une session, même si le client s'est mal déconnecté.)
`pg_advisory_unlock_shared` ( `key` `bigint` ) → `boolean` `pg_advisory_unlock_shared` ( `key1` `integer`, `key2` `integer` ) → `boolean` Relâche un verrou informatif partagé niveau session précédemment acquis. Renvoie `true` si le verrou a été relâché avec succès. Si le verrou n'était pas détenu, `false` est renvoyé et, en plus, un message d'avertissement SQL est reporté au serveur.
`pg_advisory_xact_lock` ( `key` `bigint` ) → `void` `pg_advisory_xact_lock` ( `key1` `integer`, `key2` `integer` ) → `void` Obtient un verrou informatif exclusif niveau transaction, en attendant si nécessaire.
`pg_advisory_xact_lock_shared` ( `key` `bigint` ) → `void` `pg_advisory_xact_lock_shared` ( `key1` `integer`, `key2` `integer` ) → `void` Obtient un verrou informatif partagé niveau transaction, en attendant si nécessaire.
`pg_try_advisory_lock` ( `key` `bigint` ) → `boolean` `pg_try_advisory_lock` ( `key1` `integer`, `key2` `integer` ) → `boolean` Obtient un verrou informatif exclusif niveau session si disponible. Cela va soit obtenir immédiatement le verrou et renvoyer `true`, soit renvoyer `false` sans attendre si le verrou ne peut pas être acquis immédiatement.
`pg_try_advisory_lock_shared` ( `key` `bigint` ) → `boolean` `pg_try_advisory_lock_shared` ( `key1` `integer`, `key2` `integer` ) → `boolean` Obtient un verrou informatif partagé niveau session si disponible. Cela va soit obtenir immédiatement le verrou et renvoyer `true`, soit renvoyer `false` sans attendre si le verrou ne peut pas être acquis immédiatement.
`pg_try_advisory_xact_lock` ( `key` `bigint` ) → `boolean` `pg_try_advisory_xact_lock` ( `key1` `integer`, `key2` `integer` ) → `boolean` Obtient un verrou informatif exclusif niveau transaction si disponible. Cela va soit obtenir immédiatement le verrou et renvoyer `true`, soit renvoyer `false` sans attendre si le verrou ne peut pas être acquis immédiatement.
`pg_try_advisory_xact_lock_shared` ( `key` `bigint` ) → `boolean` `pg_try_advisory_xact_lock_shared` ( `key1` `integer`, `key2` `integer` ) → `boolean` Obtient un verrou informatif partagé niveau transaction si disponible. Cela va soit obtenir immédiatement le verrou et renvoyer `true`, soit renvoyer `false` sans attendre si le verrou ne peut pas être acquis immédiatement.