COMMENT

примечание

Эта страница переведена при помощи нейросети GigaChat.

COMMENT - создание или изменение комментария к объекту.

Синтаксис

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 }

where aggregate_signature is:

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

Описание

COMMENT хранит комментарий к объекту базы данных.

Для каждого объекта может храниться только одна строка комментария, поэтому для изменения комментария нужно выполнить новую команду COMMENT для того же объекта. Чтобы удалить комментарий, укажите NULL вместо текстовой строки. Комментарии автоматически удаляются при удалении соответствующего объекта.

Для комментируемого объекта устанавливается блокировка SHARE UPDATE EXCLUSIVE.

В большинстве случаев только владелец объекта может установить комментарий. Роли не имеют владельцев, поэтому правило для COMMENT ON ROLE заключается в том, что нужно быть суперпользователем, чтобы комментировать роль суперпользователя, либо иметь привилегию CREATEROLE и получить разрешение ADMIN OPTION на целевую роль. Аналогично, методы доступа также не имеют владельцев. Нужно быть суперпользователем, чтобы прокомментировать метод доступа. Конечно, суперпользователь может оставить комментарий к чему угодно.

Комментарии можно просматривать с помощью команд семейства \d в psql. Также можно использовать встроенные функции, на которых основан psql: obj_description, col_description и shobj_description, чтобы создавать другие интерфейсы просмотра комментариев.

Параметры

object_name
relation_name.column_name
aggregate_name
constraint_name
function_name
operator_name
policy_name
procedure_name
routine_name
rule_name
trigger_name

Указывает имя объекта, который нужно прокомментировать. Имена объектов, которые находятся в схемах (таблицы, функции и так далее), могут быть квалифицированы схемой. Когда комментируется столбец, relation_name должен ссылаться на таблицу, представление, составной тип или внешнюю таблицу.

table_name
domain_name

Используются при комментировании ограничений, триггеров, правил или политик, чтобы указать таблицу или домен, к которым они относятся.

source_type

Задает имя исходного типа данных для приведения.

target_type

Задает имя целевого типа данных для приведения.

argmode

Указывает режим аргумента функции, процедуры или агрегата: IN, OUT, INOUT, или VARIADIC. Если опустить, то по умолчанию будет IN. Обратите внимание, что COMMENT фактически не обращает никакого внимания на аргументы OUT, поскольку для определения идентичности функции требуются только входные аргументы. Поэтому достаточно перечислить аргументы IN, INOUT, и VARIADIC.

argname

Указывает имя аргумента функции, процедуры или агрегата. Обратите внимание, что COMMENT фактически не обращает никакого внимания на имена аргументов, так как для определения идентичности функции необходимы только типы данных аргументов.

argtype

Указывает тип данных аргумента функции, процедуры или агрегата.

large_object_oid

Задает OID большого объекта.

left_type
right_type

Указывает Тип(ы) данных аргументов оператора, при необходимости дополненный схемой. Запишите NONE для отсутствующего аргумента префиксного оператора.

PROCEDURAL

Не имеет значения (шумовое слово).

type_name

Задает имя типа данных, для которого предназначена трансформация.

lang_name

Задает название языка, для которого предназначена трансформация.

string_literal

Задает содержание нового комментария, записанное в виде строковой константы.

NULL

Указывает на удаление комментария.

Примечания

В настоящее время нет механизма ограничения доступа к просмотру комментариев: любой пользователь, подключенный к базе данных, может просматривать все комментарии к объектам этой базы. Комментарии к общим объектам (например, базам данных, ролям, табличным пространствам) хранятся глобально, поэтому любой пользователь, подключенный к любой базе кластера, может видеть их. Поэтому не стоит размещать в комментариях информацию, связанную с безопасностью.

Примеры

Добавление комментария для таблицы mytable:

COMMENT ON TABLE mytable IS 'This is my table.';

Удалить его:

COMMENT ON TABLE mytable IS NULL;

Еще несколько примеров:

COMMENT ON ACCESS METHOD gin IS 'GIN index access method';
COMMENT ON AGGREGATE my_aggregate (double precision) IS 'Computes sample variance';
COMMENT ON CAST (text AS int4) IS 'Allow casts from text to int4';
COMMENT ON COLLATION "fr_CA" IS 'Canadian French';
COMMENT ON COLUMN my_table.my_column IS 'Employee ID number';
COMMENT ON CONVERSION my_conv IS 'Conversion to UTF8';
COMMENT ON CONSTRAINT bar_col_cons ON bar IS 'Constrains column col';
COMMENT ON CONSTRAINT dom_col_constr ON DOMAIN dom IS 'Constrains col of domain';
COMMENT ON DATABASE my_database IS 'Development Database';
COMMENT ON DOMAIN my_domain IS 'Email Address Domain';
COMMENT ON EVENT TRIGGER abort_ddl IS 'Aborts all DDL commands';
COMMENT ON EXTENSION hstore IS 'implements the hstore data type';
COMMENT ON FOREIGN DATA WRAPPER mywrapper IS 'my foreign data wrapper';
COMMENT ON FOREIGN TABLE my_foreign_table IS 'Employee Information in other database';
COMMENT ON FUNCTION my_function (timestamp) IS 'Returns Roman Numeral';
COMMENT ON INDEX my_index IS 'Enforces uniqueness on employee ID';
COMMENT ON LANGUAGE plpython IS 'Python support for stored procedures';
COMMENT ON LARGE OBJECT 346344 IS 'Planning document';
COMMENT ON MATERIALIZED VIEW my_matview IS 'Summary of order history';
COMMENT ON OPERATOR ^ (text, text) IS 'Performs intersection of two texts';
COMMENT ON OPERATOR - (NONE, integer) IS 'Unary minus';
COMMENT ON OPERATOR CLASS int4ops USING btree IS '4 byte integer operators for btrees';
COMMENT ON OPERATOR FAMILY integer_ops USING btree IS 'all integer operators for btrees';
COMMENT ON POLICY my_policy ON mytable IS 'Filter rows by users';
COMMENT ON PROCEDURE my_proc (integer, integer) IS 'Runs a report';
COMMENT ON PUBLICATION alltables IS 'Publishes all operations on all tables';
COMMENT ON ROLE my_role IS 'Administration group for finance tables';
COMMENT ON ROUTINE my_routine (integer, integer) IS 'Runs a routine (which is a function or procedure)';
COMMENT ON RULE my_rule ON my_table IS 'Logs updates of employee records';
COMMENT ON SCHEMA my_schema IS 'Departmental data';
COMMENT ON SEQUENCE my_sequence IS 'Used to generate primary keys';
COMMENT ON SERVER myserver IS 'my foreign server';
COMMENT ON STATISTICS my_statistics IS 'Improves planner row estimations';
COMMENT ON SUBSCRIPTION alltables IS 'Subscription for all operations on all tables';
COMMENT ON TABLE my_schema.my_table IS 'Employee Information';
COMMENT ON TABLESPACE my_tablespace IS 'Tablespace for indexes';
COMMENT ON TEXT SEARCH CONFIGURATION my_config IS 'Special word filtering';
COMMENT ON TEXT SEARCH DICTIONARY swedish IS 'Snowball stemmer for Swedish language';
COMMENT ON TEXT SEARCH PARSER my_parser IS 'Splits text into words';
COMMENT ON TEXT SEARCH TEMPLATE snowball IS 'Snowball stemmer';
COMMENT ON TRANSFORM FOR hstore LANGUAGE plpython3u IS 'Transform between hstore and Python dict';
COMMENT ON TRIGGER my_trigger ON my_table IS 'Used for RI';
COMMENT ON TYPE complex IS 'Complex number data type';
COMMENT ON VIEW my_view IS 'View of departmental costs';

Совместимость

В стандарте SQL нет команды COMMENT.