9.27. Fonctions d'administration système

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`

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

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.

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

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.

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.

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. Pour les slots logiques, elle doit être appelée en étant connecté sur la même base que celle du slot 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.

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. Pour les slots logiques, elle doit être appelée en étant connecté sur la même base que celle du slot 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 1024² = 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`.

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 1024² = 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.

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.

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.

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.

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

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.

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.

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.

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