Руководство По Языку SQL СУБД Firebird 5.0

CHARACTER SETОператоры обработки данных (DML)

`COMMENT ON`

Назначение

Документирование метаданных.

Доступно в

DSQL, ESQL

Синтаксис

COMMENT ON <object> IS {'sometext' | NULL}
<object> ::=
    { DATABASE | SCHEMA }
  | <basic-type> objectname
  | USER username [USING PLUGIN plugin_name]
  | COLUMN relationname.fieldname
  | [PROCEDURE | FUNCTION] PARAMETER
    [package_name.] routinename.paramname
  | {PROCEDURE | [EXTERNAL] FUNCTION}
    routinename
  | [GLOBAL] MAPPING mappingname

<basic-type> ::=
    CHARACTER SET
  | COLLATION
  | DOMAIN
  | EXCEPTION
  | FILTER
  | GENERATOR
  | INDEX
  | PACKAGE
  | ROLE
  | SEQUENCE
  | TABLE
  | TRIGGER
  | VIEW

Table 1. Параметры оператора `COMMENT ON`
Параметр	Описание
sometext	Текст комментария.
basic-type	Тип объекта метаданных.
objectname	Имя объекта метаданных.
relationname	Имя таблицы или представления.
filedname	Имя поля таблицы или представления.
routinename	Имя хранимой процедуры или функции.
paramname	Имя параметра хранимой процедуры или функции.
package_name	Имя пакета.
username	Имя пользователя.
plugin_name	Имя плагина управления пользователями.
mappingname	Имя отображения.

Оператор COMMENT ON добавляет комментарии для объектов базы данных (метаданных). Комментарии при этом сохраняются в текстовые поля RDB$DESCRIPTION типа BLOB соответствующей системной таблицы (из этих полей клиентское приложение может просмотреть комментарии).

При добавлении комментария для пользователя вы можете уточнить в каком плагине управления пользователями он находится с помощью необязательного предложения USING PLUGIN.Если это предложение отсутствует, то предполагает что пользователь создан в плагине управления по умолчанию, то есть первого плагина указанного в параметре UserManager в файле firebird.conf или databases.conf.

Note	Если вы вводите пустой комментарий (''), то он будет сохранен в базе данных как `NULL`.

Кто может добавить комментарий?

Выполнить оператор COMMENT ON могут:

Администраторы
Владелец объекта, для которого добавляется комментарий;
Пользователи с привилегией ALTER ANY <object_type>.

Примеры

Example 1. Добавление комментария для текущей базы данных.

COMMENT ON DATABASE IS 'Это тестовая (''my.fdb'') БД';

Example 2. Добавление комментария для таблицы.

COMMENT ON TABLE METALS IS 'Справочник металлов';

Example 3. Добавление комментария для поля таблицы.

COMMENT ON COLUMN METALS.ISALLOY
IS '0 = чистый металл, 1 = сплав';

Example 4. Добавление комментария для параметра процедуры.

COMMENT ON PARAMETER ADD_EMP_PROJ.EMP_NO
IS 'Код сотрудника';

Example 5. Добавление комментария для пакета, его процедур и функций, и их параметров.

COMMENT ON PACKAGE APP_VAR IS 'Переменные приложения';

COMMENT ON FUNCTION APP_VAR.GET_DATEBEGIN
IS 'Возвращает дату начала периода';

COMMENT ON PROCEDURE APP_VAR.SET_DATERANGE
IS 'Установка диапазона дат';

COMMENT ON
PROCEDURE PARAMETER APP_VAR.SET_DATERANGE.ADATEBEGIN
IS 'Дата начала';

Example 6. Добавление комментария для пользователя.

COMMENT ON USER BOB35 IS 'Это Боб из плагина по умолчанию';

COMMENT ON USER JHON USING PLUGIN Legacy_UserManager
IS 'Это Джон из плагина Legacy_UserManager';