COMMENT

Nom

COMMENT -- définit ou modifie le commentaire sur un objet

Synopsis

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
(type_arg1, type_arg2, ...) |
  INDEX nom_objet |
  LARGE OBJECT oid_large_objet |
  OPERATOR op (type_operande1, type_operande2) |
  OPERATOR CLASS nom_objet USING
méthode_indexage |
  RULE nom_role ON nom_table |
  SCHEMA nom_objet |
  SEQUENCE nom_objet |
  TRIGGER nom_declencheur ON
nom_table |
  TYPE nom_objet |
  VIEW nom_objet
} IS 'texte'

Description

COMMENT stocke un commentaire sur un objet de base de données.

Pour modifier un commentaire, lancez une nouvelle commande COMMENT pour le même objet. Seule une chaîne de commentaire est stockée pour chaque objet. Pour supprimer un commentaire, écrivez NULL à la place de la chaîne de texte. Les commentaires sont automatiquement supprimés lorsque l'objet est supprimé.

Les commentaires peuvent être facilement récupérés avec les commandes de psql \dd, \d+ et \l+. Les autres interfaces utilisateur permettant de récupérer les commentaires peuvent être construites au-dessus des même fonctions intégrées que celles utilisées par psql, nommément obj_description et col_description. (Voir Tableau 9-43.)

Paramètres

nom_objet
nom_table.nom_colonne
nom_agregat
nom_contrainte
nom_fonction
op
nom_regle
nom_declencheur

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 pourraient être qualifiés du nom du schéma.

type_agregat

Le type de données de l'argument de la fonction d'agrégat ou * si la fonction accepte tout type de données.

large_object_oid

L'OID de l'objet large.

PROCEDURAL

Ceci est du bruit.

sourcetype

Le nom du type de données source de la conversion.

targettype

Le nom du type de données cible de la conversion.

texte

Le nouveau commentaire, écrit comme une chaîne littérale ; ou NULL pour supprimer le commentaire.

Notes

Un commentaire pour une base de données peut seulement être créé dans cette base de données et ne sera visible que de cette base de données, pas des autres.

Il n'existe pas de mécanisme de sécurité pour les commentaires : tout utilisateur connecté à une base de données peut voir tous les commentaires des objets dans la base de données (bien que seuls les superutilisateurs peuvent modifier les commentaires sur des objets qu'ils ne possèdent pas). Du coup, ne placez pas d'informations critiques en terme de sécurité dans vos commentaires.

Exemples

Attacher un commentaire sur la table matable :

COMMENT ON TABLE matable IS 'Ceci est ma table.';

Supprimez-le de nouveau :

COMMENT ON TABLE matable IS NULL;

Quelques exemples supplémentaires :

COMMENT ON AGGREGATE mon_agregat (double precision) IS 'Calcule une variance type';
COMMENT ON CAST (text AS int4) IS 'Autorise les conversions de text vers int4';
COMMENT ON COLUMN ma_table.ma_colonne IS 'Numéro employé';
COMMENT ON CONVERSION ma_conv IS 'Conversion vers Unicode';
COMMENT ON DATABASE ma_database IS 'Base de données de développement';
COMMENT ON DOMAIN mon_domaine IS 'Domaine des adresses email';
COMMENT ON FUNCTION ma_fonction (timestamp) IS 'Renvoie en chiffres romain';
COMMENT ON INDEX mon_index IS 'Renforce 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 'Traite l\'intersection de deux textes';
COMMENT ON OPERATOR ^ (NONE, text) IS 'Opérateur de préfix 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 'Trace 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 générer 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';

Compatibilité

Il n'existe pas de commande COMMENT dans le standard SQL.