COMMENT

COMMENT
Prev	Up	Comandos SQL	Home	Next

COMMENT — definir o cambiar el comentario de un objeto

Synopsis

COMMENT ON
{
  ACCESS METHOD object_name |
  AGGREGATE aggregate_name ( aggregate_signature ) |
  CAST (source_type AS target_type) |
  COLLATION object_name |
  COLUMN relation_name.column_name |
  CONSTRAINT constraint_name ON table_name |
  CONSTRAINT constraint_name ON DOMAIN domain_name |
  CONVERSION object_name |
  DATABASE object_name |
  DOMAIN object_name |
  EXTENSION object_name |
  EVENT TRIGGER object_name |
  FOREIGN DATA WRAPPER object_name |
  FOREIGN TABLE object_name |
  FUNCTION function_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  INDEX object_name |
  LARGE OBJECT large_object_oid |
  MATERIALIZED VIEW object_name |
  OPERATOR operator_name (left_type, right_type) |
  OPERATOR CLASS object_name USING index_method |
  OPERATOR FAMILY object_name USING index_method |
  POLICY policy_name ON table_name |
  [ PROCEDURAL ] LANGUAGE object_name |
  PROCEDURE procedure_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  PUBLICATION object_name |
  ROLE object_name |
  ROUTINE routine_name [ ( [ [ argmode ] [ argname ] argtype [, ...] ] ) ] |
  RULE rule_name ON table_name |
  SCHEMA object_name |
  SEQUENCE object_name |
  SERVER object_name |
  STATISTICS object_name |
  SUBSCRIPTION object_name |
  TABLE object_name |
  TABLESPACE object_name |
  TEXT SEARCH CONFIGURATION object_name |
  TEXT SEARCH DICTIONARY object_name |
  TEXT SEARCH PARSER object_name |
  TEXT SEARCH TEMPLATE object_name |
  TRANSFORM FOR type_name LANGUAGE lang_name |
  TRIGGER trigger_name ON table_name |
  TYPE object_name |
  VIEW object_name
} IS { string_literal | NULL }

donde aggregate_signature es:

* |
[ argmode ] [ argname ] argtype [ , ... ] |
[ [ argmode ] [ argname ] argtype [ , ... ] ] ORDER BY [ argmode ] [ argname ] argtype [ , ... ]

Descripción

COMMENT almacena, reemplaza o elimina el comentario de un objeto de base de datos.

Solo se almacena una cadena de comentario para cada objeto. Ejecutar un nuevo comando COMMENT para el mismo objeto reemplaza el comentario existente. Especificar NULL o una cadena vacía ('') elimina el comentario. Los comentarios se eliminan automáticamente cuando se elimina su objeto correspondiente.

Se adquiere un bloqueo SHARE UPDATE EXCLUSIVE sobre el objeto que se va a comentar.

Para la mayoría de los tipos de objetos, solo el propietario del objeto puede establecer el comentario. Los roles no tienen propietarios, por lo que la regla para COMMENT ON ROLE es que debes ser superusuario para comentar sobre un rol de superusuario, o tener el privilegio CREATEROLE y haber recibido la opción ADMIN OPTION sobre el rol de destino. Del mismo modo, los métodos de acceso tampoco tienen propietarios; debes ser superusuario para comentar sobre un método de acceso. Por supuesto, un superusuario puede comentar sobre cualquier cosa.

Los comentarios se pueden ver utilizando la familia de comandos \d de psql. Se pueden construir otras interfaces de usuario para recuperar comentarios sobre las mismas funciones integradas que utiliza psql, a saber, obj_description, col_description y shobj_description (consulta Table 9.82).

Parámetros

object_name relation_name.column_name aggregate_name constraint_name function_name operator_name policy_name procedure_name routine_name rule_name trigger_name: El nombre del objeto que se va a comentar. Los nombres de los objetos que residen en esquemas (tablas, funciones, etc.) pueden calificarse con el nombre del esquema. Al comentar sobre una columna, relation_name debe referirse a una tabla, vista, tipo compuesto o tabla foránea.
table_name domain_name: Al crear un comentario sobre una restricción, un disparador (trigger), una regla o una política, estos parámetros especifican el nombre de la tabla o dominio sobre el cual está definido ese objeto.
source_type: El nombre del tipo de datos origen de la conversión (cast).
target_type: El nombre del tipo de datos destino de la conversión (cast).
argmode: El modo de un argumento de función, procedimiento o agregación: IN, OUT, INOUT o VARIADIC. Si se omite, el valor por defecto es IN. Ten en cuenta que COMMENT en realidad no presta ninguna atención a los argumentos OUT, ya que solo se necesitan los argumentos de entrada para determinar la identidad de la función. Por lo tanto, es suficiente con enumerar los argumentos IN, INOUT y VARIADIC.
argname: El nombre de un argumento de función, procedimiento o agregación. Ten en cuenta que COMMENT en realidad no presta ninguna atención a los nombres de los argumentos, ya que solo se necesitan los tipos de datos de los argumentos para determinar la identidad de la función.
argtype: El tipo de datos de un argumento de función, procedimiento o agregación.
large_object_oid: El OID del objeto grande (large object).
left_type right_type: El tipo de datos (u opcionalmente calificados por esquema) de los argumentos del operador. Escribe NONE para el argumento omitido de un operador prefijo.
PROCEDURAL: Esta es una palabra de ruido (no tiene ningún efecto).
type_name: El nombre del tipo de datos de la transformación (transform).
lang_name: El nombre del lenguaje de la transformación (transform).
string_literal: El nuevo contenido del comentario, escrito como una cadena literal. Una cadena vacía ('') elimina el comentario.
NULL: Escribe NULL para eliminar el comentario.

Notas

Actualmente no existe ningún mecanismo de seguridad para ver comentarios: cualquier usuario conectado a una base de datos puede ver todos los comentarios de los objetos en esa base de datos. Para los objetos compartidos como bases de datos, roles y tablespaces, los comentarios se almacenan globalmente, por lo que cualquier usuario conectado a cualquier base de datos en el clúster puede ver todos los comentarios de los objetos compartidos. Por lo tanto, no pongas información crítica para la seguridad en los comentarios.

Ejemplos

Asociar un comentario a la tabla mytable:

COMMENT ON TABLE mytable IS 'Esta es mi tabla.';

Eliminarlo de nuevo:

COMMENT ON TABLE mytable IS NULL;

Algunos ejemplos más:

COMMENT ON ACCESS METHOD gin IS 'Método de acceso de índice GIN';
COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Calcula la varianza muestral';
COMMENT ON CAST (text AS int4) IS 'Permitir conversiones de text a int4';
COMMENT ON COLLATION "fr_CA" IS 'Francés canadiense';
COMMENT ON COLUMN my_table.my_column IS 'Número de identificación del empleado';
COMMENT ON CONVERSION my_conv IS 'Conversión a UTF8';
COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Restringe la columna col';
COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Restringe la columna col del dominio dom';
COMMENT ON DATABASE my_database IS 'Base de datos de desarrollo';
COMMENT ON DOMAIN my_domain IS 'Dominio de dirección de correo electrónico';
COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborta todos los comandos DDL';
COMMENT ON EXTENSION hstore IS 'Implementa el tipo de datos hstore';
COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'Mi envolvedor de datos foráneos';
COMMENT ON FOREIGN TABLE my_foreign_table IS 'Información de empleados en otra base de datos';
COMMENT ON FUNCTION my_function (timestamp) IS 'Devuelve números romanos';
COMMENT ON INDEX my_index IS 'Garantiza la unicidad en el ID del empleado';
COMMENT ON LANGUAGE plpython IS 'Soporte de Python para procedimientos almacenados';
COMMENT ON LARGE OBJECT 346344 IS 'Documento de planificación';
COMMENT ON MATERIALIZED VIEW my_matview IS 'Resumen del historial de pedidos';
COMMENT ON OPERATOR ^ (text, text) IS 'Realiza la intersección de dos textos';
COMMENT ON OPERATOR - (NONE, integer) IS 'Menos unario';
COMMENT ON OPERATOR CLASS int4ops USING btree IS 'Operadores de enteros de 4 bytes para btrees';
COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'Todos los operadores de enteros para btrees';
COMMENT ON POLICY my_policy ON mytable IS 'Filtrar filas por usuarios';
COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Ejecuta un informe';
COMMENT ON PUBLICATION alltables IS 'Publica todas las operaciones en todas las tablas';
COMMENT ON ROLE my_role IS 'Grupo de administración para tablas financieras';
COMMENT ON ROUTINE my_routine (integer, integer) IS 'Ejecuta una rutina (que es una función o procedimiento)';
COMMENT ON RULE my_rule ON my_table IS 'Registra las actualizaciones de los registros de empleados';
COMMENT ON SCHEMA my_schema IS 'Datos del departamento';
COMMENT ON SEQUENCE my_sequence IS 'Utilizada para generar claves primarias';
COMMENT ON SERVER myserver IS 'Mi servidor foráneo';
COMMENT ON STATISTICS my_statistics IS 'Mejora las estimaciones de filas del planificador';
COMMENT ON SUBSCRIPTION alltables IS 'Suscripción para todas las operaciones en todas las tablas';
COMMENT ON TABLE my_schema.my_table IS 'Información del empleado';
COMMENT ON TABLESPACE my_tablespace IS 'Tablespace para índices';
COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Filtrado especial de palabras';
COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Lematizador Snowball para el idioma sueco';
COMMENT ON TEXT SEARCH PARSER my_parser IS 'Divide el texto en palabras';
COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Lematizador Snowball';
COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transformación entre hstore y dict de Python';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Utilizado para integridad referencial (RI)';
COMMENT ON TYPE complex IS 'Tipo de datos de número complejo';
COMMENT ON VIEW my_view IS 'Vista de los costos del departamento';
COMMENT ON VIEW my_view IS NULL;

Compatibilidad

No existe un comando COMMENT en el estándar SQL.