Сопровождение базы данных
Документирование базы данных. Команда COMMENT.
В PostgreSQL поддерживается нестандартная команда SQL COMMENT, при помощи которой можно документировать любой объект базы данных. Используя команду COMMENT с таблицей, функцией, оператором или другим объектом базы данных, вы можете ввести описание, которое будет храниться в системной таблице pg_description. Выборка описаний легко производится при помощи управляющих команд psql.
У многих стандартных объектов баз данных имеются стандартные описания, которые выводятся (вместе с описаниями, добавленными пользователем) командой \dd клиента psql.
Синтаксис команды COMMENT:
COMMENT ON [ [ DATABASE | INDEX | RULE SEQUENCE TABLE | TYPE j VIEW ]
{ объект |
COLUMN таблица.поле \
AGGREGATE агрегат тип_агрегата \
FUNCTION функция (тип_аргумента [….]) |
OPERATOR оператор (тип_левого_операнда. тип_правого_операнда) |
TRIGGER триггер ON таблица } ] IS 'описание'
Параметр объект определяет имя объекта базы данных, для которого создается комментарий. Ключевые слова для основных объектов баз данных не обязательны, но если комментарий создается для поля, функции, агрегатной функции, оператора или триггера, необходимо указать соответствующее ключевое слово – по нему PostgreSQL проверяет синтаксис дальнейшего описания.
Примечание
Все комментарии связываются как с базой данных, так и с конкретным пользователем. Каждый пользователь может просматривать только свои комментарии.
Строка описание, следующая за ключевым словом IS, содержит текст комментария, сохраняемого в базе данных. В листинге 9.18 создается простое описание для поля id базы данных booktown.
Листинг 9.18. Создание комментария к таблице books.
booktown=# COMMENT ON COLUMN books.id booktown-# IS 'An Internal Book Town Identifier'; COMMENT
Сообщение COMMENT означает, что комментарии к полю успешно создан.
Чтение комментариев
Комментарии к объектам базы данных легко читаются при помощи управляющих команд psql. Список этих команд приведен ниже.
- \d+. Выводит ту же информацию, что и стандартная команда \d (данные обо всех таблицах, представлениях, последовательностях и индексах текущей базы данных), но добавляет к ней столбец комментариев.
- \i+. Выводит комментарии ко всем базам данных.
- \df+ [ шаблон ]. Выводит описания всех функций текущей базы данных (с информацией о языке и реализации каждой функции). Чтобы просмотреть результаты этой команды в расширенном режиме вывода, следует предварительно выполнить команду \х (за дополнительной информацией обращайтесь к главе 6). Команде можно передать регулярное выражение шаблон, с которым должны сравниваться имена функций. Это сужает круг поиска и уменьшает количество выводимых функций.
- \dt+. Выводит комментарии ко всем таблицам текущей базы данных.
- \di+. Выводит комментарии ко всем индексам текущей базы данных.
- \ds+. Выводит комментарии ко всем последовательностям текущей базы данных.
- \dv+. Выводит комментарии ко всем представлениям текущей базы данных.
- \dS+. Выводит комментарии к системным таблицам. Следует помнить, что комментарии к системным таблицам тоже привязываются к конкретной базе данных и не выводятся, если команда \dS+ выполняется при подключении к другой базе данных.
- \dd. Выводит все описания всех объектов базы данных.
В листинге 9.19 приведен пример вывода комментариев к таблице books (листинг 9.18) командой \d+ клиента psql.
Листинг 9.19. Вывод комментариев booktown=# \d+ books.
Table "books" Attribute j Type Modifier | Description id | integer not null | An Internal Book Town Identifier title text not null j authorjd j integer subject_id | integer Index: books_id_pkey
Команда SQL COMMENT обеспечивает очень простые средства внутреннего документирования различных объектов, от таблиц до функций. Комментарии оказывают неоценимую помощь при работе с большими или очень сложными структурами баз данных. Даже специальные схемы выбора имен не всегда делают очевидным смысл объектов базы данных, особенно если над проектом работает несколько разработчиков.