COMMENT — Définir ou modifier le commentaire associé à un objet
CLUSTER
COMMENT ON
{
AGGREGATE nom_agrégat ( signature_agrégat ) |
CAST (type_source AS type_cible) |
COLLATION nom_objet |
COLUMN nom_relation.nom_colonne |
CONSTRAINT nom_contrainte ON nom_table |
CONVERSION nom_objet |
DATABASE nom_objet |
DOMAIN nom_objet |
EXTENSION nom_objet |
EVENT TRIGGER nom_objet |
FOREIGN DATA WRAPPER nom_objet |
FOREIGN TABLE nom_objet |
FUNCTION nom_fonction ( [ [ modearg ] [ nomarg ] typearg [, ...] ] ) |
INDEX nom_objet |
LARGE OBJECT oid_large_objet |
MATERIALIZED VIEW nom_objet |
OPERATOR op (type_operande1, type_operande2) |
OPERATOR CLASS nom_objet USING méthode_indexage |
OPERATOR FAMILY nom_objet USING methode_index |
ROLE nom_objet |
RULE nom_rêgle ON nom_table |
SCHEMA nom_objet |
SEQUENCE nom_objet |
SERVER nom_objet |
TABLE nom_objet |
TABLESPACE nom_objet |
TEXT SEARCH CONFIGURATION nom_objet |
TEXT SEARCH DICTIONARY nom_objet |
TEXT SEARCH PARSER nom_objet |
TEXT SEARCH TEMPLATE nom_objet |
TRIGGER nom_déclencheur ON nom_table |
TYPE nom_objet |
VIEW nom_objet
} IS 'texte'
où signature_agrégat est :
* |
[ mode_arg ] [ nom_arg ] type_arg [ , ... ] |
[ [ mode_arg ] [ nom_arg ] type_arg [ , ... ] ] ORDER BY [ mode_arg ] [ nom_arg ] type_arg [ , ... ]
COMMENT stocke un commentaire sur un objet de la base de données.
Seule une chaîne de commentaire est stockée pour chaque objet, donc pour modifier un commentaire, lancer une nouvelle commande COMMENT pour le même objet. Pour supprimer un commentaire, écrire un NULL à la place dans la chaîne de texte. Les commentaires sont automatiquement supprimées quand leur objet est supprimé.
Pour la plupart des types d'objet, seul le propriétaire de l'objet peut configurer le commentaire. Les rôles n'ont pas de propriétaires, donc la règle pour COMMENT ON ROLE est que vous devez être superutilisateur pour commenter un rôle superutilisateur ou avoir l'attribut CREATEROLE pour commenter des rôles standards. Bien sûr, un superutilisateur peut ajouter un commentaire sur n'importe quel objet.
Les commentaires sont visibles avec la famille de commandes \d, de psql. 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, col_description et shobj_description. (Voir Tableau 9.60, « Fonctions d'informations sur les commentaires ».)
Le nom de l'objet à commenter. Les noms des tables, agrégats, collationnements, conversions, domaines, tables distantes, fonctions, index, opérateurs, classes d'opérateur, familles d'opérateur, séquences, objets de la recherche plein texte, types et vues peuvent être qualifiés du nom du schéma. Lorsque le commentaire est placé sur une colonne, nom_relation doit faire référence à une table, une vue, un type composite ou une table distante.
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 ou de l'agrégat : IN, OUT, INOUT ou VARIADIC. En cas d'omission, la valeur par défaut est IN. COMMENT 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, INOUT et VARIADIC est ainsi suffisant.
Le nom d'un argument de la fonction ou de l'agrégat. 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.
Le type de données d'un argument de la fonction ou de l'agrégat.
L'OID de l'objet large.
Les types de données des arguments de l'opérateur (avec en option le nom du schéma). Écrire NONE pour l'argument manquant d'un opérateur préfixe ou postfixe.
Inutilisé.
Le nouveau commentaire, rédigé sous la forme d'une chaîne littérale ; ou NULL pour supprimer le commentaire.
Il n'existe pas de mécanisme de sécurité pour visualiser les commentaires : tout utilisateur connecté à une base de données peut voir les commentaires de tous les objets de la base. Pour les objets partagés comme les bases, les rôles et les tablespaces, les commentaires sont stockées globalement et tout utilisateur connecté à une base peut voir tous les commentaires pour les objets partagés. Du coup, ne placez pas d'informations critiques pour la sécurité dans vos 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 COLLATION "fr_CA" IS 'Canadian French'; COMMENT ON COLUMN ma_table.ma_colonne IS 'Numéro employé'; COMMENT ON CONVERSION ma_conv IS 'Conversion vers UTF8'; COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrainte sur la colonne col'; 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 EXTENSION hstore IS 'implémente le type de données hstore'; COMMENT ON FOREIGN DATA WRAPPER mon_wrapper IS 'mon wrapper de données distantes'; COMMENT ON FOREIGN TABLE ma_table_distante IS 'Information employés dans une autre base'; 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 MATERIALIZED VIEW ma_vuemat IS 'Résumé de l\'historique des ordres'; COMMENT ON OPERATOR ^ (text, text) IS 'L\'intersection de deux textes'; COMMENT ON OPERATOR - (NONE, integer) IS 'Moins unaire'; COMMENT ON OPERATOR CLASS int4ops USING btree IS 'Opérateurs d'entiers sur quatre octets pour les index btrees'; COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'Tous les opérateurs entiers pour les index btree'; COMMENT ON ROLE mon_role IS 'Groupe d'administration pour les tables finance'; 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 SERVER mon_serveur IS 'mon serveur distant'; COMMENT ON TABLE mon_schema.ma_table IS 'Informations sur les employés'; COMMENT ON TABLESPACE mon_tablespace IS 'Tablespace pour les index'; COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Filtre des mots spéciaux'; COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Stemmer Snowball pour le Suédois'; COMMENT ON TEXT SEARCH PARSER my_parser IS 'Divise le texte en mot'; COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Stemmer Snowball'; 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';