Як ви документуєте свої бази?


227

Я вважаю, що більшість моїх клієнтів взагалі не документують свої бази даних, і мені здається, що це досить страшно. Для впровадження кращої практики я хотів би знати, якими інструментами / процесами користуються люди.

  • Як ви документуєте свою базу даних? (SQL-сервер)
  • Який інструмент ви використовуєте?
  • Формат зберігання документації для схеми / метаданих баз даних?
    • Word документи
    • Електронна таблиця Excel
    • Простий текст
  • Процес документації чи політики?

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

Відповіді:


78

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

Дивіться цю презентацію: # 41 - Отримайте важіль і виберіть будь-яку черепаху: підйом метаданих

І цей код: http://code.google.com/p/caderoux/wiki/LeversAndTurtles


3
Ви можете щось змінити і забути відповідно змінити свої розширені властивості, зробивши їх неправильними. Чи можете ви автоматично виявити такі розбіжності?
АК

2
Принаймні, можна запитати схему бази даних (sys.tables / sys.columns) і залишити приєднатися до розширених властивостей (sys.extended_properties) для виявлення незадокументованих полів, а потім перетворити цей скрипт у тест, який потрібно запустити при розгортанні.
Міхей

59

Від Microsoft Visio Pro (до Visio 2010) може перепроектувати базу даних , як може СА ERwin . Visio - дешевший варіант, але ERwin - більш детальний, більш повний варіант. Розширені властивості приємні, якщо люди намагаються дивитись на них. Ви також можете використовувати щось на зразок SQL Doc Red Gate для виведення документації у форматі HTML.

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


Те, що найпростішої схеми часто не вистачає (навіть у добре названій базі даних з іноземними ключами), - це описи полів. На моєму досвіді незвично, щоб усі поля були досить простими, щоб вписатись у назву стовпця.
StockB


26

Для SQL Server я використовую розширені властивості.

За допомогою наступного сценарію PowerShell я можу генерувати сценарії створення таблиці для однієї таблиці або для всіх таблиць у схемі dbo.

Сценарій містить Create tableкоманду, первинні ключі та індекси. Іноземні ключі додаються як коментарі. Розширені властивості таблиць та стовпців таблиці додаються як коментарі. Так, підтримуються багаторядкові властивості.

Сценарій налаштований на мій особистий стиль кодування.

  • відсутні окремі порівняння для окремих стовпців.

  • в даний час для цього потрібна автентифікація сервера Sql.

Ось повний код для перетворення розширених властивостей у гарний звичайний старий документ ASCII (BTW, він дійсний sql для відтворення ваших таблиць):

function Get-ScriptForTable
{
    param (
        $server, 
        $dbname,
        $user,
        $password,
        $filter
    )

[System.reflection.assembly]::LoadWithPartialName("Microsoft.SqlServer.Smo") | out-null
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SqlServer.ConnectionInfo")  | out-null

$conn = new-object "Microsoft.SqlServer.Management.Common.ServerConnection" 
$conn.ServerInstance = $server
$conn.LoginSecure = $false
$conn.Login = $user
$conn.Password = $password
$conn.ConnectAsUser = $false
$srv = New-Object "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 -or  $_.Name -match $filter)
    {
        $lines = @()
        $header = "---------- {0, 3} {1, -30} ----------"  -f $cnt, $_.Name
        Write-Host $header 

        "/* ----------------- {0, 3} {1, -30} -----------------"  -f $cnt, $_.Name
        foreach( $i in $_.ExtendedProperties)
        {
            "{0}: {1}" -f $i.Name, $i.value
        }
        ""
        $colinfo = @{}
        foreach( $i in $_.columns)
        {
            $info = ""
            foreach ($ep in $i.ExtendedProperties)
            {
                if ($ep.value -match "`n")
                {
                    "----- Column: {0}  {1} -----" -f $i.name, $ep.name
                    $ep.value
                }
                else
                {
                    $info += "{0}:{1}  " -f $ep.name, $ep.value
                }
            }
            if ($info)
            {
                $colinfo[$i.name] =  $info
            }
        }
        ""
        "SELECT COUNT(*) FROM {0}" -f $_.Name
        "SELECT * FROM {0} ORDER BY 1" -f $_.Name
        "--------------------- {0, 3} {1, -30} ----------------- */" -f $cnt, $_.Name
        ""
        $raw = $Scripter.Script($_)
        #Write-host $raw
        $cont = 0
        $skip = $false 
        foreach ($line in $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
                continue
            }
            elseif ($line -match "^UNIQUE ")
            {
                $cont = 3
                $linebuf = $line
                $skip = $true
                continue
            }
            elseif ($line -match "^ALTER TABLE.*WITH CHECK ")
            {
                $cont = 1
                $linebuf = "-- " + $line
                continue
            }
            elseif ($line -match "^ALTER TABLE.* CHECK ")
            {
                continue
            }
            else
            {
                $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"
        $block
        $cnt++
        $used = $false
        foreach( $i in $_.Indexes)
        {
            $out = ''
            $raw = $Scripter.Script($i)
            #Write-host $raw
            foreach ($line in $raw -split "\r\n")
            {
                if ($line -match "^\)WITH ")
                {
                    $out += ")"
                }
                elseif ($line -match "^ALTER TABLE.* PRIMARY KEY")
                {
                    break
                }
                elseif ($line -match "^ALTER TABLE.* ADD UNIQUE")
                {
                    $out += $line -replace "\]|\[", "" -replace " NONCLUSTERED", "" 
                }
                elseif ($line -notmatch "^\s*$")
                {
                    $out += $line -replace "\]|\[", "" -replace "^\s*", "" `
                    -replace " ASC,", ", " -replace " ASC$", "" `
                    <#-replace "\bdbo\.\b", "" #> `
                    -replace " NONCLUSTERED", "" 
                }
                $used = $true
            }
            $block = "$out;`r`ngo`r`n"
            $out
        }
        if ($used)
        {
            "go"
        }
    }
} 
}

Ви можете виконати сценарій неповної схеми dbo даної бази даних

Get-ScriptForTable 'localhost'  'MyDB' 'sa' 'toipsecret'  |  Out-File  "C:\temp\Create_commented_tables.sql"

Або фільтруйте для однієї таблиці

Get-ScriptForTable 'localhost'  'MyDB' 'sa' 'toipsecret' 'OnlyThisTable'

21

Погляньте на SchemaCrawler - це мій безкоштовний інструмент командного рядка, який я створив для того, щоб шукати. SchemaCrawler створює текстовий файл із усіма об'єктами схеми бази даних. Цей текстовий висновок розроблений так, щоб він читався людиною, а також відрізнявся від подібного виводу з іншого сервера.

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


20

Якщо вона коли-небудь написана, документація складається із слова документа. Буде включена пара діаграм відносин. Списки таблиць та короткий опис того, що містить кожна таблиця та як вона стосується інших таблиць. Один розділ документації включає налаштування безпеки: які дозволи потребує "користувач", який потрібен додатку?

Як правило, у компаніях, над якими я працював, документація на базу даних пишеться лише тоді, коли замовником є ​​той, хто здійснює аудит, який, як правило, обмежує її використання лише фінансовими та державними замовниками.

Відмова від відповідальності: надто багато розробників приймають ставлення до того, що код є документацією , і я теж в цьому винен.


10
Велика проблема, яку я вважаю з документацією, яка не пов'язана тісно з кодом (наприклад, окремим документом Word, на відміну від автоматично сформованої схеми схеми + добре названих об'єктів бази даних), полягає в тому, що ця документація гарантується, що вона буде неправильною, оскільки час минає. Причина проста: окремий документ ефективно копіює інформацію. Без автоматизованого способу синхронізувати його з джерелом він дуже швидко застаріє. Порівняйте це з інструментом, який генерує схему в прямому ефірі з бази даних та витягує відповідні коментарі з коду.
Нік Чамма

16

Я використовую розширені властивості та Red Gates SQL Doc. Працює дуже добре!


14

Смішно, мені було цікаво, як це роблять і інші люди ..

Розробляючи свій перший великий проект бази даних, я виявив, що Microsoft SQL Server Management Studio 10.0.1600.22 підтримує діаграми бази даних, які можна експортувати в текстовий документ або інше програмне забезпечення документації, куди ви можете додати стільки детальної документації, скільки вам потрібно. Просто розгорніть базу даних, до якої ви підключились в SQL Management Studio, і клацніть правою кнопкою миші на «Діаграми баз даних» в провіднику об’єктів і виберіть «Нова діаграма баз даних», щоб створити інтерактивну діаграму, яка покаже всі взаємозв'язки між різними таблицями. Ви навіть можете вказати, які таблиці ви хочете включити в діаграми, щоб зображення не виходило неприємно, якщо ви просто намагаєтесь документувати його по частинах. Експортуйте зображення в будь-яке інше програмне забезпечення для редагування та коментуйте скільки завгодно.

Я також рекомендую багато / коментарів / у сценарії, який створює вашу базу даних.

Як правило, це велика робота, яка записує, для чого це все, але хороша ідея на довгостроковий період, наприклад, коли ви або якась інша бідна душа повертається, щоб оновити своє твір через пару років! :)


3
Я не використовую діаграми SQL Server, оскільки обмеження зовнішніх ключів просто підключені десь до таблиць, як це робиться в ER-діаграмах . Я вважаю за краще роз'єми, що з'єднують первинний та зовнішній ключові поля.
R. Schreurs

13

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


12

Я використовую інструменти моделювання даних, оскільки вони дозволяють мені документувати важливу інформацію про базу даних, крім того, що "вписується" в базу даних. Метадані, такі як питання конфіденційності / безпеки / чутливості, управління, управління тощо.

Це може вийти за рамки того, що дехто потребує в документі бази даних, але ці речі важливі для бізнесу та допомагають їм керувати своїми даними.

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


10

Для сервера Documenting sql я дуже рекомендую нещодавно випущений:

Документація на SQL Server та Windows за допомогою Windows PowerShell, написана Кендалом Ван Дайком

Короткий опис за посиланням:

SQL Power Doc - це набір скриптів і модулів Windows PowerShell, які виявляють, документують та діагностують екземпляри SQL Server та їх основні конфігурації ОС Windows та машини. SQL Power Doc працює з усіма версіями SQL Server від SQL Server 2000 до 2012 року, а всі версії Windows Server та споживчих операційних систем Windows з Windows 2000 та Windows XP через Windows Server 2012 та Windows 8. SQL Power Doc також може документувати документи Бази даних SQL Windows Azure.


10

Створення Словника СБ

це інструмент документації з базами даних з відкритим кодом з гідними графічним інтерфейсом та можливостями експорту / імпорту. Він використовує розширені властивості для зберігання документації. Він також створює автоматичні описи для стовпців первинного ключа та стовпців із зовнішнім ключем.


1
вимагає .NET Framework 4.0 і працює лише з SQL Server і SQL Express
кевінський

8

Дійсно, розширені властивості (MS_Description) - це шлях. Наявність цих описів, доступних як частина метаданих, може використовуватися не тільки генераторами документів, але й (сподіваємось, щодня) інструментами, які забезпечують "інтелісенс", наприклад, відмінного помічника SQL Softtree http://www.softtreetech.com/ isql.htm (востаннє я перевіряв, чи не вони) або вбудований в Intellisense студії управління SQL Sever (починаючи з sql2008)

Я також вважаю, що розробникам та DBA слід легко додати ці замітки, тому що, як правильно вказали Тангурена та Нік Чаммас - розробники дуже неохоче оновлюють документи та ненавидять дублювати роботу - що досить справедливо, особливо для людини, яку навчали оптимізувати речі протягом усього їхнього професійного життя. Тому, якщо по-справжньому легко не оновлювати документи в одному місці, близькому до вихідного коду, - це не спрацює. У якийсь момент я здійснив пошук в Інтернеті і не знайшов рішення для цього, тому написав LiveDoco (не безкоштовно, вибачте), намагаючись зробити це легше. Більше інформації тут, якщо зацікавлено: http://www.livedoco.com/why-livedoco


7

Ви також можете поглянути на wsSqlSrvDoc . Це приємний маленький інструмент, який працює з розширеними властивостями SQL Server і створює документ MS Word.

Виведення всіх властивостей стовпця (із зовнішніми ключами) працює з вікна. Для подальшого опису кожного поля ви повинні налаштувати розширені властивості цих стовпців у студії управління SQL Server.

Це не безкоштовно, але цілком доступно. Якщо вам просто потрібно створити документацію для БД "не працює", ця більш-менш закінчена, ніж було б достатньо для використання безкоштовної пробної версії.

Веб-сайт інструменту


5

Ми використовуємо Dataedo для створення словника даних, зберігання документів та процедур та функцій. Ми вставляємо ERD, створені у Visio. Вся документація зберігається у сховищі метаданих Dataedo (відформатований текст), і ми експортуємо їх у HTML для внутрішнього використання або експортуємо у PDF для друкованого документа.

Кожен об'єкт ми присвоюємо модулю і присвоюємо кожному модулю людину. Dataedo постачає звіт про стан документації, щоб ми могли сказати, чи є новий стовпець або таблиця, яку потрібно задокументувати.


1

Ви можете використовувати регулярні --попередні коментарі у .sqlфайлі.

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

Приклад:

-- Table to store details about people.
-- See also: The customer table.
-- Note: Keep this data safe!
-- Todo: Add a email column.
CREATE TABLE Persons ( -- People in the registry
    PersonID int,
    LastName varchar(255), -- The person's last name
    FirstName varchar(255), -- The person's first name
    Address varchar(255), -- Address of residence
    City varchar(255) -- City of residence
);

Можливо, ви могли також використовувати XML.

-- <summary>
-- Table to store details about people.
-- </summary>
-- <column name="PersonID">The id column.</column>
-- <column name="LastName">The person's last name.</column>
-- <column name="FirstName">The person's first name.</column>
-- <column name="Address">Address of residence.</column>
-- <column name="City">City of residence.</column>
CREATE TABLE Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
);

Ви також можете використовувати синтаксис із подібністю jsDoc / phpDoc .

-- Table to store details about people.
-- @column {int} PersonID - The id column.
-- @column {varchar} LastName - The person's last name.
-- @column {varchar} FirstName - The person's first name.
-- @column {varchar} Address - Address of residence.
-- @column {varchar} City - City of residence.
-- @see {@link https://example.com/|Example}
-- @author Jane Smith <jsmith@example.com>
-- @copyright Acme 2018
-- @license BSD-2-Clause
-- @todo Add a column for email address.
-- @since 1.0.1
-- @version 1.2.3
CREATE TABLE Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
);

Або ви можете використовувати синтаксис MarkDown.

-- # Persons
-- Table to store details about **people**.
-- * `PersonID` - The id column.
-- * `LastName` - The person's _last_ name.
-- * `FirstName` - The person's _first_ name.
-- * `Address` - Address of residence.
-- * `City` - City of residence.
--
-- [I'm an inline-style link](https://www.example.com/)
--
-- | PersonID | LastName | FirstName | Address | City |
-- | ---------| -------- | --------- | ------- | ---- |
-- | 1        | Smith    | Jane      | N/A     | N/A  |
CREATE TABLE Persons (
    PersonID int,
    LastName varchar(255),
    FirstName varchar(255),
    Address varchar(255),
    City varchar(255)
);

1

Діаграми ERD (діаграми бази даних) завжди були найкориснішими для моєї команди

Але є правило писати " Опис " у Властивості кожної створеної нами таблиці та стовпця.

Тоді ми використовуємо назву програмного забезпечення Enterprise Architect для документування Tablesз усіма Indexes, Foreign Keysа також Columnsз Typeі описом .

введіть тут опис зображення


-1

Зокрема, для MySQL ми завжди використовуємо MySQL Workbench . Ми створюємо наші дизайни баз даних в дизайнері, а потім експортуємо їх як запущений сценарій SQL. Застосування всіх змін у дизайні, а потім запуск створеного сценарію гарантує, що дизайн та фактична база даних ідеально синхронізуються між собою та що документація не застаріє так легко.

Використовуючи наш веб-сайт, ви визнаєте, що прочитали та зрозуміли наші Політику щодо файлів cookie та Політику конфіденційності.
Licensed under cc by-sa 3.0 with attribution required.