Как вы документируете свои базы данных?
Я считаю, что большинство моих клиентов вообще не документируют свои базы данных, и я нахожу это довольно страшным. Чтобы внедрить некоторую более эффективную практику, я хотел бы знать, какие инструменты /процессы используют люди.
- Как вы документируете свою базу данных? (SQL-Server)
- Какой инструмент вы используете?
- Формат хранения документации для схемы базы данных /метаданных?
- Документы Word
- Таблица Excel
- Обычный текст
- Процесс или политика документирования?
Я не говорю об обратном проектировании /документировании существующей базы данных, но главным образом о лучших примерах документации при разработке вашей системы /базы данных.
16 ответов
Я использую расширенные свойства, так как они очень гибкие. Большинство стандартных инструментов документации можно отключить MS_Description
, а затем вы можете использовать свои собственные с помощью специальных инструментов.
См. эту презентацию: # 41-Получить рычаг и выбрать любую черепаху: Подъем с метаданными
И этот код: http://code.google.com/p/caderoux/wiki/LeversAndTurtles
Microsoft Visio Pro (вверх to Visio 2010) может перепроектировать базу данных, а CA ERwin . Visio - более дешевый вариант, но ERwin - это более подробный, более полный вариант. Расширенные свойства хороши, если люди не хотят смотреть на них. Вы также можете использовать что-то вроде документа Docs , например, вывода в формате HTML.
Я нахожу соглашения об именах и правильной настройке внешних ключей приводят к созданию почти самодокументируемой базы данных. У вас все еще должны быть внешние документы для лучшего понимания цели.
Попробуйте SchemaSpy: http://schemaspy.sourceforge.net/
Для SQL Server я использую расширенные свойства.
С помощью следующего сценария PowerShell я могу сгенерировать сценарии Create Table для отдельной таблицы или для всех таблиц в схеме dbo.
Сценарий содержит команду Create table
, первичные ключи и индексы. В качестве комментариев добавляются внешние ключи.
Расширенные свойства таблиц и столбцов таблицы добавляются в виде комментариев. Да, поддерживаются свойства нескольких строк.
Сценарий настроен на мой личный стиль кодирования.
-
нет отдельных сопоставлений для отдельных столбцов.
-
в настоящее время требуется сервер Sql Аутентификация.
Вот полный код, чтобы превратить расширенные свойства в хороший простой старый ASCII-документ (BTW он действительно sql для воссоздания ваших таблиц):
функция Get-ScriptForTable
{
param (
$ Сервер,
$ Имя_бд,
$ Пользователю,
$ Пароль,
$ фильтр
)
[System.reflection.assembly] :: LoadWithPartialName ("Microsoft.SqlServer.Smo") | из-нуль
[System.Reflection.Assembly] :: LoadWithPartialName ("Microsoft.SqlServer.ConnectionInfo") | из-нуль
$ conn = new-object "Microsoft.SqlServer.Management.Common.ServerConnection"
$ conn.ServerInstance = $ server
$ conn.LoginSecure = $ false
$ conn.Login = $ user
$ conn.Password = $ password
$ conn.ConnectAsUser = $ false
$ srv = Новый объект «Microsoft.SqlServer.Management.Smo.Server» $ conn
$ Scripter = new-object ("Microsoft.SqlServer.Management.Smo.Scripter")
# $ Scripter.Options.DriAll = $ false
$ Scripter.Options.NoCollation = $ True
$ Scripter.Options.NoFileGroup = $ true
$ scripter.Options.DriAll = $ True
$ Scripter.Options.IncludeIfNotExists = $ False
$ Scripter.Options.ExtendedProperties = $ false
$ Scripter.Server = $ srv
$ database = $ srv.databases [$ dbname]
$ obj = $ database.tables
$ cnt = 1
$ obj | % {
if (! $ filter -или $ _. Name -match $ filter)
{
$ lines = @ ()
$ header = "---------- {0, 3} {1, -30} ----------" -f $ cnt, $ _. Имя
Write-Host $ header
"/* ----------------- {0, 3} {1, -30} -----------------" - f $ cnt, $ _. Имя
foreach ($ i в $ _. ExtendedProperties)
{
"{0}: {1}" -f $ i.Name, $ i.value
}
«»
$ colinfo = @ {}
foreach ($ i в столбцах $ _.)
{
$ info = ""
foreach ($ ep в $ i.ExtendedProperties)
{
if ($ ep.value -match "` n ")
{
"----- Столбец: {0} {1} -----" -f $ i.name, $ ep.name
$ ep.value
}
еще
{
$ info + = "{0}: {1}" -f $ ep.name, $ ep.value
}
}
if ($ info)
{
$ colinfo [$ i.name] = $ info
}
}
«»
"SELECT COUNT (*) FROM {0}" -f $ _. Имя
"SELECT * FROM {0} ORDER BY 1" -f $ _. Имя
"--------------------- {0, 3} {1, -30} ----------------- * /"-f $ cnt, $ _. Имя
«»
$ raw = $ Scripter.Script ($ _)
# Write-host $ raw
$ cont = 0
$ skip = $ false
foreach ($ line в $ raw -split "\ r \ n")
{
if ($ cont -gt 0)
{
if ($ line -match "^ \) WITH")
{
$ line = ")"
}
$ linebuf + = '' + $ line -replace "ASC", ""
$ cont--
if ($ cont -gt 0) {continue}
}
elseif ($ line -match "^ CONSTRAINT")
{
$ cont = 3
$ linebuf = $ line
Продолжать
}
elseif ($ line -match "^ UNIQUE")
{
$ cont = 3
$ linebuf = $ line
$ skip = $ true
Продолжать
}
elseif ($ line -match "^ ALTER TABLE. * WITH CHECK")
{
$ cont = 1
$ linebuf = "-" + $ line
Продолжать
}
elseif ($ line -match "^ ALTER TABLE. * CHECK")
{
Продолжать
}
еще
{
$ linebuf = $ line
}
if ($ linebuf -notmatch "^ SET")
{
if ($ linebuf -match "^ \) WITH")
{
$ lines + = ")"
}
elseif ($ skip)
{
$ skip = $ false
}
elseif ($ linebuf -notmatch "^ \ s * $")
{
$ linebuf = $ linebuf -replace "\] | \ [", ""
$ comment = $ colinfo [($ linebuf.Trim () -split "") [0]]
if ($ comment) {$ comment = '-' + $ comment}
$ lines + = $ linebuf + $ comment
}
}
}
$ lines + = "go"
$ lines + = ""
$ block = $ lines -join "` r`n "
$ блок
$ CNT ++
$ used = $ false
foreach ($ i в $ _. Индексы)
{
$ out = ''$ raw = $ Scripter.Script ($ i)
# Write-host $ raw
foreach ($ line в $ raw -split "\ r \ n")
{
if ($ line -match "^ \) WITH")
{
$ out + = ")"
}
elseif ($ line -match "^ ALTER TABLE. * PRIMARY KEY")
{
ломать
}
elseif ($ line -match "^ ALTER TABLE. * ADD UNIQUE")
{
$ out + = $ line -replace "\] | \ [", "" -replace "NONCLUSTERED", ""
}
elseif ($ line -notmatch "^ \ s * $")
{
$ out + = $ line -replace "\] | \ [", "" -replace "^ \ s *", "" `
- замените «ASC», «,» - замените «ASC $», «» `
<# - заменить "\ bdbo \. \ b", "" #> `
- замените "НЕПРЕРЫВНО", ""
}
$ used = $ true
}
$ block = "$ out;` r`ngo`r`n "
$ из
}
if ($ used)
{
"идти"
}
}
}
}
Вы можете либо сценарий полной схемы dbo данной базы данных
Get-ScriptForTable 'localhost' 'MyDB' 'sa' 'toipsecret' | Out-File "C: \ temp \ Create_commented_tables.sql"
Или фильтр для отдельной таблицы
Get-ScriptForTable 'localhost' 'MyDB' 'sa' 'toipsecret' 'OnlyThisTable'
Взгляните на SchemaCrawler - это мой бесплатный инструмент командной строки, который я разработал, чтобы делать то, что вы ищете. SchemaCrawler создает текстовый файл со всеми объектами схемы базы данных. Этот текстовый вывод предназначен как для чтения человеком, так и для него несовместимого с аналогичным выходом с другого сервера.
На практике я обнаружил, что вывод текстового файла схемы базы данных полезен, когда выполняется как часть сборки. Таким образом, вы можете проверить текстовый файл в вашей системе управления исходным кодом и иметь историю версий того, как ваша схема эволюционировала с течением времени. SchemaCrawler предназначен для автоматизации этого также из командной строки.
Если это когда-либо написано, документация состоит из словарного документа. Будет приведена пара диаграмм отношений. Списки таблиц и краткое описание того, что каждая таблица имеет и как она относится к другим таблицам. В одной главе документации содержатся параметры безопасности: какие разрешения имеет «пользователь», который требуется приложению?
Как правило, в компаниях, над которыми я работал, документация по базам данных только записывается, когда клиент выполняет аудит, который, как правило, ограничивает использование финансовых и государственных клиентов.
Отказ от ответственности: слишком многие разработчики считают, что код - это документация , и я тоже виноват в этом.
Смешно, мне было интересно, как это делают другие люди.
При разработке моего первого проекта большой базы данных я обнаружил, что Microsoft SQL Server Management Studio 10.0.1600.22 поддерживает диаграммы баз данных, которые вы можете экспортировать в текстовый документ или другое программное обеспечение для документации, где вы можете добавить столько подробной документации, сколько хотите. Просто разверните базу данных, к которой вы подключились, в SQL Management Studio и щелкните правой кнопкой мыши на «диаграммах базы данных» в проводнике объектов и выберите «Новая диаграмма базы данных», чтобы создать интерактивную диаграмму, в которой будут показаны все отношения между различными таблицами. Вы даже можете указать, какие таблицы вы хотите включить в диаграммы, чтобы изображение не становилось неуравновешенным, если вы просто пытаетесь задокументировать его по частям. Экспортируйте изображение в любое другое программное обеспечение для редактирования и прокомментируйте столько, сколько хотите.
Я также рекомендую множество /комментариев /в скрипте, который генерирует вашу базу данных.
Как правило, много работы записывает то, для чего все для этого, но хорошая идея надолго, например, когда вы или какая-то другая бедная душа вернется, чтобы обновить свое творение пару лет спустя! :)
Я использую расширенные свойства и Red Dates SQL Doc. Хорошо работает!
Я устанавливаю расширенное свойство MS_description для всех объектов, а затем документирую всю базу данных, используя ApexSQL Doc . Раньше я использовал HTML-документы, но в последнее время предпочитаю PDF
Я использую инструменты моделирования данных, потому что они позволяют мне документировать важную информацию о базе данных, отличную от того, что «подходит» в базе данных. Метаданные, такие как конфиденциальность /безопасность /чувствительность, управление, управление и т. Д.
Это может выходить за рамки того, что необходимо для документирования базы данных, но эти вещи важны для бизнеса и помогают им управлять своими данными.
Формальные инструменты также помогают мне в управлении данными, которые хранятся в нескольких базах данных /экземпляре /сервере. Это никогда не было более правдоподобным, чем в нашем мире приложений.
Для документирования SQL-сервера я настоятельно рекомендую недавно опубликовать:
SQL Server & Документация Windows с использованием Windows PowerShell , написанная Кендалом Ван Дайком
Краткое описание по ссылке:
SQL Power Doc - это набор сценариев и модулей Windows PowerShell, которые открывают, документируют и диагностируют экземпляры SQL Server и их базовые ОС Windows и amp; машинные конфигурации. SQL Power Doc работает со всеми версиями SQL Server с SQL Server 2000 по 2012 год, а все версии Windows Server и потребительские операционные системы Windows из Windows 2000 и Windows XP через Windows Server 2012 и Windows 8. Документ SQL Power Doc также способен документировать Базы данных Windows Azure SQL.
Создатель словаря DB
- это инструмент для документирования базы данных с открытым исходным кодом с достойным графическим интерфейсом и параметрами экспорта /импорта. Он использует расширенные свойства для хранения документации. Он также генерирует автоматические описания столбцов первичного ключа и столбцов внешнего ключа.
Действительно, расширенные свойства (MS_Description) - это путь. Наличие этих описаний, легко доступных как часть метаданных, может быть использовано не только генераторами документов, но также (надеюсь, в один прекрасный день) с помощью инструментов, которые предоставляют «intellisense», например, отличный помощник Softtree SQL Assistant http://www.softtreetech.com/isql.htm (последний раз, когда я их не проверял) или встроен в Intellisense SQL Sever Management Studio (начиная с sql2008)
Я также считаю, что разработчикам и администраторам баз данных должно быть легко добавить эти примечания, потому что, как правильно указали Tangurena и Nick Chammas, разработчики очень неохотно поддерживают обновление документов и ненавидят дублирующую работу - что достаточно справедливо, особенно для человека которому учили оптимизировать вещи на протяжении всей своей профессиональной жизни. Поэтому, если действительно очень просто обновить документы в одном месте рядом с исходным кодом - это не сработает. В какой-то момент я обыскал в Интернете и не нашел решения для этого, поэтому я написал LiveDoco (не бесплатно, извините), пытаясь сделать это легко. Больше информации здесь, если интересно: http://www.livedoco.com/why-livedoco
Вы также можете посмотреть wsSqlSrvDoc . Это хороший инструмент, который работает с расширенными свойствами SQL Server и создает документ MS Word.
Отпечаток всех свойств столбца (с отношениями внешних ключей) работает из коробки. Для получения дополнительных описаний в каждом поле вам необходимо настроить расширенные свойства этих столбцов в SQL Server Management Studio.
Это не бесплатно, а вполне доступно. Если вам просто нужно создать документацию для базы данных «не работает», которая более или менее закончена, чем было бы достаточно для бесплатной пробной версии.
Мы используем Dataedo для создания словаря данных, хранимых процедур и функций документа. Мы вставляем ERD, созданные в Visio. Вся документация хранится в репозитории метаданных Dataedo (форматированный текст), и мы экспортируем его в HTML для внутреннего использования или экспортируем в PDF для печатного документа.
Мы назначаем каждый объект модулю и назначаем каждый модуль человеку. Dataedo поставляется с отчетами о статусе документации, поэтому мы можем сказать, есть ли новый столбец или таблица, которые необходимо документировать.
Вы можете использовать регулярные комментарии -
-prefixed в файле .sql
.
Преимущества включают, что документация связана с кодом схемы базы данных, и вы можете легко передать ее системе управления версиями, например
Вы также можете использовать некоторый синтаксис с сходством jsDoc / phpDoc . Или вы можете использовать синтаксис MarkDown. - Таблица для хранения сведений о людях.
- @column {int} PersonID - столбец id.
- @column {varchar} LastName - фамилия человека.
- @column {varchar} FirstName - имя человека.
- @column {varchar} Адрес - Адрес проживания.
- @column {varchar} Город - Город проживания.
- @see {@link https://example.com/|Example}
- @author Jane Smith <[email protected]>
- @copyright Acme 2018
- @license BSD-2-оговорка
- @todo Добавить столбец для адреса электронной почты.
- @since 1.0.1
- @version 1.2.3
СОЗДАТЬ ТАБЛИЦЫ Лица (
PersonID int,
LastName varchar (255),
FirstName varchar (255),
Адрес varchar (255),
Город варчар (255)
);
- # Лица
- Таблица для хранения сведений о ** **.
- * `PersonID` - столбец id.
- * `LastName` - имя пользователя _last_.
- * `FirstName` - имя _first_ человека.
- * «Адрес» - адрес проживания.
- * Город - Город проживания.
-
- [Я - ссылка в стиле lineline) (https://www.example.com/)
-
- | Личный идентификатор | LastName | FirstName | Адрес | Город |
- | --------- | -------- | --------- | ------- | ---- |
- | 1 | Смит | Джейн | N /A | N /A |
СОЗДАТЬ ТАБЛИЦЫ Лица (
PersonID int,
LastName varchar (255),
FirstName varchar (255),
Адрес varchar (255),
Город варчар (255)
);