CLUSTER
COMMENT ON
{
TABLE nom_objet |
COLUMN nom_table.nom_colonne |
AGGREGATE nom_agrégat (type_agrégat) |
CAST (typesource AS typecible) |
CONSTRAINT nom_contrainte ON nom_table |
CONVERSION nom_objet |
DATABASE nom_objet |
DOMAIN nom_objet |
FUNCTION nom_fonction ( [ [ modearg ] [ nomarg ] typearg [, ...] ] ) |
INDEX nom_objet |
LARGE OBJECT oid_large_objet |
OPERATOR op (type_operande1, type_operande2) |
OPERATOR CLASS nom_objet USING méthode_indexage |
RULE nom_rêgle ON nom_table |
SCHEMA nom_objet |
SEQUENCE nom_objet |
TRIGGER nom_déclencheur ON nom_table |
TYPE nom_objet |
VIEW nom_objet
} IS 'texte'
COMMENT stocke un commentaire sur un objet de la base de données.
Pour modifier un commentaire, il suffit de lancer une nouvelle commande COMMENT portant sur le même objet. Une seule chaîne de commentaire est stockée pour chaque objet. Pour supprimer un commentaire, NULL est écrit à la place de la chaîne de texte. Les commentaires sont automatiquement supprimés avec l'objet.
Les commentaires peuvent être facilement récupérés avec les commandes psql \dd, \d+ et \l+. D'autres interfaces utilisateur de récupération des commentaires peuvent être construites au-dessus des fonctions intégrées qu'utilise psql, à savoir obj_description et col_description. (Voir Tableau 9.43, « Fonctions d'informations sur les commentaires ».)
Le nom de l'objet à commenter. Les noms des tables, agrégats, domaines, fonctions, index, opérateurs, classes d'opérateurs, séquences, types et vues peuvent être qualifiés du nom du schéma.
Le type de données de l'argument de la fonction d'agrégat ou * si la fonction accepte tout type de données.
Le nom du type de donnée source du transtypage.
Le nom du type de données cible du transtypage.
Le mode d'un argument de la fonction : IN, OUT ou INOUT. En cas d'omission, la valeur par défaut est IN. COMMENT ON FUNCTION ne tient pas compte, à l'heure actuelle, des arguments OUT car seuls ceux en entrée sont nécessaires pour déterminer l'identité de la fonction. Lister les arguments IN et INOUT est ainsi suffisant.
Le nom d'un argument de la fonction. COMMENT ON FUNCTION ne tient pas compte, à l'heure actuelle, des noms des arguments, seuls les types de données des arguments étant nécessaires pour déterminer l'identité de la fonction.
Les types de données des arguments de la fonction (éventuellement qualifiés du nom du schéma).
L'OID de l'objet large.
Inutilisé.
Le nouveau commentaire, rédigé sous la forme d'une chaîne littérale ; ou NULL pour supprimer le commentaire.
Un commentaire de base de données ne peut être créé que dans cette base et n'est visible que depuis cette base.
Il n'existe pas de mécanisme de sécurité pour les commentaires : tout utilisateur connecté à une base de données peut voir les commentaires de tous les objets de la base (mais seuls les superutilisateurs peuvent modifier les commentaires des objets qu'ils ne possèdent pas). Il est de ce fait judicieux de ne pas placer d'informations critiques dans les commentaires.
Attacher un commentaire à la table matable :
COMMENT ON TABLE matable IS 'Ceci est ma table.';
Suppression du commentaire précédent :
COMMENT ON TABLE matable IS NULL;
Quelques exemples supplémentaires :
COMMENT ON AGGREGATE mon_agregat (double precision) IS 'Calcul d'une variance type'; COMMENT ON CAST (text AS int4) IS 'Transtypage de text en int4'; COMMENT ON COLUMN ma_table.ma_colonne IS 'Numéro employé'; COMMENT ON CONVERSION ma_conv IS 'Conversion vers UTF8'; COMMENT ON DATABASE ma_base IS 'Base de données de développement'; COMMENT ON DOMAIN mon_domaine IS 'Domaine des adresses de courriel'; COMMENT ON FUNCTION ma_fonction (timestamp) IS 'Retourner des chiffres romains'; COMMENT ON INDEX mon_index IS 'S'assurer de l'unicité de l'ID de l'employé'; COMMENT ON LANGUAGE plpython IS 'Support de Python pour les procedures stockées'; COMMENT ON LARGE OBJECT 346344 IS 'Document de planification'; COMMENT ON OPERATOR ^ (text, text) IS 'L\'intersection de deux textes'; COMMENT ON OPERATOR - (NONE, text) IS 'Opérateur de préfixe sur un texte'; COMMENT ON OPERATOR CLASS int4ops USING btree IS 'Opérateurs d'entiers sur quatre octets pour les index btrees'; COMMENT ON RULE ma_regle ON my_table IS 'Tracer les mises à jour des enregistrements d\'employé'; COMMENT ON SCHEMA mon_schema IS 'Données du département'; COMMENT ON SEQUENCE ma_sequence IS 'Utilisé pour engendrer des clés primaires'; COMMENT ON TABLE mon_schema.ma_table IS 'Informations sur les employés'; COMMENT ON TRIGGER mon_declencheur ON my_table IS 'Utilisé pour RI'; COMMENT ON TYPE complex IS 'Type de données pour les nombres complexes'; COMMENT ON VIEW ma_vue IS 'Vue des coûts départementaux';