COMMENT — Définir ou modifier le commentaire associé à un objet
COMMENT ON { ACCESS METHODnom_objet
| AGGREGATEnom_agrégat
(signature_agrégat
) | CAST (type_source
AStype_cible
) | COLLATIONnom_objet
| COLUMNnom_relation
.nom_colonne
| CONSTRAINTnom_contrainte
ONnom_table
| CONSTRAINTnom_contrainte
ON DOMAINnom_domaine
| CONVERSIONnom_objet
| DATABASEnom_objet
| DOMAINnom_objet
| EXTENSIONnom_objet
| EVENT TRIGGERnom_objet
| FOREIGN DATA WRAPPERnom_objet
| FOREIGN TABLEnom_objet
| FUNCTIONnom_fonction
[ ( [ [mode_arg
] [nom_arg
]type_arg
[, ...] ] ) ] | INDEXnom_objet
| LARGE OBJECToid_large_objet
| MATERIALIZED VIEWnom_objet
| OPERATORop
(type_opérande1
,type_opérande2
) | OPERATOR CLASSnom_objet
USINGméthode_indexage
| OPERATOR FAMILYnom_objet
USINGméthode_index
| POLICYnom_politique
ONnom_table
| PROCEDUREnom_procédure
[ ( [ [mode_arg
] [nom_arg
]type_arg
[, ...] ] ) ] | PUBLICATIONnom_objet
| ROLEnom_objet
| ROUTINEnom_routine
[ ( [ [mode_arg
] [nom_arg
]type_arg
[, ...] ] ) ] | RULEnom_règle
ONnom_table
| SCHEMAnom_objet
| SEQUENCEnom_objet
| SERVERnom_objet
| STATISTICSnom_objet
| SUBSCRIPTIONnom_objet
| TABLEnom_objet
| TABLESPACEnom_objet
| TEXT SEARCH CONFIGURATIONnom_objet
| TEXT SEARCH DICTIONARYnom_objet
| TEXT SEARCH PARSERnom_objet
| TEXT SEARCH TEMPLATEnom_objet
| TRANSFORM FORnom_type
LANGUAGEnom_langage
| TRIGGERnom_trigger
ONnom_table
| TYPEnom_objet
| VIEWnom_objet
} IS {texte
| NULL } 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.
Une seule 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é.
Un verrou SHARE UPDATE EXCLUSIVE
est acquis sur l'objet
concerné par le commentaire.
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.
De la même façon, les méthodes d'accès n'ont pas encore de
propriétaire ; vous devez être superutilisateur pour modifier le
commentaire d'une méthode d'accès. 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.77.)
nom_objet
nom_relation.nom_colonne
nom_agrégat
nom_contrainte
nom_fonction
op
nom_opérateur
nom_politique
nom_procédure
nom_routine
nom_règle
nom_trigger
Le nom de l'objet à commenter. Les noms des objets qui résident dans des
schémas (tables, fonctions, etc.) 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.
nom_table
nom_domaine
Lors de l'ajout d'un commentaire sur une contrainte, un trigger, une règle ou une politique, ces paramètres spécifient le nom de la table ou du domaine sur lequel cet objet est défini.
type_source
Le nom du type de donnée source du transtypage.
type_cible
Le nom du type de données cible du transtypage.
mode_arg
Le mode d'un argument de la fonction, de la procédure 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 suffisant.
nom_arg
Le nom d'un argument de la fonction, de la procédure 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
sont nécessaires pour déterminer l'identité de la fonction.
type_arg
Le type de données d'un argument de la fonction, de la procédure ou de l'agrégat.
oid_objet_large
L'OID de l'objet large.
type_gauche
type_droit
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.
PROCEDURAL
Inutilisé.
nom_type
Le nom du type de données de la transformation.
nom_langage
Le nom du langage de la transformation.
texte
Le nouveau commentaire, rédigé sous la forme d'une chaîne littérale.
NULL
Écrire 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 ACCESS METHOD gin IS Méthode d''accès GIN'; 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 'Contrainte sur la colonne col'; COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Contrainte sur la colonne du domaine'; 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 EVENT TRIGGER abort_ddl IS 'Annule toute commande DDL'; 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 POLICY ma_politique ON ma_table IS 'Filtre des lignes par utilisateur'; COMMENT ON PROCEDURE ma_proc (integer, integer) IS 'Lance un rapport'; COMMENT ON PUBLICATION toutes_tables IS 'Publit toutes les opérations sur toutes les tables'; COMMENT ON ROLE mon_role IS 'Groupe d'administration pour les tables finance'; COMMENT ON ROUTINE ma_routine (integer, integer) IS 'Exécute une routine (qui est une fonction ou une procédure)'; 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 STATISTICS ma_statistique IS 'Améliore les estimations de ligne de l''optimiseur'; COMMENT ON SUBSCRIPTION toutes_tables IS 'Souscription pour toutes les opérations sur toutes les tables'; 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 TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transformation entre hstore et un dictionnaire Python'; COMMENT ON TRIGGER mon_trigger 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';
Il n'existe pas de commande COMMENT
dans le standard SQL.