Инструмент, тип документации | Какую информацию можно найти | Примеры и комментарии | Что почитать |
Специальные платформы управления данными Data Management. | • Каталог данных (Data Catalog) — единый источник сведений о всех информационных активах организации. • Список полей и атрибутов • Метаданные — например, информацию о размере таблиц, дате последнего обновления • Информацию об ответственных лицах • Бизнес-глоссарий | Дороги в применении, используются в крупных только в больших компаниях, актуальны для проектов создания DWH (централизованное персистентное хранение данных всего предприятия для аналитики). | Что такое каталог данных? Видео от DIS Group Комплексная платформа управления данными от компании Юнидата |
Сгенерированные отчёты с использованием специальных внешних сервисов и утилит или инструментов автосборки документации на основе комментариев в коде БД. | • Дают понимание физической модели данных, схемы данных БД — таблиц, полей и атрибутов, и т.д. • Включают информацию об объектах, помимо таблиц (индексах, представлениях, и т.п.). | Использование дополнительных утилит, не всегда приемлемо с точки зрения безопасности. Автосборка требует высокой дисциплины разработчиков и QC, и подходит, если команда придерживается практики DocsAsCode для важной документации (что встречается в зрелых продуктовых компаниях). | Анализ средств документирования баз данных
Обсуждение способов сборки документации по базе данных |
Полная модель данных на концептуальном, логическом, физическом уровне (как минимум, одном из них). Включая: • Состав таблиц • Типы данных • Связи между сущностями и атрибутами | Наглядно показывают связи между таблицами.. Обычно встроены в современные средства работы с БД и позволяют сгенерировать DDL для БД. | Дороги в применении, используются в крупных компаниях. И даже при этом, фактически, применяются только для части системы. | CASE-средства проектирования баз данных |
Специальные диаграммы: • ER диаграммы, • Диаграммы классов UML • Другие виды диаграмм | Сущности, атрибуты и связи между ними. Логическая связь между данными. | Нужно понимать контекст создания диаграмм, так как они редко являются исчерпывающими. Если диаграммы разрабатывались для постановки задачи в средствах визуализации, не интегрированных с СУБД, то они могут не отражать физическую схему данных и не конвертируются напрямую в SQL код. | Методика построения ER-диаграммы для базы данных Просмотр модели данных готовой БД |
Разные разделы документов требований к разрабатываемой системе. | Допустимые значения, смысл данных | Разбросаны по разным UC, главам документа Технического задания, приложениям и т.д. | Алгоритм описания функциональных требований в формате Use Case-ов |
Наборы данных, применяемые для тестирования. | Допустимые значения, форматы данных. | Некомфортны для чтения. | Создание тестовых данных |
Способ | Описание | Пример |
Использовать специализированные инструменты, обеспечивающие возможность просмотра объектов БД. | Способ позволит визуально быстро понять, какие объекты есть в вашей базе данных. Можное осмотреть список таблиц и о каждой из них узнать что-то из контекстного меню или другой части внутри GUI используемого средства. Однако, получать, хранить и передавать информацию в такой форме неудобно. | Документация к редактору объектов DBeaver |
Вывести информацию об объектах БД с помощью соответствующих SQL запросов к служебным таблицам. | В РСУБД существуют служебные таблицы, которые содержат интересующие нас сведения об объектах базы данных. Вы можете строить несложные SQL запросы к служебным таблицам и системным каталогам БД (помимо таблиц со схемой, среди служебных таблиц обычно есть много интересного). | Использование схемы данных в SQL Server Примеры запросов для получения схемы данных SQL Server Пример запроса к специальной таблице в SQLite Пример запроса к системному каталогу PostgreSQL |
Применять встроенные или внешние инструменты моделирования БД. | Позволяют наглядно увидеть связи между таблицами, это комфортно и информативно. Современные средства работы с БД обычно имеют такие инструменты. | ER диаграммы, встроенные в инструмент работы с РСУБД DBeaber Генерация таблиц БД из ER диаграммы |
Таблица | Комментарий к таблице | № п.п | Поле | Комментарий к полю | Тип | Ключ | NULL |
EMPLOYEE | Сотрудники | 1 | ID | Идентификатор | int(11) | PK | NO |
EMPLOYEE | Сотрудники | 2 | LAST_NAME | Фамилия | varchar(45) | NO | |
EMPLOYEE | Сотрудники | 3 | FIRST_NAME | Имя | varchar(45) | NO | |
EMPLOYEE | Сотрудники | 4 | MIDDLE_NAME | Отчество | varchar(45) | YES | |
EMPLOYEE | Сотрудники | 5 | BIRTHDAY | День рождения | date | YES | |
GRADE | Оценки | 1 | ID | Идентификатор | int(11) | PK | NO |
GRADE | Оценки | 2 | STUDENT_ID | ИД студента в группе | int(11) | YES | |
GRADE | Оценки | 3 | MODULE_NUM | Номер модуля | int(11) | YES | |
GRADE | Оценки | 4 | GRADE | Оценка | int(11) | YES | |
GROUP_ST | Учебные группы | 1 | ID | Идентификатор | int(11) | PK | NO |
GROUP_ST | Учебные группы | 2 | GROUP_CODE | Код группы | varchar(45) | YES | |
GROUP_ST | Учебные группы | 3 | TEACHER_ID | ИД сотрудника-преподавателя | int(11) | YES | |
GROUP_ST | Учебные группы | 4 | CURATOR_ID | ИД сотрудника-куратора | int(11) | YES | |
STUDENT | Студенты | 1 | ID | Идентификатор | int(11) | PK | NO |
STUDENT | Студенты | 2 | LAST_NAME | Фамилия | varchar(45) | NO | |
STUDENT | Студенты | 3 | FIRST_NAME | Имя | varchar(45) | NO | |
STUDENT | Студенты | 4 | MIDDLE_NAME | Отчество | varchar(45) | YES | |
STUDENT | Студенты | 5 | BIRTHDAY | День рождения | date | YES |
Далее я попробовал получить аналогичный отчёт для PostgreSQL, благо набор представлений INFORMATION_SCHEMA присутствует и здесь. Но вот всех нужных данных (прежде всего, комментариев к полям и таблицам) в этих представлениях мне обнаружить не удалось (возможно, плохо искал). Поэтому я пошёл по альтернативному пути, специфическому для PostgreSQL, обратившись к системным каталогам из схемы PG_CATALOG. Для построения запроса понадобилось пять таблиц и несколько дополнительных ухищрений.
Используемые служебные таблицы:
SELECT
c.relname as "Таблица",
(
SELECT
td.description
FROM
pg_catalog.pg_description td
WHERE
td.objoid = a.attrelid
AND td.objsubid = 0
) as "Комментарий к таблице",
a.attnum as "№ п/п",
a.attname as "Поле",
ad.description as "Комментарий к полю",
pt.typname as "Тип",
CASE WHEN a.atttypmod = -1 THEN NULL ELSE a.atttypmod END "Размер",
a.attnotnull as "NULL",
CASE WHEN a.attnum IN(
SELECT
UNNEST(cn.conkey)
FROM
pg_catalog.pg_constraint cn
WHERE
cn.conrelid = a.attrelid
AND cn.contype LIKE 'p'
) THEN 'PK' END as "Ключ" FROM
pg_catalog.pg_attribute a
JOIN pg_catalog.pg_type pt ON a.atttypid = pt.oid
JOIN pg_catalog.pg_class c ON a.attrelid = c.oid
JOIN pg_catalog.pg_namespace n ON c.relnamespace = n.oid
LEFT JOIN pg_catalog.pg_description ad ON ad.objoid = a.attrelid
AND ad.objsubid = a.attnum
WHERE
a.attnum > 0 AND n.nspname = 'public' and c.reltype <> 0
ORDER BY
c.relname,
a.attnum;
Воркшоп Дарьи Колесовой из Яндекса
«От проектирования до эксплуатации:
реляционные БД и SQL-запросы для аналитика
(на примере PostgreSQL)»
SELECT
cl.owner as "Владелец",
cl.table_name as "Таблица",
tc.comments as "Комментарий к таблице",
cl.internal_column_id as "№ п/п",
cl.column_name as "Поле",
cl.data_type as "Тип",
cl.data_length as "Размер",
cl.data_precision as "Точность",
cl.nullable as "NULL",
cm.comments as "Комментарий к полю"
FROM
sys.all_tab_cols cl
JOIN sys.all_col_comments cm ON cl.owner = cm.owner
AND cl.table_name = cm.table_name
AND cl.column_name = cm.column_name
JOIN sys.all_tab_comments tc ON cl.owner = tc.owner
AND cl.table_name = tc.table_name
WHERE
cl.owner = <имя схемы, если надо>
ORDER BY cl.table_name,
cl.internal_column_id;
SELECT
cl.table_name as "Таблица",
tc.comments as "Комментарий к таблице",
cl.internal_column_id as "№ п/п",
cl.column_name as "Поле",
cl.data_type as "Тип",
cl.data_length as "Размер",
cl.data_precision as "Точность",
cl.nullable as "NULL",
cm.comments as "Комментарий к полю"
FROM
sys.user_tab_cols cl
JOIN sys.user_col_comments cm ON cl.table_name = cm.table_name
AND cl.column_name = cm.column_name
JOIN sys.user_tab_comments tc ON cl.table_name = tc.table_name
ORDER BY
cl.table_name,
cl.internal_column_id
SELECT
*
FROM
MSysObjects o
WHERE
o.Flags = 0 AND o.Type = 1 ORDER BY
o.NAME;
SELECT
*
FROM
sqlite_master m
WHERE
m.type = 'table';
Больше полезных статей