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

Question

. (Примечание: Я понимаю, что это близко к How do you document your database structure?, но я не думаю, что это идентично)

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

Я попытался использовать «Жаба», чтобы создать диаграмму ER, но, оставив ее в течение 48 часов подряд, она все еще ничего не выдавала, и мне нужен был мой компьютер. Я говорил с некоторыми другими недавними нанимателями, и все мы предположили, что всякий раз, когда мы озадачиваем, что такое конкретная таблица или какие-то ее столбцы, мы должны обновить ее в вики разработчиков.

Так что это хороший способ сделать это? Просто перечислите таблицы/представления и их столбцы и заполните их, когда мы идем? Основными инструментами, которые мне нужны, являются Toad, Oracle SQL Developer, MS Office и Visio.

Answer 1

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

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

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

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

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

Answer 2

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

Answer 3

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

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

Answer 4

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

1. Импорт UML-диаграмм из ODBC-соединения.
2. Сгенерировать SQL-скрипты (DDL) для всего БД сразу
3. Создать пользовательскую Templated Documentation вашей БД.

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

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

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

(Mostly stolen from another answer of mine)

Answer 5

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

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

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

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

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

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

Answer 6

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

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

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

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

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

Answer 7

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

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

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

Answer 8

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

Answer 9

В нашей команде мы пришли к полезному подходу к документированию унаследованных больших баз данных 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» для даты, которая хранится в текстовом поле,
• Перечислите все известные/важные значения an, что означает, например. для столбца статуса может быть примерно так: «Статус документа: A - Активен, C - Отменен, D - Удален»,
• Если есть какой-либо API для таблицы - представление, которое должно использоваться для чтения данных и функций/процедур вставить/обновить данные - перечислить их в описании таблицы,
• Опишите, откуда берутся строки/столбцы (процедура, форма, интерфейс и т. д.),
• Использовать знак [[устаревший] »(или аналогичный) для столбцов, которые не должны использоваться (поле столбца полезно для этого, объясните, какое поле должно использоваться вместо этого в поле описания).

Answer 10

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

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

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

Примечания

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

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