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

(Примечание: я понимаю, что это близко к тому, как вы документируете свою структуру базы данных?, Но я не думаю, что она идентична.)

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

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

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

15.12.2008 18:25:21
Еще раз, полезный вопрос закрылся через несколько лет, из-за жестких правил, которые мы имеем сейчас ...
Georgi Raychev 4.09.2018 12:12:15
Проверьте проект с открытым исходным кодом dbml.org, где вы можете документировать свою базу данных, используя простой DSL, который они создали.
huy 20.10.2019 04:17:03
10 ОТВЕТОВ
РЕШЕНИЕ

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

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

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

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

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

66
15.12.2008 19:06:26
Я согласен с понятными для человека документами, если предположить, что есть кто-то, способный написать это; Мой опыт был необходимыми знаниями, которые покинули компанию, что делает необходимость документирования еще более очевидной.
SqlACID 15.12.2008 19:23:54

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

1
15.12.2008 18:30:51

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

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

8
15.12.2008 18:41:50
Как я уже говорил в исходном вопросе, я не могу изменить схему и не могу изменить сценарии, которые поддерживают схему. Поэтому я не могу добавлять комментарии ни к чему, кроме тестовой базы данных на моем собственном компьютере, и это регулярно сдувается и воссоздается.
Paul Tomblin 15.12.2008 18:47:50
Вы не меняете схему, когда добавляете комментарии. Но я ценю ситуацию с тупой бюрократией базы данных.
Steven Huwig 15.12.2008 19:46:04
Но комментирование для столбцов и таблиц ограничено в базе данных information_schema, поэтому, возможно, комментировать таблицы и столбцы, как вы ответили, бесполезно.
shgnInc 6.09.2015 09:42:57
комментарии в information_schema могут содержать json
NaturalData 24.03.2018 16:37:02

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

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

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

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

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

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

7
23.05.2017 11:47:23
где я могу увидеть generate custom templated documentationв EA?
William Kinaan 9.04.2013 06:24:27
Давайте посмотрим ... Я думаю, что вы щелкните правой кнопкой мыши на что-то справа и выберите Generate. Это на версии от 5 лет назад. Проверьте восьмой пункт вниз: sparxsystems.com/products/ea/index.html
Kieveli 9.04.2013 13:10:01
Спасибо за ваш повтор. Щелкните правой кнопкой мыши -> Документация-> Отчет RTCH Text Format (RTF), затем выберите data model templateв поле Использовать шаблон.
William Kinaan 9.04.2013 14:59:11

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

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

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

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

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

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

3
15.12.2008 18:58:21
Билл - вы когда-нибудь использовали Visiomodeler (Object Role Modeling), et. и др.?
dkretz 15.12.2008 19:05:54
Нет, я никогда не использовал это. Но сейчас оно кажется старым и неподдерживаемым.
Bill Karwin 15.12.2008 19:10:22
Это; но для него нет замены, совместимой с плагином (пока - по крайней мере, есть один проект SourceForge на ранних стадиях для плагина VS, интересно. Я из тех, кто по своей природе игнорирует мой собственный евангелизм для него, но это на самом деле большой шаг за пределы ERD.
dkretz 15.12.2008 19:15:41
Я использовал Object Role Modeling. Это не имеет ничего общего с документированием уже существующих или вновь созданных баз данных
Gennady Vanin Геннадий Ванин 8.10.2010 17:12:20

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

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

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

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

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

3
15.12.2008 19:19:36
Терри Хэлпин подробно объясняет ORM или моделирование ролей объектов в tinyurl.com/8h296m
Ruben 22.12.2008 15:32:21
Какое отношение имеет ObjectRoleModeling к документированию существующих баз данных RDBMS?
Gennady Vanin Геннадий Ванин 8.10.2010 17:07:57
Одним из вариантов является использование функции обратного инжиниринга для извлечения вашей схемы и ее загрузки - она ​​отлично работает по моему опыту.
dkretz 27.10.2010 06:56:56

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

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

Если у вас есть терпение, то использование HTML для документирования таблиц и столбцов облегчает доступ к вашей документации.

0
15.12.2008 21:31:57

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

4
4.05.2011 07:10:00
Пожалуйста, предоставьте резюме на случай, если ссылка не работает.
przemo_li 24.05.2018 13:11:47

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

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

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

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

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

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

Диаграммы:

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

Описания:

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

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

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

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

Ноты

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

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

1
23.06.2015 10:08:03