PostgreSQLLa base de données la plus sophistiquée au monde.

9.22. Fonctions d'informations système

Le Tableau 9.44, « Fonctions d'information de session » présente diverses fonctions qui extraient des informations de session et 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 système. Voir Section 26.2.2, « Visualiser les statistiques récupérées » pour plus d'informations.

Tableau 9.44. Fonctions d'information de session

Nom Type de retour Description
current_database() nom nom de la base de données courante
current_schema() nom nom du schéma courant
current_schemas(boolean) nom[] nom des schémas dans le chemin de recherche, avec optionnellement les schémas implicites
current_user nom nom d'utilisateur du contexte d'exécution courant
inet_client_addr() inet adresse de la connexion distante
inet_client_port() int port de la connexion distante
inet_server_addr() inet adresse de la connexion locale
inet_server_port() int port de la connexion locale
pg_my_temp_schema() oid OID du schéma temporaire de la session, 0 si aucun
pg_is_other_temp_schema(oid) boolean s'agit-il du schéma temporaire d'une autre session ?
pg_postmaster_start_time() timestamp with time zone heure de démarrage du serveur
session_user name nom de l'utilisateur de session
user name équivalent à current_user
version() text informations de version de PostgreSQL

session_user est habituellement l'utilisateur qui a initié la connexion à la base de données ; mais les superutilisateurs peuvent modifier ce paramétrage avec SET SESSION AUTHORIZATION. current_user est l'identifiant de l'utilisateur, utilisable pour les vérifications de permissions. Il est habituellement identique à l'utilisateur de la session, mais il peut être modifié avec SET ROLE. Il change aussi pendant l'exécution des fonctions comprenant l'attribut SECURITY DEFINER. En langage Unix, l'utilisateur de la session est le « real user » (NdT : l'utilisateur réel) et l'utilisateur courant est l'« effective user » (NdT : l'utilisateur effectif) .

[Note]

Note

current_user, session_user et user ont un statut syntaxique spécial en SQL : ils doivent être appelés sans parenthèses à droite.

current_schema renvoie le nom du premier schéma dans le chemin de recherche (ou une valeur NULL si ce dernier est vide). C'est le schéma utilisé pour toute création de table ou autre objet nommé sans précision d'un schéma cible. current_schemas(boolean) renvoie un tableau qui contient les noms de tous les schémas du chemin de recherche. L'option booléenne indique si les schémas système implicitement inclus, comme pg_catalog, doivent être inclus dans le chemin de recherche retourné.

[Note]

Note

Le chemin de recherche est modifiable à l'exécution. La commande est :

SET search_path TO schema [, schema, ...]

inet_client_addr renvoie l'adresse IP du client courant et inet_client_port le numéro du port. inet_server_addr renvoie l'adresse IP sur laquelle le serveur a accepté la connexion courante et inet_server_port le numéro du port. Toutes ces fonctions renvoient NULL si la connexion courante est établie via une socket de domaine Unix.

pg_my_temp_schema renvoie l'OID du schéma temporaire de la session courante, ou 0 s'il n'existe pas (parce qu'il n'y a pas eu de création de tables temporaires). pg_is_other_temp_schema renvoie true si l'OID donné est l'OID d'un schéma temporaire d'une autre session. (Ceci peut être utile pour exclure les tables temporaires d'autres sessions lors de l'affichage d'un catalogue, par exemple.)

pg_postmaster_start_time renvoie la date et l'heure (type timestamp with time zone) de démarrage du serveur.

version renvoie une chaîne qui décrit la version du serveur PostgreSQL™.

Le Tableau 9.45, « Fonctions de consultation des privilèges d'accès » liste les fonctions qui permettent aux utilisateurs de consulter les privilèges d'accès. Voir la Section 5.6, « Droits » pour plus d'informations sur les privilèges.

Tableau 9.45. Fonctions de consultation des privilèges d'accès

Nom Type de retour Description
has_database_privilege (utilisateur, base, privilège) boolean utilisateur a-t-il le privilège privilège sur base
has_database_privilege (base, privilège) boolean l'utilisateur courant a-t-il le privilège privilège sur base
has_function_privilege (utilisateur, fonction, privilège) boolean utilisateur a-t-il le privilège privilège sur fonction
has_function_privilege (fonction, privilège) boolean l'utilisateur courant a-t-il e privilège privilège sur fonction
has_language_privilege (utilisateur, langage, privilège) boolean utilisateur a-t-il le privilège privilège sur langage
has_language_privilege (langage, droit) boolean l'utilisateur courant a-t-il le privilège privilège sur langage
has_schema_privilege(utilisateur, schéma, privilège) boolean utilisateur a-t-il le privilège privilège sur schéma
has_schema_privilege(schéma, privilège) boolean l'utilisateur courant a-t-il le privilège privilège sur schéma
has_table_privilege(utilisateur, table, privilège) boolean utilisateur a-t-il le privilège privilège sur table
has_table_privilege(table, privilege) boolean l'utilisateur courant a-t-il le privilège privilège sur table
has_tablespace_privilege (utilisateur, tablespace, privilège) boolean utilisateur a-t-il le privilège privilège sur tablespace
has_tablespace_privilege (tablespace, privilège) boolean l'utilisateur courant a-t-il le privilège privilège sur tablespace
pg_has_role(utilisateur, rôle, privilège) boolean utilisateur a-t-il le privilège privilège sur rôle
pg_has_role(rôle, privilège) boolean l'utilisateur courant a-t-il le privilège privilège sur rôle

has_database_privilege vérifie si l'utilisateur possède un privilège particulier d'accès à une base de données. Ses arguments sont analogues à has_table_privilege. Les privilèges possibles sont CREATE, CONNECT, TEMPORARY ou TEMP (équivalent à TEMPORARY).

has_function_privilege vérifie si l'utilisateur possède un privilège particulier d'accès à une fonction. Ses arguments sont analogues à has_table_privilege. Si la fonction est précisée par une chaîne texte plutôt que par son OID, l'entrée autorisée est la même que pour le type de données regprocedure (voir la Section 8.16, « Types identifiant d'objet »). Le seul privilège possible est EXECUTE. Par exemple :

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

has_language_privilege vérifie si l'utilisateur possède un privilège particulier d'accès à un langage procédural. Ses arguments sont analogues à has_table_privilege. Le seul privilège possible est USAGE.

has_schema_privilege vérifie si l'utilisateur possède un privilège particulier d'accès à un schéma. Ses arguments sont analogues à has_table_privilege. Les privilèges possibles sont CREATE et USAGE.

has_table_privilege vérifie si l'utilisateur possède un privilège particulier d'accès à une table. L'utilisateur peut être indiqué par son nom ou son OID (pg_authid.oid). Si l'argument est omis, current_user est utilisé. La table peut être indiquée par son nom ou par son OID. (Il existe donc six versions de has_table_privilege qui se distinguent par le nombre et le type de leurs arguments.) Lors de l'indication par nom, il est possible de préciser le schéma. Les privilèges possibles, indiqués sous la forme d'une chaîne de caractères, sont : SELECT, INSERT, UPDATE, DELETE, REFERENCES et TRIGGER. (La casse n'a pas d'importance.) Par exemple :

SELECT has_table_privilege('monschema.matable', 'select');
 

has_tablespace_privilege vérifie si l'utilisateur possède un privilège particulier d'accès à un tablespace. Ses arguments sont analogues à has_table_privilege. Le seul privilège possible est CREATE.

pg_has_role vérifie si l'utilisateur possède un privilège particulier d'accès à un rôle. Ses arguments sont analogues à has_table_privilege. Les privilèges possible sont MEMBER et USAGE. MEMBER indique une appartenance directe ou indirecte au rôle (c'est-à-dire le droit d'exécuter SET ROLE) alors que USAGE indique que les droits du rôle sont immédiatement disponibles sans avoir à exécuter SET ROLE.

Pour tester si l'utilisateur peut accorder un privilège, on ajoute WITH GRANT OPTION au mot-clé indiquant le privilège ; par exemple 'UPDATE WITH GRANT OPTION'.

Le Tableau 9.46, « Fonctions d'interrogation de visibilité dans les schémas » affiche les fonctions qui permettent de savoir si un objet particulier est visible dans le chemin de recherche courant. Une table est dite visible si son schéma contenant est dans le chemin de recherche et qu'aucune table de même nom ne la précède dans le chemin de recherche. C'est équivalent au fait que la table peut être référencée par son nom sans qualification explicite de schéma. Par exemple, pour lister les noms de toutes les tables visibles :

SELECT relname FROM pg_class WHERE pg_table_is_visible(oid);

Tableau 9.46. Fonctions d'interrogation de visibilité dans les schémas

Nom Type de retour Description
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
pg_operator_is_visible (operator_oid) boolean l'opérateur est-il visible dans le chemin de recherche
pg_opclass_is_visible (opclass_oid) boolean la classe d'opérateur est-elle visible dans le chemin de recherche
pg_table_is_visible(table_oid) boolean la table est-elle visible dans le chemin de recherche
pg_ts_config_is_visible(config_oid) boolean la configuration de la recherche textuelle est-elle visible dans le chemin de recherche
pg_ts_dict_is_visible(dict_oid) boolean le dictionnaire de recherche textuelle est-il visible dans le chemin de recherche
pg_ts_parser_is_visible(parser_oid) boolean l'analyseur syntaxique de recherche textuelle est-il visible dans le chemin de recherche
pg_ts_template_is_visible(template_oid) boolean le modèle de recherche textuelle 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

Chaque fonction vérifie la visibilité d'un type d'objet de la base de données. pg_table_is_visible peut aussi être utilisée avec des vues, index et séquences, pg_type_is_visible avec les domaines. Pour les fonctions et les opérateurs, un objet est visible dans le chemin de recherche si aucun objet de même nom et prenant des arguments de mêmes types de données n'est précédemment présent dans le chemin de recherche. Pour les classes d'opérateurs, on considère à la fois le nom et la méthode d'accès à l'index associé.

Toutes ces fonctions nécessitent des OID pour identifier les objets à vérifier. Pour tester un objet par son nom, il est préférable d'utiliser les types d'alias d'OID (regclass, regtype, regprocedure ou regoperator). Par exemple

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

Il n'est pas très utile de tester ainsi un nom non qualifié -- si le nom peut être reconnu, c'est qu'il est visible.

Le Tableau 9.47, « Fonctions d'information du catalogue système » liste les fonctions qui extraient des informations des catalogues système.

Tableau 9.47. Fonctions d'information du catalogue système

Nom Type de retour Description
format_type (type_oid, typemod) text récupère le nom SQL d'un type de données
pg_get_constraintdef(constraint_oid) text récupère la définition d'une contrainte
pg_get_constraintdef(constraint_oid, pretty_bool) text récupère la définition d'une contrainte
pg_get_expr(expr_text, relation_oid) text décompile la forme interne d'une expression, en supposant que toutes les variables qu'elle contient font référence à la relation indiquée par le second paramètre
pg_get_expr(expr_text, relation_oid, pretty_bool) text décompile la forme interne d'une expression, en supposant que toutes les variables qu'elle contient font référence à la relation indiquée par le second paramètre
pg_get_indexdef(index_oid) text récupère la commande CREATE INDEX de l'index
pg_get_indexdef(index_oid, column_no, pretty_bool) text récupère la commande CREATE INDEX pour l'index, ou la définition d'une seule colonne d'index quand column_no ne vaut pas zéro
pg_get_ruledef(rule_oid) text récupère la commande CREATE RULE pour une règle
pg_get_ruledef(rule_oid, pretty_bool) text récupère la commande CREATE RULE de la règle
pg_get_serial_sequence(table_name, column_name) text récupère le nom de la séquence qu'une colonne serial ou bigserial utilise
pg_get_triggerdef(trigger_oid) text récupère la commande CREATE [ CONSTRAINT ] TRIGGER du déclencheur
pg_get_userbyid(roleid) name récupère le nom du rôle possédant cet ID
pg_get_viewdef(view_name) text récupère la commande SELECT sous-jacente à la vue (obsolète)
pg_get_viewdef(view_name, pretty_bool) text récupère la commande SELECT sous-jacente à la vue (obsolète)
pg_get_viewdef(view_oid) text récupère la commande SELECT sous-jacente à la vue
pg_get_viewdef(view_oid, pretty_bool) text récupère la commande SELECT sous-jacente à la vue
pg_tablespace_databases(tablespace_oid) setof oid récupère l'ensemble des OID des bases qui possèdent des objets dans ce tablespace

format_type renvoie le nom SQL d'un type de données identifié par son OID de type et éventuellement un modificateur de type. On passe NULL pour le modificateur de type si aucun modificateur spécifique n'est connu.

pg_get_constraintdef, pg_get_indexdef, pg_get_ruledef et pg_get_triggerdef reconstruisent respectivement la commande de création d'une contrainte, d'un index, d'une règle ou d'un déclencheur. (Il s'agit d'une reconstruction décompilée, pas du texte originale de la commande.) pg_get_expr décompile la forme interne d'une expression individuelle, comme la valeur par défaut d'une colonne. Cela peut être utile pour examiner le contenu des catalogues système. pg_get_viewdef reconstruit la requête SELECT qui définit une vue. La plupart de ces fonctions existent en deux versions, l'une d'elles permettant, optionnellement, d'« afficher joliment » le résultat. Ce format est plus lisible, mais il est probable que les futures versions de PostgreSQL™ continuent d'interprêter le format par défaut actuel de la même façon ; la version « jolie » doit être évitée dans les sauvegardes. Passer false pour le paramètre de « jolie » sortie conduit au même résultat que la variante sans ce paramètre.

pg_get_serial_sequence renvoie le nom de la séquence associée à une colonne ou NULL si aucune séquence n'est associée à la colonne. Le premier argument en entrée est un nom de table, éventuellement qualifié du schéma. Le second paramètre est un nom de colonne. Comme le premier paramètre peut contenir le nom du schéma et de la table, il n'est pas traité comme un identifiant entre guillemets doubles, ce qui signifie qu'il est converti en minuscules par défaut, alors que le second paramètre, simple nom de colonne, est traité comme s'il était entre guillemets doubles et sa casse est préservée. La fonction renvoie une valeur convenablement formatée pour être traitée par les fonctions de traitement des séquences (voir Section 9.15, « Fonctions de manipulation de séquences »). Cette association peut être modifiée ou supprimée avec ALTER SEQUENCE OWNED BY. (La fonction aurait probablement dû s'appeler pg_get_owned_sequence ; son nom reflète le fait qu'elle est typiquement utilisée avec les colonnes serial et bigserial.)

pg_get_userbyid récupère le nom d'un rôle d'après son OID.

pg_tablespace_databases autorise l'examen d'un tablespace. Il renvoie l'ensemble des OID des bases qui possèdent des objets stockés dans le tablespace. Si la fonction renvoie une ligne, le tablespace n'est pas vide et ne peut pas être supprimée. Pour afficher les objets spécifiques peuplant le tablespace, il est nécessaire de se connecter aux bases identifiées par pg_tablespace_databases et de requêter le catalogue pg_class.

Les fonctions affichées dans Tableau 9.48, « Fonctions d'informations sur les commentaires » extraient les commentaires stockées précédemment avec la commande COMMENT. Une valeur NULL est renvoyée si aucun commentaire ne correspond aux paramètres donnés.

Tableau 9.48. Fonctions d'informations sur les commentaires

Nom Type de retour Description
col_description(table_oid, column_number) text récupère le commentaire d'une colonne de la table
obj_description (object_oid, catalog_name) text récupère le commentaire d'un objet de la base de données
obj_description(object_oid) text récupère le commentaire d'un objet de la base de données (obsolète)
shobj_description(object_oid, catalog_name) text récupère le commentaire d'un objet partagé de la base de données

col_description renvoie le commentaire d'une colonne de table, la colonne étant précisée par l'OID de la table et son numéro de colonne. obj_description ne peut pas être utilisée pour les colonnes de table car les colonnes n'ont pas d'OID propres.

La forme à deux paramètres de obj_description renvoie le commentaire d'un objet de la base de données, précisé par son OID et le nom du catalogue système le contenant. Par exemple, obj_description(123456,'pg_class') récupère le commentaire pour la table d'OID 123456. La forme à un paramètre de obj_description ne requiert que l'OID de l'objet. Elle est maintenant obsolète car il n'existe aucune garantie que les OID soient uniques au travers des différents catalogues système ; un mauvais commentaire peut alors être renvoyé.

shobj_description est utilisé comme obj_description, mais pour les commentaires des objets partagés. Certains catalogues systèmes sont globaux à toutes les bases de données à l'intérieur de chaque cluster et leurs descriptions sont stockées globalement.

Les fonctions présentées dans Tableau 9.49, « ID de transaction et instantanés » remontent à l'utilisateur des informations de transaction de niveau interne au serveur. L'usage principal de ces fonctions est de déterminer les transactions commitées entre deux instantanés (« snapshots »).

Tableau 9.49. ID de transaction et instantanés

Nom Type retour Description
txid_current() bigint récupère l'ID de transaction courant
txid_current_snapshot() txid_snapshot récupère l'instantané courant
txid_snapshot_xmin(txid_snapshot) bigint récupère le xmin de l'instantané
txid_snapshot_xmax(txid_snapshot) bigint récupère le xmax de l'instantané
txid_snapshot_xip(txid_snapshot) setof bigint récupère l'ID de la transaction en cours dans l'instantané
txid_visible_in_snapshot(bigint, txid_snapshot) boolean l'ID de transaction est-il visible dans l'instantané ?

Le type interne ID de transaction (xid) est sur 32 bits. Il boucle donc tous les 4 milliards de transactions. Cependant, ces fonctions exportent au format 64 bits, étendu par un compteur « epoch », de façon à éviter tout cycle sur la durée de vie de l'installation. Le type de données utilisé par ces fonctions, txid_snapshot, stocke l'information de visibilité des ID de transaction à un instant particulier. Ces composants sont décrits dans Tableau 9.50, « Composants de l'instantané ».

Tableau 9.50. Composants de l'instantané

Nom Description
xmin ID de transaction (txid) le plus ancien encore actif. Toutes les transactions plus anciennes sont soient commitées et visibles, soient annulées et mortes.
xmax Premier txid non encore assigné. Tous les txids qui suivent celui-ci ne sont pas encore démarrés à ce moment de l'instantané, et donc invisibles.
xip_list txids actifs au moment de l'instantané. Ils sont tous compris entre xmin et xmax. Un txid qui est xmin <= txid < xmax et n'est pas dans la cette liste est déjà terminé à ce moment de l'instantané, et donc soit visible, soit mort, selon son statut de validation.

La représentation textuelle du txid_snapshot est xmin:xmax:xip_list. Ainsi 10:20:10,14,15 signifie xmin=10, xmax=20, xip_list=10, 14, 15.