9.19. Fonctions d'information sur le système

Le Tableau 9.40, « Fonctions d'information sur la session » affiche plusieurs fonctions qui extraient des informations de la session et du système.

Tableau 9.40. Fonctions d'information sur la session

Nom Type de retour Description
current_database() nom nom de la base de données en cours
current_schema() nom nom du schéma en cours
current_schemas(boolean) nom[] nom des schémas dans le chemin de recherche des schémas, incluant en option les schémas implicites
current_user nom nom d'utilisateur du contexte d'exécution en cours
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 ce schéma est-il le schéma temporaire d'une autre session ?
pg_postmaster_start_time() timestamp with time zone heure de lancement du serveur
session_user name nom de l'utilisateur de la session
user name équivalent à current_user
version() text informations sur la version de PostgreSQL

session_user est habituellement l'utilisateur utilisé pour 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, applicable pour les vérifications de droits. Normalement, il est 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. Dans le langage Unix, l'utilisateur de la session est le « real user » (NdT : l'utilisateur réel) et l'utilisateur en cours est l'« effective user » (NdT : l'utilisateur effectif) .

[Note]

Note

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

current_schema renvoie le nom du premier schéma sur le chemin de recherche (ou une valeur NULL si ce dernier est vide). C'est le schéma qui sera utilisé pour toute table ou tout autre objet nommé créé sans spécifier de schéma cible. current_schemas(boolean) renvoie un tableau de noms avec tous les schémas du chemin de recherche. L'option booléenne détermine si les schémas système inclus implicitement comme pg_catalog sont inclus dans le chemin de recherche renvoyé.

[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 en cours et inet_client_port renvoie le numéro du port. inet_server_addr renvoie l'adresse IP sur laquelle le serveur a accepté la connexion en cours et inet_server_port renvoie le numéro du port. Toutes ces fonctions renvoient NULL si la connexion en cours s'est établie via un socket de domaine Unix.

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

pg_postmaster_start_time renvoie la date et l'heure (type timestamp with time zone) du lancement du serveur.

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

Le Tableau 9.41, « Fonctions de demandes de droits d'accès » liste les fonctions qui permettent aux utilisateurs de demander les droits d'accès. Voir la Section 5.6, « Droits » pour plus d'informations sur les droits.

Tableau 9.41. Fonctions de demandes de droits d'accès

Nom Type de retour Description
has_database_privilege (utilisateur, base, droit) boolean l'utilisateur a-t'il des droits sur la base de données
has_database_privilege (base, droit) boolean l'utilisateur courant a-t'il des droits sur la base de données
has_function_privilege (utilisateur, fonction, droit) boolean l'utilisateur a-t'il des droits sur la fonction
has_function_privilege (fonction, droit) boolean l'utilisateur courant a-t'il des droits sur la fonction
has_language_privilege (utilisateur, langage, droit) boolean l'utilisateur a-t'il des droits sur le langage
has_language_privilege (langage, droit) boolean l'utilisateur en cours a-t'il des droits sur le langage
pg_has_role(user, role, privilege) boolean l'utilisateur a-t'il le droit d'utiliser ce rôle
has_schema_privilege(user, schema, privilege) boolean l'utilisateur a-t'il le droit pour ce schéma
has_schema_privilege(schema, privilege) boolean l'utilisateur actuel a-t'il le droit pour ce schéma
has_table_privilege(user, table, privilege) boolean l'utilisateur a-t'il des droits sur cette table
has_table_privilege(table, privilege) boolean l'utilisateur actuel a-t'il des droits sur cette table
has_tablespace_privilege (espacelogique, droit) boolean l'utilisateur en cours a-t'il des droits sur l'espace logique
pg_has_role(user, role, privilege) boolean l'utilisateur a-t'il des droits pour ce rôle
pg_has_role(role, privilege) boolean l'utilisateur actuel a-t'il des droits pour ce rôle

has_database_privilege vérifie si l'utilisateur peut accéder à une base de données d'une façon particulière. Les possibilités pour ses arguments sont analogues à has_table_privilege. Le type de droit d'accès désiré doit être évalué à CREATE, CONNECT, TEMPORARY ou TEMP (ce qui est équivalent à TEMPORARY).

has_function_privilege vérifie si un utilisateur peut accéder à une fonction d'une façon particulière. Les possibilités pour ses arguments sont analogues à has_table_privilege. En spécifiant une fonction par une chaîne texte plutôt que par son OID, l'entrée autorisée est identique au type de données regprocedure (voir la Section 8.12, « Types identifiant d'objet »). Le type de droit d'accès désiré doit s'évaluer à EXECUTE. Voici un exemple :

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

has_language_privilege vérifie si un utilisateur peut accéder à un langage de procédures d'une façon particulière. Les possibilités pour ses arguments sont analogues à has_table_privilege. Le type de droit d'accès désiré doit s'évaluer à USAGE.

has_schema_privilege vérifie si un utilisateur peut accéder à un schéma d'une façon particulière. Les possibilités pour ses arguments sont analogues à has_table_privilege. Le type de droit d'accès désiré doit s'évaluer à CREATE ou USAGE.

has_table_privilege vérifie si un utilisateur peut accéder à une table d'une façon particulière. L'utilisateur peut être indiqué par son nom ou son OID (pg_authid.oid), ou si l'argument est omis, current_user est utilisé. La table peut être indiquée par son nom ou par son OID. (Du coup, il existe six versions de has_table_privilege qui sont distinguées par le nombre et le types de leurs arguments.) En spécifiant par nom, ce dernier peut avoir le nom du schéma si nécessaire. Le type du droit d'accès désiré est indiqué par une chaîne qui doit être parmi ces dernières : SELECT, INSERT, UPDATE, DELETE, REFERENCES ou TRIGGER. (la casse n'est pas importante.) An example is:

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

has_tablespace_privilege vérifie si un utilisateur peut accéder à un tablespace d'une façon particulière. Les possibilités pour ses arguments sont analogues à has_table_privilege. Le type de droit d'accès désiré doit s'évaluer à CREATE.

pg_has_role vérifie si un utilisateur peut accéder à un rôle d'une façon particulière. Les possibilités pour ses arguments sont analogues à has_table_privilege. Le type du droit d'accès désiré doit s'évaluer à MEMBER ou USAGE. MEMBER dénote une appartenance directe ou indirecte dans le rôle (c'est-à-dire le droit de faire SET ROLE) alors que USAGE dénote le fait que les droits du rôle sont immédiatement disponibles sans exécuter SET ROLE.

Pour tester si un utilisateur détient une option grant sur le droit, ajoutez WITH GRANT OPTION au mot clé du droit ; par exemple 'UPDATE WITH GRANT OPTION'.

Le Tableau 9.42, « Fonctions de requêtes sur la visibilité dans les schémas » affiche les fonctions qui déterminent si un certain objet est visible dans le chemin de recherche en cours. Une table est dite visible si son schéma contenant est dans le chemin de recherche et qu'aucune table du même nom apparaît avant dans le chemin de recherche. Ceci est équivalent à au fait que la table peut être référencée par 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.42. Fonctions de requêtes sur la 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_type_is_visible(type_oid) boolean le type (ou domaine) est-il visible dans le chemin de recherche

pg_conversion_is_visible, pg_function_is_visible, pg_operator_is_visible, pg_opclass_is_visible, pg_table_is_visible et pg_type_is_visible réalisent la vérification de la visibilité pour les conversions, fonctions, opérateurs, classes d'opérateur, tables et types. Notez que pg_table_is_visible peut aussi être utilisé avec des vues, index et séquences ; pg_type_is_visible peut aussi être utilisé avec les domaines. Pour les fonctions et les opérateurs, un objet est visible dans le chemin de recherche si aucun objet du même nom et des mêmes types de données en argument n'arrive avant dans le chemin de recherche. Pour les classes d'opérateurs, le nom et la méthode d'accès à l'index associée sont considérés.

Toutes ces fonctions nécessitent que les OID des objets identifient l'objet à vérifier. Si vous voulez 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);

Notez qu'il n'y aurait aucun sens à tester un nom non qualifié de cette façon -- si le nom peut être reconnu, il doit être visible.

Le Tableau 9.43, « Fonctions d'information sur le catalogue système » liste les fonctions qui extraient des informations à partir des catalogues système.

Tableau 9.43. Fonctions d'information sur le catalogue système

Nom Type de retour Description
format_type (type_oid, typemod) text obtient le nom SQL d'un type de données
pg_get_constraintdef(constraint_oid) text obtient la définition d'une contrainte
pg_get_constraintdef(constraint_oid, pretty_bool) text obtient 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 tous les Vars 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 tous les Vars font référence à la relation indiquée par le second paramètre
pg_get_indexdef(index_oid) text obtient la commande CREATE INDEX pour l'index
pg_get_indexdef(index_oid, column_no, pretty_bool) text obtient la commande CREATE INDEX pour l'index, ou la définition d'un seul index d'une seule colonne d'un index quand column_no ne vaut pas zéro
pg_get_ruledef(rule_oid) text obtient la commande CREATE RULE pour une règle
pg_get_ruledef(rule_oid, pretty_bool) text obtient la commande CREATE RULE pour une règle
pg_get_serial_sequence(table_name, column_name) text obtient le nom de la séquence qu'une colonne serial ou bigserial utilise
pg_get_triggerdef(trigger_oid) text obtient la commande CREATE [ CONSTRAINT ] TRIGGER du déclencheur
pg_get_userbyid(roleid) name obtient le nom du rôle ayant cet ID
pg_get_viewdef(view_name) text obtient la commande SELECT sous-jacente pour la vue (obsolète)
pg_get_viewdef(view_name, pretty_bool) text obtient la commande SELECT sous-jacente pour la vue (obsolète)
pg_get_viewdef(view_oid) text get underlying SELECT command for view
pg_get_viewdef(view_oid, pretty_bool) text obtient la commande SELECT sous-jacente pour la vue
pg_tablespace_databases(tablespace_oid) setof oid obtient l'ensemble d'OID des bases qui ont des objets dans ce tablespace

format_type renvoie le nom SQL d'un type de données qui est identifié par son OID de type et peut-être par un modificateur de type. Passez NULL au 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 pour une contrainte, un index, une règle ou un déclencheur. (Notez qu'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 viennent en deux versions, dont une qui, en option, peut « afficher joliment » le résultat. Ce format est plus lisible mais le format par défaut est plus facilement interprétable de la même façon avec les versions futures de PostgreSQL™ ; éviter d'utiliser la jolie sortie pour les sauvegardes. Passer false pour le paramètre de la jolie sortie ramène le même résultat que la variante qui n'a pas ce paramètre

pg_get_serial_sequence renvoie le nom de la séquence associée avec une colonne ou NULL s'il n'existe aucune séquence associée à la colonne. Le premier argument en entrée est un nom de table avec le nom du schéma en option. Le second paramètre est un nom de colonne. Comme le premier paramètre peut potentiellement contenir le nom du schéma et de la table, il n'est pas traité comme un identifiant entre guillemets doubles, signifiant qu'il est en minuscule par défaut alors que le second paramètre, étant un simple nom de colonne, est présenté avec des guillemets doubles et a sa casse préservé. La fonction renvoie une valeur formatée convenablement pour qu'elle soit fournie aux fonctions sur les séquences (voir Section 9.12, « Fonctions de manipulation de séquence »). Cette association peut être modifiée ou supprimée avec ALTER SEQUENCE OWNED BY. (La fonction devrait probablement avoir été appelée pg_get_owned_sequence ; son nom reflète le fait qu'il est typiquement utilisé avec les colonnes serial et bigserial.)

pg_get_userbyid extrait un nom de rôle d'après son OID.

pg_tablespace_databases autorise l'examen d'un espace logique. Il renvoie l'ensemble des OID des bases qui ont 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, vous aurez besoin de connecter les bases identifiées par pg_tablespace_databases et d'exécuter des requêtes sur le catalogue pg_class.

les fonctions affichées dans Tableau 9.44, « 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 se trouve correspondre aux paramètres donnés.

Tableau 9.44. Fonctions d'informations sur les commentaires

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

col_description renvoie le commentaire de la colonne d'une 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é pour les colonnes de table car les colonnes n'ont pas d'OID elles-mêmes.

La forme à deux paramètres de obj_description renvoie le commentaire d'un objet de la base de données, spécifié par son OID et le nom du catalogue système le contenant. Par exemple, obj_description(123456,'pg_class') récupérerait le commentaire pour une table d'OID 123456. La forme à un paramètre de obj_description requiert seulement 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 ; du coup, un mauvais commentaire pourrait être renvoyé.

shobj_description est utilisé comme obj_description, seulement il est utilisé pour récupérer les commentaires sur les 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.