Как документировать базу данных

Ответ 1

По моему опыту, диаграммы ER (или UML) не являются самым полезным артефактом - с большим количеством таблиц, диаграммы (особенно обратные инженерные) часто представляют собой большой запутанный беспорядок, от которого никто ничего не узнает.

Для моих денег какая-то хорошая человеко-читаемая документация (возможно, дополненная диаграммами меньших частей системы) даст вам наибольший пробег. Это будет включать в себя для каждой таблицы:

• Описания того, что означает таблица и как оно функционально используется (в пользовательском интерфейсе и т.д.).
• Описания того, что означает каждый атрибут, если это не очевидно
• Объяснения отношений (внешние ключи) из этой таблицы в другие и наоборот
• Объяснения дополнительных ограничений и/или триггеров
• Дополнительное объяснение основных видов и процессов, которые касаются таблицы, если они уже не документированы уже

Со всем вышесказанным, не документируйте ради документирования - документация, которая повторяет очевидное, просто попадает по-человечески. Вместо этого сосредоточьтесь на том, что сначала смутило вас, и потратьте несколько минут, написание действительно ясных и лаконичных объяснений. Это поможет вам продумать это, и оно будет активно помогать другим разработчикам, которые впервые сталкиваются с этими таблицами.

Как уже упоминалось, существует множество инструментов, которые помогут вам справиться с этим, например Enterprise Architect, Red Gate SQL Doc и встроенные инструменты от разных поставщиков. Но в то время как поддержка инструментов является полезной (и даже критической, в больших базах данных), тяжелая работа по пониманию и объяснению концептуальной модели базы данных является реальной победой. С этой точки зрения, вы можете даже сделать это в текстовом файле (хотя делать это в Wiki-форме позволило бы нескольким людям сотрудничать при добавлении к этой документации поэтапно - так, каждый раз, когда кто-то что-то выясняет, они могут добавить его в растущее тело документации моментально).

Ответ 2

Мы используем Enterprise Architect для наших определений БД. Мы включаем хранимые процедуры, триггеры и все определения таблиц, определенные в UML. Три блестящие особенности программы:

• Импортировать диаграммы UML из ODBC-соединения.
• Сгенерировать SQL-скрипты (DDL) для всего БД сразу
• Создание пользовательской шаблонной документации вашей БД.

Вы можете редактировать определения классов/таблиц в инструменте UML и генерировать полностью описательный документ с включенным изображением. Автогенерированный документ может быть в нескольких форматах, включая MSWord. У нас всего лишь 100 таблиц в нашей схеме, и это вполне управляемо.

Я никогда не был впечатлен каким-либо другим инструментом за 10 лет в качестве разработчика. EA поддерживает Oracle, MySQL, SQL Server (несколько версий), PostGreSQL, Interbase, DB2 и Access одним махом. Каждый раз, когда у меня были проблемы, их форумы быстро отвечали на мои проблемы. Очень рекомендуется!

Когда происходят изменения БД, мы делаем это в EA, генерируем SQL и проверяем его на наш контроль версий (svn). Мы используем Hudson для построения, и он автоматически создает базу данных из сценариев, когда видит, что вы модифицировали зарегистрированный sql.

(В основном украден из другого моего ответа)

Ответ 3

В нашей команде мы пришли к полезному подходу к документированию старых баз данных Oracle и SQL Server. Мы используем Dataedo для документирования элементов схемы базы данных (словаря данных) и создания диаграмм ERD. Dataedo поставляется с репозиторием документации, поэтому вся ваша команда может работать над документированием и чтением недавней документации в Интернете. И вам не нужно вмешиваться в базу данных (комментарии Oracle или SQL Server MS_Description).

Сначала вы импортируете схему (все таблицы, представления, хранимые процедуры и функции - с помощью триггеров, внешних ключей и т.д.). Затем вы определяете логические домены/модули и группируете все объекты (перетаскивание) в них, чтобы иметь возможность анализировать и работать с меньшими фрагментами базы данных. Для каждого модуля вы создаете диаграмму ERD и записываете описание верхнего уровня. Затем, когда вы обнаружите значение таблиц и представлений, напишите краткое описание для каждого. Сделайте то же самое для каждого столбца. Dataedo позволяет вам добавлять значащее название для каждого объекта и столбца - полезно, если имена объектов неопределенны или недействительны. Pro позволяет вам описывать внешние ключи, уникальные ключи/ограничения и триггеры - что полезно, но не обязательно для понимания базы данных.

Вы можете получить доступ к документации через пользовательский интерфейс или экспортировать ее в PDF или интерактивный HTML (последний доступен только в версии Pro).

Здесь описывается непрерывный процесс, а не одно время. Если ваша база данных изменяется (например, новые столбцы, представления), вы должны регулярно синхронизировать свою документацию (пару кликов с помощью Dataedo).

См. примерную документацию: http://dataedo.com/download/Dataedo%20repository.pdf

Некоторые рекомендации по процессу документирования:

Диаграммы:

• Держите ваши диаграммы маленькими и читабельными - просто включите важные таблицы, отношения и столбцы - только те, которые имеют какое-либо значение для понимания большой картины - первичные/бизнес-ключи, важные атрибуты и отношения,
• Используйте другой цвет для таблиц ключей на диаграмме,
• Вы можете иметь более одной диаграммы для каждого модуля,
• Вы можете добавить диаграмму к описанию наиболее важных таблиц/с большинством отношений.

Описания:

• Не документируйте очевидное - не записывайте описание "Дата документа" для столбца document.date. Если нет ничего значимого для добавления, просто оставьте его пустым,
• Если объекты, хранящиеся в таблицах, имеют типы или статусы, полезно их перечислить в общем описании таблицы,
• Определите формат, который ожидается, например. "mm/dd/yy" для даты, которая хранится в текстовом поле,
• Список всех известных/важных значений и их значение, например. для столбца состояния может быть что-то вроде этого: "Статус документа: A - Активен, C - Отменено, D - Удалено",
• Если любой API для таблицы - представление, которое должно использоваться для чтения данных и функций/процедур для вставки/обновления данных, - перечислите его в описании таблицы,
• Опишите, откуда берутся строки/столбцы (процедура, форма, интерфейс и т.д.),
• Используйте "[устаревший]" знак (или аналогичный) для столбцов, которые не должны использоваться (поле столбца полезно для этого, объясните, какое поле должно использоваться вместо этого в поле описания).

Ответ 4

Одна вещь, которую следует учитывать, - это средство COMMENT, встроенное в СУБД. Если вы разместите комментарии ко всем таблицам и всем столбцам самой СУБД, ваша документация будет находиться в системе базы данных.

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

Ответ 5

Этот ответ расширяет Кивели выше, который я поддерживал. Если ваша версия EA поддерживает Object Role Modeling (концептуальный дизайн, по сравнению с логическим дизайном = ERD), перепроектируйте это, а затем заполните модель выразительным богатством, которое она дает вам.

Дешевый и более легкий вариант - загрузить Visiomodeler бесплатно с MS и сделать то же самое с этим.

ORM (называть его ORMDB) - единственный инструмент, который я когда-либо нашел, который поддерживает и поощряет разговоры о дизайне базы данных с заинтересованными сторонами, не связанными с IS, о объектах и ​​отношениях BL.

Проверка реальности - на пути к генерации DDL она проходит через фазу полной остановки ERD, где вы можете удовлетворять свои вопросы о том, что она делает что-то острое. Это не так. Это, вероятно, покажет вам слабые места в ERD, который вы сами создали.

ORMDB - это классический случай принципа: чем концептуальнее инструмент, тем меньше рынок. Девушки просто хотят повеселиться, а программисты просто хотят закодировать.

Ответ 6

Вот хорошая статья о том, как подойти к документации по базе данных: http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and-how/

Ответ 7

Решение wiki поддерживает гиперссылки и совместное редактирование, но вики не хуже, чем люди, которые поддерживают его и обновляют. Вам нужно, чтобы кто-то владел проектом документа, независимо от того, какой инструмент вы используете. Этот человек может привлекать других знающих людей для заполнения деталей, но один человек должен нести ответственность за организацию информации.

Если вы не можете использовать инструмент для создания ERD с помощью обратного проектирования, вам придется создавать его вручную, используя TOAD или VISIO.

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

Вы также можете создать псевдо-ERD, где группы таблиц представлены одним объектом на одной диаграмме, а эта группа расширена на другой диаграмме.

Единственной ERD или набором ERD недостаточно для документирования системы этой сложности, не более, чем диаграмма классов, достаточная для документирования OO-системы. Вам нужно будет написать документ, используя ERD в качестве иллюстраций. Вам нужны текстовые описания значения и использования каждой таблицы, каждого столбца и связей между таблицами (особенно там, где такие отношения неявны, а не представлены ограничениями ссылочной целостности).

Все это большая работа, но это того стоит. Если есть четкое и современное место, где схема документирована, вся команда выиграет от нее.

Ответ 8

Поскольку у вас есть роскошь работать с другими разработчиками, которые находятся в одной лодке, я бы предложил расспросить их, что они чувствуют, передавая необходимую информацию, наиболее легко. У моей компании более 100 таблиц, и мой босс дал мне ERD для определенных таблиц набора, которые все подключаются. Таким образом, вы можете попробовать сломать 1 массивную ERD в кучу меньших управляемых ERD.

Ответ 9

Если описание ваших баз данных конечным пользователям является вашей основной целью Ooluk Data Dictionary Manager может оказаться полезным. Это веб-многопользовательское программное обеспечение, которое позволяет присоединять описания к таблицам и столбцам и позволяет выполнять полнотекстовый поиск по этим описаниям. Он также позволяет вам логически группировать таблицы с помощью меток и просматривать таблицы с помощью этих меток. Таблицы, а также столбцы могут быть помечены для поиска похожих элементов данных в вашей базе данных/базах данных.

Программное обеспечение позволяет импортировать данные метаданных, такие как имя таблицы, имя столбца, тип данных столбца, внешние ключи во внутренний репозиторий с использованием API. Поддержка источников данных JDBC встроена и может быть расширена по мере распространения источника API в ASL 2.0. Он кодируется для чтения КОММЕНТАРИИ/ЗАМЕЧАНИЯ из многих RDBMS. Вы всегда можете вручную переопределить импортированную информацию. Информация, которую вы можете хранить о таблицах и столбцах, может быть расширена с помощью настраиваемых полей.

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

Примечания

• При описании технических аспектов вашей базы данных, таких как триггеры, индексы, статистика важна, что это программное обеспечение не самый лучший вариант. Однако можно объединить техническое решение с этим программное обеспечение, использующее настраиваемые поля гиперссылки.
• Программное обеспечение не создает ERD

Раскрытие информации: Я работаю в компании, которая разрабатывает этот продукт.

Ответ 10

Ну, изображение говорит тысячу слов, поэтому я бы рекомендовал создавать диаграммы ER, где вы можете сразу просмотреть взаимосвязь между таблицами, что трудно сделать с описанием только для текста.

Вам не нужно делать всю базу данных на одной диаграмме, разбивать ее на разделы. Мы используем Visual Paradigm на работе, но EA - хорошая альтернатива, как ERWIN, и, несомненно, есть много других, которые так же хороши.

Если у вас есть терпение, то с помощью html для документирования таблиц и столбцов упрощается доступ к документации.