PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 13.0 » Langage SQL » Fonctions et opérateurs » Fonctions et opérateurs d'information sur le système

9.26. Fonctions et opérateurs d'information sur le système

Tableau 9.63 montre différentes fonctions pour extraire des informations sur les sessions et le système.

En plus des fonctions listées dans cette section, il existe plusieurs fonctions relatives au système de statistiques qui fournissent aussi des informations sur le système. Voir Section 27.2.2 pour plus d'informations.

Tableau 9.63. Fonctions d'information sur la session

Fonction

Description

current_catalogname

current_database () → name

Renvoie le nom de la base actuelle. (Les bases sont appelées des « catalogues » dans le standard SQL, donc current_catalog est le terme du standard.)

current_query () → text

Renvoie le texte de la requête en cours d'exécution telle qu'elle a été envoyée par le client (elle pourrait donc contenir plus d'une requête).

current_rolename

Équivalent à current_user.

current_schemaname

current_schema () → name

Renvoie le nom du premier schéma dans le chemin de recherche (ou une valeur NULL si le chemin de recherche est vide). C'est le schéma qui sera utilisé par toute création de tables ou d'autres objets nommés si un schéma cible n'est pas précisé.

current_schemas ( include_implicit boolean ) → name[]

Renvoie un tableau de noms pour tous les schémas présents dans le chemin de recherche, dans leur ordre de priorité. (Les éléments dans le paramètre search_path ne correspondant pas à des objets existants et cherchables sont omis.) Si l'argument booléen vaut true, alors les schémas systèmes implicites, tels que pg_catalog sont inclus dans le résultat.

current_username

Renvoie le nom de l'utilisateur dans le contexte d'exécution actuel.

inet_client_addr () → inet

Renvoie l'adresse IP du client actuel ou NULL si la connexion actuelle a été réalisée via une socket de domaine Unix.

inet_client_port () → integer

Renvoie le numéro de port IP du client actuel, ou NULL si la connexion actuelle a été réalisée via une socket de domaine Unix.

inet_server_addr () → inet

Renvoie l'adresse IP par laquelle le serveur a accepté la connexion actuelle, ou NULL si la connexion actuelle a été réalisée via une socket de domaine Unix.

inet_server_port () → integer

Renvoie le numéro de port IP par lequel le serveur a accepté la connexion actuelle, ou NULL si la connexion actuelle a été réalisée via une socket de domaine Unix.

pg_backend_pid () → integer

Renvoie l'identifiant de processus du processus serveur attaché à la session actuelle.

pg_blocking_pids ( integer ) → integer[]

Renvoie un tableau d'identiants de processus des sessions bloquant l'accès à un verrou pour le processus serveur dont l'identifiant a été donné. Renvoie un tableau vide si aucun processus ne le bloque.

Un processus serveur bloque un autre processus s'il détient un verrou qui entre en conflit avec la demande de verrou du processus bloqué (blocage dur) ou s'il est en attente d'un verrou qui rentrerait en conflit avec la demande de verrou du processus bloqué et est devant lui dans la queue d'attente (verrou léger). Lors de l'utilisation de requêtes parallélisées, le résultat liste toujours les identifiants des processus visibles du client (autrement dit, le résultat de pg_backend_pid) même si le verrou réel est détenu ou attendu par un processus worker. Ceci résulte potentiellement en des PID dupliqués dans le résultat. De plus, notez que quand une transaction préparée détient un verrou en conflit, il sera représenté par un identifiant zéro.

Les appels fréquents à cette fonction ont des impacts sur les performances de la base car il est nécessaire d'avoir un accès exclusif à l'état partagé du gestionnaire de verrous pour un court moment.

pg_conf_load_time () → timestamp with time zone

Renvoie l'horodatage du dernier chargement des fichiers de configuration. Si la session actuelle était vivante à ce moment, cela sera l'heure quand la session a elle-même relu les fichiers de configuration (donc le résultat peut légèrement varier sur les différentes sessions). Sinon c'est le moment où le processus postmater relit les fichiers de configuration.

pg_current_logfile ( [ text ] ) → text

Renvoie le chemin du fichier de traces actuellement utilisé par le collecteur de traces. Le chemin inclut le répertoire log_directory et le nom du fichier de traces individuel. Le résultat est NULL si le collecteur de traces est désactivé. Quand plusieurs fichiers de trace existent, chacun dans un format différent, pg_current_logfile sans argument renvoie le fichier vers le fichier ayant le premier format trouvé dans la liste ordonnée : stderr, csvlog. NULL est renvoyé si aucun fichier de trace n'a un de ces formats. Pour réclamer des informations sur un format spécifique de fichier de trace, indiquez soit csvlog soit stderr comme valeur au paramètre optionnel. Le résultat est NULL si le format de trace demandé n'est pas configuré dans log_destination. Le résultat réflète le contenu du fichier current_logfiles.

pg_my_temp_schema () → oid

Renvoie l'OID du schéma temporaire de la session en cours, ou zéro si ce schéma n'existe pas (parce que la session n'a pas créé de tables temporaires).

pg_is_other_temp_schema ( oid ) → boolean

Renvoie true si l'OID donné est l'OID du schéma temporaire d'une autre session. (Ceci peut être utile, par exemple, pour exclure les tables temporaires des autres sessions d'un affichage du catalogue.)

pg_jit_available () → boolean

Renvoie true si l'extension de compilation JIT est disponible (voir Chapitre 31) et si le paramètre de configuration jit est configué à on.

pg_listening_channels () → setof text

Renvoie l'ensemble de noms des canaux de notification asynchrone sur lesquels la session actuelle écoute.

pg_notification_queue_usage () → double precision

Renvoie la fraction (0–1) de la taille maximale de la queue de notification asynchrone actuellement occupée par des notifications en attente de traitement. Voir LISTEN et NOTIFY pour plus d'informations.

pg_postmaster_start_time () → timestamp with time zone

Renvoie l'heure de démarrage du serveur.

pg_safe_snapshot_blocking_pids ( integer ) → integer[]

Renvoie un tableau d'identifiants de processus des sessions bloquant le processus serveur avec l'identifiant de processus spécifié pour aquérir une image propre. Renvoie un tableau vide si ce processus n'existe pas ou s'il n'est pas bloqué.

Une session exécutant une transaction SERIALIZABLE bloque une transaction SERIALIZABLE READ ONLY DEFERRABLE sur l'acquisition d'une image jusqu'à ce que ce dernier détermine s'il est sûr d'éviter de prendre des verrous de prédicat. Voir Section 13.2.3 pour plus d'informations sur les transactions sérialisables et déferrables.

Les appels fréquents à cette fonction pourraient avoir des impacts sur la performance des bases car elle a besoin d'accéder à l'état partagé du gestionnaire de verrous de prédicats pour un court moment.

pg_trigger_depth () → integer

Renvoie le niveau de profondeur actuel des triggers PostgreSQL (0 si non appelé, directement ou indirectement, à partir d'un trigger).

session_username

Renvoie le nom d'utilisateur de la session.

username

Équivalent à current_user.

version () → text

Renvoie une chaîne décrivant la version du serveur PostgreSQL. Vous pouvez aussi obtenir cette information à partir de server_version ou, pour une version lisible par un logiciel, vous pouvez utiliser server_version_num. Les développeurs de logiciels devraient utiliser server_version_num (disponible depuis la version 8.2) ou PQserverVersion au lieu d'analyser la version texte.


Note

current_catalog, current_role, current_schema, current_user, session_user et user ont un statut syntaxique spécial en SQL : elles doivent être appelées sans les parenthèses. Dans PostgreSQL, les parenthèses peuvent être utilisées en option avec current_schema, mais pas avec les autres.

session_user est habituellement l'utilisateur qui a initié la connexion à la base de données ; les superutilisateurs peuvent modifier ce paramètre avec SET SESSION AUTHORIZATION. current_user est l'identifiant de l'utilisateur applicable pour les vérifications de droits. Habituellement, il est égal à l'utilisateur de la session mais il peut être changé avec SET ROLE. Il peut aussi changer durant l'exécution d'une fonction ayant l'attribut SECURITY DEFINER. Dans la parlance Unix, l'utilisateur de session est le « real user » et l'utilisateur courant est le « effective user ». current_role et user sont des synonymes pour current_user. (Le standard SQL fait une distinction entre current_role et current_user, mais PostgreSQL ne la fait pas car il unifie les utilisateurs et les rôles en une seule entité.)

Tableau 9.64 liste les fonctions qui permettent d'accéder programmatiquement aux droits d'accès aux objets. (Voir Section 5.7 pour plus d'informations sur les droits.) Dans ces fonctions, l'utilisateur dont les droits sont interrogés peut être indiqué par son nom ou son OID (pg_authid.oid), ou si le nom donné est public, alors la vérification se fait sur les droits du pseudo-rôle PUBLIC. De plus, l'argument user peut être complètement omis, auquel cas la vérification se fera sur current_user. L'objet vérifié peut être indiqué par son nom ou son OID. Dans le cas du nom, le nom du schéma peut être inclus si nécessaire. Le droit d'accès d'intérêt est indiqué par une chaîne de caractères qui doit correspondre à un des mots clés approprié pour le type d'objet (par exemple SELECT). En option, WITH GRANT OPTION peut être ajouté au type de droit pour tester si le droit contient cette option. De plus, plusieurs types de droits peuvent être listés en les séparant par des virgules, auquel cas le résultat sera vrai si un des droits est détenu (la casse n'est pas significative et les espaces blancs supplémentaires sont autorisés entre les noms des droits, mais pas à l'intérieur des noms.) Quelques exemples :

SELECT has_table_privilege('myschema.mytable', 'select');
SELECT has_table_privilege('joe', 'mytable', 'INSERT, SELECT WITH GRANT OPTION');

Tableau 9.64. Fonctions d'accès aux droits

Fonction

Description

has_any_column_privilege ( [ user name or oid, ] table text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour une colonne de la table ? Ceci réussit si le droit est détenu pour la table entière ou s'il est détenu par au moins une colonne de la table. Les droits autorisés sont SELECT, INSERT, UPDATE et REFERENCES.

has_column_privilege ( [ user name or oid, ] table text or oid, column text or smallint, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour la colonne spécifié de la table ? Ceci réussit si le droit est détenu pour la table entière ou s'il est détenu par cette colonne de la table. La colonne peut être spécifiée par son nom ou son numéro d'attribut (pg_attribute.attnum). Les droits autorisés sont SELECT, INSERT, UPDATE et REFERENCES.

has_database_privilege ( [ user name or oid, ] database text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour la base ? Les droits autorisés sont CREATE, CONNECT, TEMPORARY et TEMP (qui est équivalent à TEMPORARY).

has_foreign_data_wrapper_privilege ( [ user name or oid, ] fdw text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le foreign data wrapper ? Le seul droit autorisé est USAGE.

has_function_privilege ( [ user name or oid, ] function text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour la fonction ? Le seul droit autorisé est EXECUTE.

Lors de la spécification d'une fonction par nom, plutôt que par OID, l'entrée autorisée est la même que pour le type de données regprocedure (voir Section 8.19). En voici un exemple :

SELECT has_function_privilege('joeuser', 'myfunc(int, text)', 'execute');

has_language_privilege ( [ user name or oid, ] language text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le langage ? Le seul droit autorisé est USAGE.

has_schema_privilege ( [ user name or oid, ] schema text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le schéma ? Les droits autorisés sont CREATE et USAGE.

has_sequence_privilege ( [ user name or oid, ] sequence text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour la séquence ? Les droits autorisés sont USAGE, SELECT et UPDATE.

has_server_privilege ( [ user name or oid, ] server text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le serveur distant ? Le seul droit autorisé est USAGE.

has_table_privilege ( [ user name or oid, ] table text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour la table ? Les droits autorisés sont SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES et TRIGGER.

has_tablespace_privilege ( [ user name or oid, ] tablespace text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le tablespace ? Le seul droit autorisé est CREATE.

has_type_privilege ( [ user name or oid, ] type text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le type de données ? Le seul droit autorisé est USAGE. Lors de la spécification d'un type par son nom plutôt que par son OID, l'entrée autorisée est la même que pour le type de données regtype (voir Section 8.19).

pg_has_role ( [ user name or oid, ] role text or oid, privilege text ) → boolean

Est-ce que l'utilisateur a le droit pour le rôle ? Les droits autorisés sont MEMBER et USAGE. MEMBER dénote une appartenance de groupe directe ou indirecte dans le rôle (autrement dit, le droit d'exécuter SET ROLE), alors que USAGE dénote si les droits de ce rôle sont immédiatement disponibles sans exécuter SET ROLE. Cette fonction n'autorise pas le cas spécial de configurer user à public, car le pseudo-rôle PUBLIC ne peut jamais être un membre d'un vrai rôle.

row_security_active ( table text or oid ) → boolean

Est-ce que la sécurité niveau ligne est active pour la table dans le contexte de l'utilisateur et de l'environnement actuels ?


Tableau 9.65 montre les opérateurs disponibles pour le type aclitem, qui est la représentation catalogue pour les droits d'accès. Voir Section 5.7 pour des informations sur la lecture des droits d'accès.

Tableau 9.65. Opérateurs aclitem

Opérateur

Description

Exemple(s)

aclitem = aclitemboolean

Est-ce que les aclitem sont identiques ? (Notez que le type aclitem manque de l'ensemble habituel d'opérateurs de comparaison ; il n'a que l'égalité. Cependant, les tableaux aclitem peuvent seulement être comparés par égalité.)

'calvin=r*w/hobbes'::aclitem = 'calvin=r*w*/hobbes'::aclitemf

aclitem[] @> aclitemboolean

Est-ce que le tableau contient les droits indiqués ? (Ceci vaut true s'il existe une entrée de tableau qui correspond à l'aclitem et a au moins l'ensemble indiqué de droits.)

'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] @> 'calvin=r*/hobbes'::aclitemt

aclitem[] ~ aclitemboolean

Alias obsolète pour @>.

'{calvin=r*w/hobbes,hobbes=r*w*/postgres}'::aclitem[] ~ 'calvin=r*/hobbes'::aclitemt


Tableau 9.65 montre quelques fonctions supplémentaires pour la gestion du type aclitem.

Tableau 9.66. Fonctions aclitem

Fonction

Description

acldefault ( type "char", ownerId oid ) → aclitem[]

Construit un tableau d'aclitem détenant les droits d'accès par défaut d'un objet de type type appartenant au rôle d'OID ownerId. Ceci représente les droits d'accès supposés quand une entrée ACL d'un objet est NULL. (Les droits d'accès par défaut sont décrits dans Section 5.7.) Le paramètre type doit faire partie de 'c' pour COLUMN, 'r' pour TABLE ainsi que les objets de type table, 's' pour SEQUENCE, 'd' pour DATABASE, 'f' pour FUNCTION ou PROCEDURE, 'l' pour LANGUAGE, 'L' pour LARGE OBJECT, 'n' pour SCHEMA, 't' pour TABLESPACE, 'F' pour FOREIGN DATA WRAPPER, 'S' pour FOREIGN SERVER, ou 'T' pour TYPE ou DOMAIN.

aclexplode ( aclitem[] ) → setof record ( grantor oid, grantee oid, privilege_type text, is_grantable boolean )

Renvoie le tableau the aclitem sous la forme d'un ensemble de lignes. Si le bénéficiaire est le pseudo-rôle PUBLIC, il est représenté par zéro dans la colonne grantee. Chaque droit donné est représenté sous la forme SELECT, INSERT, etc. Notez que chaque droit est séparé sur sa propre ligne, donc un seul mot clé apparaît dans la colonne privilege_type.

makeaclitem ( grantee oid, grantor oid, privileges text, is_grantable boolean ) → aclitem

Construit un aclitem avec les propriétés données.


Tableau 9.67 montre les fonctions qui déterminent si un certain objet est visible dans le chelub de recherche de schémas courant. Par exemple, une table est dite visible si le schéma qui la contient est dans le chemin de recherche. C'est équivalent au fait que la table doit être référencée par nom sans qualification explicite par d'un schéma. De ce fait, pour lister les noms des tables visibles :

SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);

Pour les fonctions et opérateurs, un objet dans le chemin de recherche est dit visible si aucun objet du même nom et du même type se trouve avant dans le chemin. Pour les classes et familles d'opérateur, le nom et la méthode d'accès associé de l'index sont considérés.

Tableau 9.67. Fonctions de vérification de la visibilité

Fonction

Description

pg_collation_is_visible ( collation oid ) → boolean

La collation est-elle visible dans le chemin de recherche ?

pg_conversion_is_visible ( conversion oid ) → boolean

La conversion est-elle visible dans le chemin de recherche ?

pg_function_is_visible ( function oid ) → boolean

La fonction est-elle visible dans le chemin de recherche ? (Ceci fonctionne aussi pour les procédures et les agrégats.)

pg_opclass_is_visible ( opclass oid ) → boolean

La classe d'opérateur est-elle visible dans le chemin de recherche ?

pg_operator_is_visible ( operator oid ) → boolean

L'opérateur est-il visible dans le chemin de recherche ?

pg_opfamily_is_visible ( opclass oid ) → boolean

La famille d'opérateur est-elle visible dans le chemin de recherche ?

pg_statistics_obj_is_visible ( stat oid ) → boolean

L'objet statistique est-il visible dans le chemin de recherche ?

pg_table_is_visible ( table oid ) → boolean

La table est-elle visible dans le chemin de recherche ? (Cela fonctionne aussi pour tous les types de relations, ceci incluant les vues, les vues matérialisées, les séquences et les tables externes.)

pg_ts_config_is_visible ( config oid ) → boolean

La configuration de recherche plein texte est-elle visible dans le chemin de recherche ?

pg_ts_dict_is_visible ( dict oid ) → boolean

Le dictionnaire de recherche plein texte est-il visible dans le chemin de recherche ?

pg_ts_parser_is_visible ( parser oid ) → boolean

L'analyseur de recherche plein texte est-il visible dans le chemin de recherche ?

pg_ts_template_is_visible ( template oid ) → boolean

Le modèle de recherche plein texte est-il visible dans le chemin de recherche ?

pg_type_is_visible ( type oid ) → boolean

Le type (ou domaine) est-il visible dans le chemin de recherche ?


Toutes ces fonctions requièrent les OID des objets pour identifier l'objet à vérifier. Si vous voulez tester un objet par son nom, il est préférable d'utiliser les types d'alias de l'OID (regclass, regtype, regprocedure, regoperator, regconfig ou regdictionary), par exemple :

SELECT pg_type_is_visible('myschema.widget'::regtype);

Notez qu'il n'y aurait pas de sens à tester un nom de type non qualifié par son schéma de cette façon -- si le nom peut être reconnu, c'est qu'il est visible.

Tableau 9.68 liste les fonctions qui extraient des informations des catalogues systèmes.

Tableau 9.68. Fonctions d'information sur les catalogues systèmes

Fonction

Description

format_type ( type oid, typemod integer ) → text

Renvoie le nom SQL pour un type de données identifié par l'OID type et potentiellement par un modifieur de type. Envoyez NULL pour le modifieur si aucun modifieur spécifique n'est connu.

pg_get_constraintdef ( constraint oid [, pretty boolean ] ) → text

Reconstruit la commande de création pour une contrainte. (Ceci est une reconstruction décompilée, pas le texte original de la commande.)

pg_get_expr ( expr pg_node_tree, relation oid [, pretty boolean ] ) → text

Décompile la forme interne de l'expression stockée dans les catalogues systèmes, telle que la valeur par défaut pour une colonne. Si l'expression peut contenir Vars, indiquez l'OID de la relation à laquelle elles font référence dans le deuxième paramètre ; si aucun Var n'est attendu, indiquer 0 est suffisant.

pg_get_functiondef ( func oid ) → text

Reconstruit la commande de création pour une fonction ou une procédure. (C'est une reconstruction décompilée, pas le texte original de la commande.) Le résultat est une instruction complète, CREATE OR REPLACE FUNCTION ou CREATE OR REPLACE PROCEDURE.

pg_get_function_arguments ( func oid ) → text

Reconstruit la liste d'argument d'une fonction ou procédure, dans la forme où elle devrait apparaître dans un CREATE FUNCTION (en incluant les valeurs par défaut).

pg_get_function_identity_arguments ( func oid ) → text

Reconstruit la liste d'arguments nécessaire pour identifier une fonction ou une procédure, sous la forme nécessaire pour intégrer une commande telle que ALTER FUNCTION. Cette forme omet les valeurs par défaut.

pg_get_function_result ( func oid ) → text

Reconstruit la clause RETURNS d'une function, dans la forme nécessaire pour apparaçitre dans CREATE FUNCTION. Renvoie NULL pour une procédure.

pg_get_indexdef ( index oid [, column integer, pretty boolean ] ) → text

Reconstruit la commande de création pour un index (C'est une reconstruction décompilée, et non pas le texte original de la commande.) Si column est fourni et est différent de zéro, seule la définition de cette colonne est reconstruite.

pg_get_keywords () → setof record ( word text, catcode "char", catdesc text )

Renvoie un ensemble d'enregistrements décrivant les mots clés SQL reconnus par le serveur. La colonne word contient le mot clé. La colonne catcode contient un code de catégorie : U pour un mot clé non réservé, C pour un mot clé qui peut être un nom de colonne, T pour un mot clé qui peut être un nom de type ou de fonction, R pour un mot totalement réservé. La colonne catdesc contient une chaîne potentiellement localisée décrivant la catégorie.

pg_get_ruledef ( rule oid [, pretty boolean ] ) → text

Reconstruit la commande de création pour une règle. (C'est une reconstruction décompilée, et non pas le texte original de la commande.)

pg_get_serial_sequence ( table text, column text ) → text

Renvoie le nom de la séquence associée à une colonne ou NULL si aucune séquence n'est associée à la colonne. Si la colonne est une colonne identité, la séquence associée est la séquence créée en interne pour cette colonne. Pour les colonnes créées en utilisant un des types serial (serial, smallserial, bigserial), il s'agit de la séquence crée pour la définition de la colonne serial. Dans ce dernier cas, l'association peut être modifiée ou supprimée avec ALTER SEQUENCE OWNED BY. (Cette fonction aurait due s'appeler pg_get_owned_sequence ; son nom actuel reflète le fait qu'elle était historiquement utilisée avec des colonnes serial.) Le premier paramètre est un nom de tableau avec le schéma en option, et le deuxième paramètre est un nom de colonne. Comme le premier paramètre contient potentiellement un nom de schéma et un nom de table, il est analysé sauivant les règles SQL habituelles, signifiant qu'il est mis en minuscule par défaut. Le second paramètre, étant juste un nom de colonne, est traité littéralement et conserve donc sa casse. Le résultat est formaté de façon convenable pour être donné à des fonctions de séquence (voir Section 9.17).

Une utilisation typique est la lecture de la valeur actuelle d'une séquence pour une colonne identité ou serial. Par exemple :

SELECT currval(pg_get_serial_sequence('sometable', 'id'));

pg_get_statisticsobjdef ( statobj oid ) → text

Reconstruit le commande de création d'un objet statistique étendu. (Ceci est une reconstruction décompilée, par le texte de la commande originale.)

pg_get_triggerdef ( trigger oid [, pretty boolean ] ) → text

Reconstruit la commande de création d'un trigger. (Ceci est une reconstruction décompilée, par le texte de la commande originale.)

pg_get_userbyid ( role oid ) → name

Renvoie le nom d'un rôle d'après son OID.

pg_get_viewdef ( view oid [, pretty boolean ] ) → text

Reconstruit la commande SELECT sous-jacente pour une vue ou une vue matérialisée. (Ceci est une reconstruction décompilée, par le texte de la commande originale.)

pg_get_viewdef ( view oid, wrap_column integer ) → text

Reconstruit la commande SELECT sous-jacente pour une vue ou une vue matérialisée. (Ceci est une reconstruction décompilée, par le texte de la commande originale.) Dans cette forme de la fonction, l'affichage joli est toujours activé, et les longues lignes sont coupées pour essayer de les conserver plus petites que le nombre indiqué de colonnes.

pg_get_viewdef ( view text [, pretty boolean ] ) → text

Reconstruit la commande SELECT sous-jacente pour une vue ou une vue matérialisée, en travaillant à partir d'un nom pour la vue plutôt que de son OID. (Ceci est obsolète ; utilisez la variante OID à la place.)

pg_index_column_has_property ( index regclass, column integer, property text ) → boolean

Teste si une colonne d'index a la propriété nommée. Les propriétés communes de colonne d'index sont listées dans Tableau 9.69. (Notez que les méthodes d'accès d'extension peuvent définir des noms de propriété supplémentaires pour leurs index.) NULL est renvoyé si le nom de la propriété n'est pas connu ou ne s'applique pas à l'objet particulier ou si l'OID ou le numéro de colonne n'identifie pas un objet valide.

pg_index_has_property ( index regclass, property text ) → boolean

Teste si un index a la propriété nommée. Les propriétés communes d'index sont listées dans Tableau 9.70. (Notez que les méthodes d'accès d'extension peuvent définir des noms de propriété supplémentaires pour leurs index.) NULL est renvoyé si le nom de la propriété n'est pas connu ou ne s'applique pas à l'objet particulier ou si l'OID n'identifie pas un objet valide.

pg_indexam_has_property ( am oid, property text ) → boolean

Teste si une méthode d'accès aux index a la propriété nommée. Les propriétés communes des méthodes d'accès aux index sont listées dans Tableau 9.71. NULL est renvoyé si le nom de la propriété n'est pas connu ou ne s'applique pas à l'objet particulier ou si l'OID n'identifie pas un objet valide.

pg_options_to_table ( reloptions text[] ) → setof record ( option_name text, option_value text )

Renvoie l'ensemble d'options de stockage représenté par une valeur à partir de pg_class.reloptions ou pg_attribute.attoptions.

pg_tablespace_databases ( tablespace oid ) → setof oid

Renvoie l'ensemble d'OID des bases ayant des objets dans le tablespace indiqué. Si cette fonction renvoie des lignes, le tablespace n'est pas vide et ne peut pas être supprimé. Pour identifier les objets spécifiques peuplant le tablespace, vous aurez besoin de vous connecter aux bases identifiées par pg_tablespace_databases et de requêter leurs catalogues pg_class.

pg_tablespace_location ( tablespace oid ) → text

Renvoie le chemin du système de fichiers où ce tablespace est situé.

pg_typeof ( "any" ) → regtype

Renvoie l'OID du type de données de la valeur qui lui est fournie. Ceci peut être utile pour débogguer ou pour construire dynamiquement des requêtes SQL. Cette fonction est déclarée renvoyer le type regtype, qui est un alias d'OID pour les objets types de données (voir Section 8.19) ; ceci signifie qu'il est identique à un OID pour des comparaisons mais qu'il s'affiche sous la forme du nom du type.

Par exemple :

SELECT pg_typeof(33);
 pg_typeof
-----------
 integer

SELECT typlen FROM pg_type WHERE oid = pg_typeof(33);
 typlen
--------
      4

COLLATION FOR ( "any" ) → text

Renvoie le nom de la collation de la valeur qui lui est fournie. La valeur est entre guillemet et qualifiée du schéma si nécessaire. Si aucune collation n'a été dérivée de l'expression de l'argument, alors NULL est renvoyée. Si l'argument n'est pas un type de données collationnable, alors une erreur est levée.

Par exemple :

SELECT collation for (description) FROM pg_description LIMIT 1;
 pg_collation_for
------------------
 "default"

SELECT collation for ('foo' COLLATE "de_DE");
 pg_collation_for
------------------
 "de_DE"

to_regclass ( text ) → regclass

Traduit un nom de relation en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regclass (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regcollation ( text ) → regcollation

Traduit un nom de collation en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regcollation (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regnamespace ( text ) → regnamespace

Traduit un nom de schéma en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regnamespace (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regoper ( text ) → regoper

Traduit un nom d'opérateur en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regoper (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regoperator ( text ) → regoperator

Traduit un nom d'opérateur en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regoperator (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regproc ( text ) → regproc

Traduit un nom de fonction ou procédure en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regproc (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regprocedure ( text ) → regprocedure

Traduit un nom de fonction ou procédure en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regprocedure (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regrole ( text ) → regrole

Traduit un nom de rôle en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regrole (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.

to_regtype ( text ) → regtype

Traduit un nom de type en son OID. Un résultat similaire est obtenu en convertissant la chaîne dans le type regtype (voir Section 8.19) ; néanmoins, cette fonction renverra NULL plutôt que de lever une erreur si le nom n'est pas trouvé. De plus, contrairement à la conversion, ceci n'accepte pas un OID numérique en entrée.


La plupart des fonctions qui reconstruisent (décompilent) des objets de base ont un drapeau pretty, qui à true, cause que le résultat soit « joliment affiché ». Un bel affichage supprime les parenthèses inutiles et ajoute des espaces blancs pour la lisibilité. Ce format est plus lisible mais le format par défaut a plus de chance d'être interprété de la même façon par les versions futures de PostgreSQL ; pour éviter d'utiliser une sortie joliment affichée pour les sauvegardes. Configurer false pour le paramètre pretty donne le même résultat que d'omettre le paramètre.

Tableau 9.69. Propriétés des colonnes d'un index

NomDescription
ascEst-ce que la colonne trie en ordre ascendant sur un parcours en avant ?
descEst-ce que la colonne trie en ordre descendant sur un parcours en avant ?
nulls_firstEst-ce que la colonne trie les valeurs NULL en premier sur un parcours en avant ?
nulls_lastEst-ce que la colonne trie les valeurs NULL en dernier sur un parcours en avant ?
orderableEst-ce que la colonne possède un ordre de tri défini ?
distance_orderableEst-ce que la colonne peut être parcourue en ordre par un opérateur « distance », par exemple ORDER BY col <-> constant ?
returnableEst-ce que la valeur de la colonne peut être renvoyée par un parcours d'index seul ?
search_arrayEst-ce que la colonne supporte nativement les recherches col = ANY(array) ?
search_nullsEst-ce que la colonne supporte les recherches IS NULL et IS NOT NULL ?

Tableau 9.70. Propriétés des index

NomDescription
clusterableL'index peut-il être utilisé dans une commande CLUSTER ?
index_scanL'index supporte-t-il les parcours simples (non bitmap) ?
bitmap_scanL'index supporte-t-il les parcours bitmap ?
backward_scanEst-ce que la direction du parcours peut être changée en milieu de parcours (pour accepter FETCH BACKWARD sur un curseur sans nécessiter de matérialisation) ?

Tableau 9.71. Propriétés des méthodes d'accès aux index

NomDescription
can_orderEst-ce que la méthode d'accès supporte ASC, DESC et les autres mots-clés dans CREATE INDEX ?
can_uniqueEst-ce que la méthode d'accès supporte les index d'unicité ?
can_multi_colEst-ce que la méthode d'accès supporte les index multi-colonnes ?
can_excludeEst-ce que la méthode d'accès supporte les contraintes d'exclusion ?
can_includeEst-ce que la méthode d'accès supporte la clause INCLUDE de CREATE INDEX ?

Tableau 9.72 liste les fonctions relatives à l'identification et l'adressage des objets de la base.

Tableau 9.72. Fonctions d'information et d'adressage des objets

Fonction

Description

pg_describe_object ( classid oid, objid oid, objsubid integer ) → text

Renvoie une description textuelle d'un objet de base identifié par un OID de catalogue, un OID d'objet, et un identifiant de sous-objet (tel que le numéro de colonne dans une table ; cet identifiant vaut zéro lorsqu'il référence un objet complet). Cette description a pour but d'être lisible par un humain, et pourrait être traduite, suivant la configuration du serveur. C'est particulièrement utile pour déterminer l'identité d'un objet référencé dans le catalogue pg_depend.

pg_identify_object ( classid oid, objid oid, objsubid integer ) → record ( type text, schema text, name text, identity text )

Renvoie une ligne contenant suffisamment d'informations pour identifier de façon unique l'objet de la base spécifié par un OID de catalogue, un OID d'objet et un identifiant de sous-objet. Cette information a pour but d'être lisible par un logiciel et n'est jamais traduite. type identifie le type d'objet de base ; schema est le nom du schéma auquel l'objet appartient ou NULL pour les types d'objet n'appartenant pas à des schémas ; name est le nom de l'objet, entre guillemets si nécessaire, si le nom (avec le nom du schéma le cas échéant) est suffisant pour identifier de façon unique l'objet, et NULL sinon ; identity est l'identité complète de l'objet, avec le format précis dépendant du type d'objet, et chaque nom dans le format habituel (qualification avec le schéma et guillemets doubles si nécessaire).

pg_identify_object_as_address ( classid oid, objid oid, objsubid integer ) → record ( type text, object_names text[], object_args text[] )

Renvoie une ligne contenant suffisamment d'informations pour identifier de façon unique l'objet de la base spécifié par un OID de catalogue, un OID d'objet et un identifiant de sous-objet. L'information renvoyé est indépendante du serveur, autrement dit il pourrait être utilisé pour idenfier un objet pareillement nommé sur un autre serveur. type identifie le type d'objet de base ; object_names et object_args sont des tableaux de texte qui forment ensemble une référence à l'objet. Ces trois valeurs peuvent être passées à pg_get_object_address pour obtenir l'adresse interne de l'objet.

pg_get_object_address ( type text, object_names text[], object_args text[] ) → record ( classid oid, objid oid, objsubid integer )

Renvoie une ligne contenant suffisamment d'informations pour identifier de façon unique l'objet de base spécifié par le code type et le nom d'objet et les tableaux d'arguments. Les valeurs renvoyées sont celles qui seraient utilisées dans les catalogues systèmes tels que pg_depend ; elles peuvent être fournies à d'autres fonctions systèmes telles que pg_describe_object ou pg_identify_object. classid est l'OID du catalogue système contenant l'objet ; objid est l'OID de l'objet lui-même et objsubid est l'identifiant du sous-objet ou 0 si aucun. Cette fonction est l'inverse de pg_identify_object_as_address.


Les fonctions listées dans Tableau 9.73 extraient les commentaires préalablement enregistrés avec la commande COMMENT. Une valeur NULL est renvoyée si aucun commentaire n'a été trouvé pour les paramètres donnés.

Tableau 9.73. Fonctions d'informations sur les commentaires

Fonction

Description

col_description ( table oid, column integer ) → text

Renvoie le commentaire pour une colonne de table, qui est spécifié par l'OID de la table et le numéro de colonne. (obj_description ne peut être utilisé pour les colonnes d'une table car les colonnes n'ont pas d'OID propre.)

obj_description ( object oid, catalog name ) → text

Renvoie le commentaire pour un objet de la base qui est spécifié par son OID et le nom du catalogue système le contenant. Par exemple, obj_description(123456, 'pg_class') récupérera le commentaire de la table d'OID 123456.

obj_description ( object oid ) → text

Renvoie le commentaire pour un objet de la base spécifié par son seul OID. Cette fonction est obsolète cat il n'existe aucune garantie que les OID soient uniques entre différents catalogues systèmes ; de ce fait, un mauvais commentaire pourrait être renvoyé.

shobj_description ( object oid, catalog name ) → text

Renvoie le commentaire pour un objet de base partagé, spécifié par son OID et le nom du catalogue système le contenant. C'est comme obj_description, sauf que c'est utilisé pour récupérer les commentaires sur les objets partagés (donc les bases, les rôles et les tablespaces). Certains catalogues systèmes sont globaux à toutes les bases d'une instance, et les descriptions de ces objects sont stockées là-aussi globalement.


Les fonctions listées dans Tableau 9.74 fournissent des informations sur la transaction serveur dans un format exportable. L'utilisation principale de ces fonctions est de déterminer les transactions validées entre deux images de base.

Tableau 9.74. Fonctions d'identifiants de transaction et d'informations sur les images de base

Fonction

Description

pg_current_xact_id () → xid8

Renvoie l'identifiant actuel de la transaction. Il sera affecté si la transaction n'en a pas déjà un (ceci arrive si elle n'a pas encore réalisé d'écritures sur la base).

pg_current_xact_id_if_assigned () → xid8

Renvoie l'identifiant actuel de la transaction ou NULL si aucun identifiant n'a encore été assigné. (Il est préférable d'utiliser cette variante si la transaction est habituellement en lecture seule pour éviter de consommer inutilement un identifiant de transaction.)

pg_xact_status ( xid8 ) → text

Renvoie le statut de validation d'une transaction récente. Le résultat fait partie de in progress, committed ou aborted, en supposant que la transaction est suffisamment récente pour que le système dispose du statut de validation de cette transaction. S'il est assez ancien pour qu'aucune référence de la transaction n'est survécu au système et que le statut de validation ait disparu, le résultat est NULL. Les applications peuvent utiliser cette fonction pour déterminer, par exemple, si leur transaction a été validée ou annulée si l'application a été déconnectée alors qu'un COMMIT était en cours. Notez que les transactions préparées sont rapportés en cours ; les applications doivent vérifier pg_prepared_xacts si elles ont besoin de savoir si un identifiant de transaction appartient à une transaction préparée.

pg_current_snapshot () → pg_snapshot

Renvoie un snapshot (image) actuel, une structure de données indiquant les identifiants de transaction actuellement en cours.

pg_snapshot_xip ( pg_snapshot ) → setof xid8

Renvoie l'ensemble des identifiants de transactions en cours contenu dans un snapshot (image de base).

pg_snapshot_xmax ( pg_snapshot ) → xid8

Renvoie le xmax d'une image de base.

pg_snapshot_xmin ( pg_snapshot ) → xid8

Renvoie le xmin d'une image de base

pg_visible_in_snapshot ( xid8, pg_snapshot ) → boolean

Est-ce que l'identifiant de transaction donné est visible d'après cette image de base (autrement dit, est-il terminé avant que l'image ne soit réalisée) ? Notez que cette fonction ne renverra pas la bonne réponse pour un identifiant de sous-transaction.


Le type interne des identifiants de transaction, xid, est sur 32 bits et boucle tous les 4 milliards de transactions. Néanmoins, les fonctions listées dans Tableau 9.74 utilisent un type xid8 sur 64 bits qui ne boucle pas sur toute la durée de vie d'une instance, et qui peut être converti en xid par conversion si nécessaire. Le type de données pg_snapshot enregistre des informations sur la visibilité des identifiants de transaction à un moment particulier. Ses composants sont décrits dans Tableau 9.75. La représentation textuelle de pg_snapshot est xmin:xmax:xip_list. Par exemple, 10:20:10,14,15 signifie xmin=10, xmax=20, xip_list=10, 14, 15.

Tableau 9.75. Composants d'image de base

NomDescription
xmin Plus petit identifiant de transaction toujours actif. Tous les identifiants de transaction inférieurs à xmin sont soit validés et visibles, soit annulés et morts.
xmax L'identifiant de transaction après le dernier identifiant terminé. Tous les identifiants de transaction supérieurs ou égals à xmax ne sont pas encore terminés au moment de la création de l'image, et sont de ce fait invisibles.
xip_list Transactions en cours au moment de la création de l'image de base. Un identifiant de transaction qui est xmin <= X < xmax et qui n'est pas dans cette liste a déjà été terminé au moins de la création de l'image et, de ce fait, est soit visible soit mort suivant son statut de validation. Cette liste n'inclut pas les identifiants de transaction des sous-transactions.

Dans les versions de PostgreSQL antérieures à la 13, le type xid8 n'existait pas, donc des variantes de ces fonctions étaient fournies. Elles utilisaient le type bigint pour représenter un identifiant sur 64 bits, avec un type de données pour l'image nommé txid_snapshot. Ces anciennes fonctions avaient le mot txid dans leur nom. Elles sont toujours acceptées pour des raisons de compatibilité ascendante, mais pourraient être supprimées dans une version future. Voir Tableau 9.76.

Tableau 9.76. Fonctions obsolètes sur les identifiants de transactions et les informations sur les images de base

Fonction

Description

txid_current () → bigint

Voir pg_current_xact_id().

txid_current_if_assigned () → bigint

Voir pg_current_xact_id_if_assigned().

txid_current_snapshot () → txid_snapshot

Voir pg_current_snapshot().

txid_snapshot_xip ( txid_snapshot ) → setof bigint

Voir pg_snapshot_xip().

txid_snapshot_xmax ( txid_snapshot ) → bigint

Voir pg_snapshot_xmax().

txid_snapshot_xmin ( txid_snapshot ) → bigint

Voir pg_snapshot_xmin().

txid_visible_in_snapshot ( bigint, txid_snapshot ) → boolean

Voir pg_visible_in_snapshot().

txid_status ( bigint ) → text

Voir pg_xact_status().


Les fonctions montrées dans Tableau 9.77 fournissent des informations sur le moment où d'anciennes transactions ont été validées. Elles fournissent des informations utiles seulement quand le paramètre track_commit_timestamp est activé, et seulement pour les transactions qui ont été validées après l'activation du paramètre.

Tableau 9.77. Fonctions d'informations sur les transactions validées

Fonction

Description

pg_xact_commit_timestamp ( xid ) → timestamp with time zone

Renvoie l'horodatage de validation d'une transaction.

pg_last_committed_xact () → record ( xid xid, timestamp timestamp with time zone )

Renvoie l'identifiant de transaction et l'horodatage de sa validation pour la dernière transaction validée.


Les fonctions listées dans Tableau 9.78 affichent des informations initialisées lors de l'exécution de la commande initdb, telle que la version du catalogue. Elles affichent aussi des informations sur les écritures dans les journaux de transactions et le traitement des checkpoints. Ces informations sont globales à l'instance, et non pas spécifique à une base. Ces fonctions fournissent la plupart des informations en utilisant la mêle source que l'application pg_controldata.

Tableau 9.78. Fonctions des données de contrôle

Fonction

Description

pg_control_checkpoint () → record

Renvoie des informations sur l'état du checkpoint en cours, comme indiqué dans Tableau 9.79.

pg_control_system () → record

Renvoie des informations sur l'état du fichier de contrôle en cours, comme indiqué dans Tableau 9.80.

pg_control_init () → record

Renvoie des informations sur l'état d'initialisation de l'instance, comme indiqué dans Tableau 9.81.

pg_control_recovery () → record

Renvoie des informations sur l'état de restauration, comme indiqué dans Tableau 9.82.


Tableau 9.79. Colonnes en sortie de pg_control_checkpoint

Nom de la colonneType de données
checkpoint_lsnpg_lsn
redo_lsnpg_lsn
redo_wal_filetext
timeline_idinteger
prev_timeline_idinteger
full_page_writesboolean
next_xidtext
next_oidoid
next_multixact_idxid
next_multi_offsetxid
oldest_xidxid
oldest_xid_dbidoid
oldest_active_xidxid
oldest_multi_xidxid
oldest_multi_dbidoid
oldest_commit_ts_xidxid
newest_commit_ts_xidxid
checkpoint_timetimestamp with time zone

Tableau 9.80. Colonnes en sortie de pg_control_system

Nom de colonneType de données
pg_control_versioninteger
catalog_version_nointeger
system_identifierbigint
pg_control_last_modifiedtimestamp with time zone

Tableau 9.81. Colonnes en sortie de pg_control_init

Nom de colonneType de données
max_data_alignmentinteger
database_block_sizeinteger
blocks_per_segmentinteger
wal_block_sizeinteger
bytes_per_wal_segmentinteger
max_identifier_lengthinteger
max_index_columnsinteger
max_toast_chunk_sizeinteger
large_object_chunk_sizeinteger
float8_pass_by_valueboolean
data_page_checksum_versioninteger

Tableau 9.82. Colonnes en sortie de pg_control_recovery

Nom de colonneType de données
min_recovery_end_lsnpg_lsn
min_recovery_end_timelineinteger
backup_start_lsnpg_lsn
backup_end_lsnpg_lsn
end_of_backup_record_requiredboolean