Как документировать структуру базы данных? [закрытый]
многие системы баз данных не допускают комментариев или описаний таблиц и полей, поэтому как вы документируете цель таблицы/поля, кроме очевидного наличия хороших соглашений об именах?
(предположим, что" отличные " имена таблиц и полей недостаточно для документирования полного значения каждой таблицы, поля и отношения в базе данных.)
Я знаю, что многие люди используют диаграммы UML для визуализации базы данных, но я редко-если когда-либо видел диаграмму UML, включая комментарии к полю. Тем не менее, у меня есть хороший опыт использования комментариев внутри .sql файлы. Недостатком этого подхода является то, что он требует .sql файлы, которые будут вручную обновляться по мере изменения структуры базы данных с течением времени, но если вы это сделаете, вы также можете иметь его под контролем версий.
некоторые другие методы, которые я видел, - это отдельный документ, описывающий структуру базы данных и отношения и вручную поддерживаемые комментарии внутри кода ORM или другой код сопоставления базы данных.
Как вы решили эту проблему в прошлом? Какие существуют методы и какие с ними связаны различные плюсы и минусы? Как бы вы хотели, чтобы это было решено в"идеальном мире"?
обновление
как указывали другие, большинство популярных SQL-движков действительно позволяют комментарии, что здорово. Как ни странно, люди, похоже, не используют эти функции много. По крайней мере, не на проектах, которые у меня есть был связан с прошлым.
12 ответов
в MySQL позволяет комментарии к таблицам и строкам. В PostgreSQL тут Как хорошо. Из других ответов Oracle и MSSQL также имеют комментарии.
для меня комбинация диаграммы UML для быстрого обновления имен полей, типов и ограничений и внешнего документа (TeX, но может быть любым форматом) с расширенным описанием всего, что связано с базой данных-специальные значения, комментарии полей, Примечания доступа, что угодно - работает лучше всего.
поздно, но, надеюсь, полезным… Вот процесс, который мы использовали при разработке относительно большой базы данных (около 100 таблиц и около 350 объектов в общей сложности)
- разработчики должны были использовать расширенные свойства для добавления деталей ко всем объектам.
- администраторы отклонили любой DDL, который не имел расширенных свойств
- сторонний инструмент использовался для автоматического создания визуальной документации через интерфейс командной строки каждый день. Мы использовали ApexSQL Doc и он работал просто отлично, но я также успешно использовал SQL Doc от Red Gate в другой компании.
этот процесс гарантировал, что у нас есть все объекты, документировать и документы до дата.
трудная вещь, хотя заставляла разработчиков писать хорошие комментарии последовательно;)
SQL Server имеет расширенные свойства, которые могут позаботиться об этом.
в этой статье описывается, как настроить их в SQL Sever http://www.developer.com/db/article.php/3677766
его можно использовать совместно с RedGate SQL Doc чтобы создать хороший словарь данных.
Я использую комментарии к таблицам и столбцам. SchemaSpy - отличный инструмент для создания файлов документации html из вашей схемы, включая комментарии.
в какой-то момент я написал базовый синтаксический анализатор SQL, который будет анализировать инструкции CREATE TABLE и удалять специально отформатированные комментарии. Затем они были обработаны в источник LaTeX и переданы в PDF. Это было вдохновлено Javadoc и был использован для создания документации для этот продукт. Впоследствии в менеджер хранилища была встроена функция словаря данных, и измененная версия генератора LaTeX использовалась для отображения словаря данных из менеджер склада.
в другом проекте я использовал Visio-версия, которая поставляется с Visual Studio Enterprise Architect, будет перенаправлять инженер базы данных. Созданный таким образом SQL имел комментарии таблицы и столбца, отображаемые в строках комментариев, которые были довольно просты для анализа. Инструмент, который я написал, создал MIF-файлы, которые были включены в документ спецификации, построенный с FrameMaker.
Если у вас есть инструмент репозитории, такие как Powerdesigner вы можете поддерживайте в нем модели данных и получайте отчеты репозитория, включающие введенную документацию. Если вам нужна более глубокая интеграция словаря данных с функциональными спецификациями (весьма полезная для систем хранилища данных, где ETL является сложным и включает в себя значительное вычисление производных значений), вы все равно можете извлечь метаданные и написать утилиту для создания чего-то, что интегрирует словарь данных в документ спецификации. Это также позволяет перекрестные ссылки между элементами словаря данных и другими документами спецификации и генерацией индексов, которые охватывают определения словаря данных и связанную документацию, такую как спецификация того, как что-то вычисляется с примерами.
мы написали документ word, в котором перечислены таблицы, поля и все, что делает. Это подкрепляется диаграммой, которая показывает, как все связывает/относится друг к другу. Это довольно простой документ, просто загрузка таблиц с именем Поля > тип данных > цель
Я использую Жар который имеет поле описания для всех системных объектов (таблиц, столбцов, представлений, процедур и параметров, триггеров и т. д.) Это хорошо, потому что вы можете легко поделиться им с другими (документы идут с базой данных, а не отдельно), и вы никогда не потеряете его.
большинство админ. инструменты для Firebird позволяют редактировать эти описания, и есть некоторые специализированные инструменты (например, IBDesc), которые создают хорошие отчеты HTML или PDF, которые вы можете распечатать (для некоторых или всех таблицы) легко.
Это действительно упрощенный подход, но я использую пару вики-страниц: одну с mysqldump базы данных и одну, написанную в немного более английском формате.
для проектов, над которыми я работал, этого было достаточно (через десятки уровней таблиц). Я не знаю, насколько хорошо он может масштабироваться для более крупных проектов (скажем, в сотнях таблиц), но до сих пор это было хорошо.
я комментирую свои базы данных, как я комментирую свои программы. Написав хорошие (я надеюсь) комментарии в исходном коде (файл SQL, содержащий инструкции DDL).
использование SQL COMMENT-еще одна возможность. Хорошо с ними то, что они всегда с вашими объектами, подкреплены ими и т. д. Плохо то, что они более ограничены (например, по длине).
поскольку мы используем Rational Software Architect, мы используем его функции обнаружения данных для документирования наших баз данных, а затем аннотирования их оттуда.
в Oracle вы можете комментировать таблицы, и он сохраняет его в словаре данных.
тем не менее, я храню все свои комментарии таблицы, столбца, индекса в очень старой версии ERWin. Это главный источник истины и генерирует DDL для создания таблиц и т. д. Оттуда я могу извлечь его в документ word или pdf.
недавно я обратился к написанию документации markdown, которая включает ссылку на отдельную таблицу .sql файлы (где таблицы и поля, надеюсь, интуитивно им с большим количеством комментариев).
Я сохраняю схему отдельной таблицы в системе управления версиями, используя следующую команду:
mysqldump --no-data --tab=./tables dbname
схема для одной таблицы позволяет видеть комментарии, индексы, уникальные ключи и т. д. так что довольно самоочевидно (ну, это идея в наименьший.)
в документации master markdown есть гиперссылки, такие как таблица пользователя, поэтому читатель может легко перейти к различным таблицам.