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

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

  • Как вы документируете свою базу данных? (SQL-Server)
  • Какой инструмент вы используете?
  • Формат хранения документации для схемы базы данных /метаданных?
    • Документы Word
    • Таблица Excel
    • Обычный текст
  • Процесс или политика документирования?

Я не говорю об обратном проектировании /документировании существующей базы данных, но главным образом о лучших примерах документации при разработке вашей системы /базы данных.

209 голосов | спросил 4 revs, 2 users 72%
user316
1 Jam1000000amThu, 01 Jan 1970 03:00:00 +030070 1970, 03:00:00

16 ответов


69

Я использую расширенные свойства, так как они очень гибкие. Большинство стандартных инструментов документации можно отключить MS_Description, а затем вы можете использовать свои собственные с помощью специальных инструментов.

См. эту презентацию: # 41-Получить рычаг и выбрать любую черепаху: Подъем с метаданными

И этот код: http://code.google.com/p/caderoux/wiki/LeversAndTurtles

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
52

Microsoft Visio Pro (вверх to Visio 2010) может перепроектировать базу данных, а CA ERwin . Visio - более дешевый вариант, но ERwin - это более подробный, более полный вариант. Расширенные свойства хороши, если люди не хотят смотреть на них. Вы также можете использовать что-то вроде документа Docs , например, вывода в формате HTML.

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

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
22

Попробуйте SchemaSpy: http://schemaspy.sourceforge.net/

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
21

Для 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'
ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
19

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

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

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
18

Если это когда-либо написано, документация состоит из словарного документа. Будет приведена пара диаграмм отношений. Списки таблиц и краткое описание того, что каждая таблица имеет и как она относится к другим таблицам. В одной главе документации содержатся параметры безопасности: какие разрешения имеет «пользователь», который требуется приложению?

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

Отказ от ответственности: слишком многие разработчики считают, что код - это документация , и я тоже виноват в этом.

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
12

Смешно, мне было интересно, как это делают другие люди.

При разработке моего первого проекта большой базы данных я обнаружил, что Microsoft SQL Server Management Studio 10.0.1600.22 поддерживает диаграммы баз данных, которые вы можете экспортировать в текстовый документ или другое программное обеспечение для документации, где вы можете добавить столько подробной документации, сколько хотите. Просто разверните базу данных, к которой вы подключились, в SQL Management Studio и щелкните правой кнопкой мыши на «диаграммах базы данных» в проводнике объектов и выберите «Новая диаграмма базы данных», чтобы создать интерактивную диаграмму, в которой будут показаны все отношения между различными таблицами. Вы даже можете указать, какие таблицы вы хотите включить в диаграммы, чтобы изображение не становилось неуравновешенным, если вы просто пытаетесь задокументировать его по частям. Экспортируйте изображение в любое другое программное обеспечение для редактирования и прокомментируйте столько, сколько хотите.

Я также рекомендую множество /комментариев /в скрипте, который генерирует вашу базу данных.

Как правило, много работы записывает то, для чего все для этого, но хорошая идея надолго, например, когда вы или какая-то другая бедная душа вернется, чтобы обновить свое творение пару лет спустя! :)

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
12

Я использую расширенные свойства и Red Dates SQL Doc. Хорошо работает!

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
12

Я устанавливаю расширенное свойство MS_description для всех объектов, а затем документирую всю базу данных, используя ApexSQL Doc . Раньше я использовал HTML-документы, но в последнее время предпочитаю PDF

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
11

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

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

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

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
9

Для документирования 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.

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
8

Создатель словаря DB

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

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
7

Действительно, расширенные свойства (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

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
6

Вы также можете посмотреть wsSqlSrvDoc . Это хороший инструмент, который работает с расширенными свойствами SQL Server и создает документ MS Word.

Отпечаток всех свойств столбца (с отношениями внешних ключей) работает из коробки. Для получения дополнительных описаний в каждом поле вам необходимо настроить расширенные свойства этих столбцов в SQL Server Management Studio.

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

веб-сайт инструмента

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
3

Мы используем Dataedo для создания словаря данных, хранимых процедур и функций документа. Мы вставляем ERD, созданные в Visio. Вся документация хранится в репозитории метаданных Dataedo (форматированный текст), и мы экспортируем его в HTML для внутреннего использования или экспортируем в PDF для печатного документа.

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

ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04
0

Вы можете использовать регулярные комментарии - -prefixed в файле .sql.

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

Вы также можете использовать некоторый синтаксис с сходством jsDoc / phpDoc .

- Таблица для хранения сведений о людях.
- @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)
);

Или вы можете использовать синтаксис MarkDown.

- # Лица
- Таблица для хранения сведений о ** **.
- * `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)
);
ответил Ramakant Dadhichi 11 J000000Tuesday17 2017, 20:42:04

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132