it-swarm.dev

Jak dokumentujesz swoje bazy danych?

Uważam, że większość moich klientów w ogóle nie dokumentuje swoich baz danych i wydaje mi się to dość przerażające. Aby wprowadzić jakąś lepszą praktykę, chciałbym wiedzieć, jakich narzędzi/procesów używają ludzie.

  • Jak dokumentujesz swoją bazę danych? (SQL-Server)
  • Jakiego narzędzia używasz?
  • Format przechowywania dokumentacji dla schematu/metadanych bazy danych?
    • Dokumenty Word
    • Excel arkusz kalkulacyjny
    • Zwykły tekst
  • Proces dokumentacji lub zasady?

Nie mówię o inżynierii odwrotnej/dokumentowaniu istniejącej bazy danych, ale głównie o najlepszych praktykach dokumentacji podczas tworzenia systemu/bazy danych.

234
user316

Korzystam z rozszerzonych właściwości, ponieważ są one bardzo elastyczne. Większość standardowych narzędzi do dokumentacji można wyłączyć MS_Description, a następnie możesz użyć własnego z niestandardowymi narzędziami.

Zobacz tę prezentację: # 41-Zdobądź dźwignię i wybierz dowolnego żółwia: podnoszenie za pomocą metadanych

I ten kod: http://code.google.com/p/caderoux/wiki/LeversAndTurtles

80
Cade Roux

Microsoft Visio Pro (do Visio 2010) może dokonać inżynierii wstecznej bazy danych, podobnie jak CA ERwin . Visio jest tańszą opcją, ale ERwin jest bardziej szczegółową i kompletną opcją. Rozszerzone właściwości są ładne, jeśli ludzie próbują na nie spojrzeć. Możesz również użyć czegoś takiego jak Red Gate's SQL Doc do wydrukowania dokumentacji w formacie HTML.

Uważam, że konwencje nazewnictwa i prawidłowe konfigurowanie kluczy obcych prowadzą do prawie samodokumentującej bazy danych. Nadal powinieneś mieć jakieś zewnętrzne dokumenty, aby lepiej zrozumieć cel.

27
Robert Durgin

W przypadku SQL Server używam rozszerzonych właściwości.

Za pomocą następującego skryptu PowerShell mogę wygenerować skrypty tworzenia tabeli dla pojedynczej tabeli lub dla wszystkich tabel w schemacie dbo.

Skrypt zawiera Create table polecenie, klucze podstawowe i indeksy. Klucze obce są dodawane jako komentarze. Rozszerzone właściwości tabel i kolumn tabeli są dodawane jako komentarze. Tak, obsługiwane są właściwości wielu linii.

Skrypt jest dostosowany do mojego osobistego stylu kodowania.

  • brak pojedynczych zestawień dla pojedynczych kolumn.

  • obecnie wymaga uwierzytelnienia serwera Sql.

Oto kompletny kod, aby przekształcić rozszerzone właściwości w dobry, zwykły stary ASCII (BTW, aby odtworzyć tabele, należy użyć kodu 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"
        }
    }
} 
}

Możesz albo wykonać skrypt pełnego schematu dbo dla danej bazy danych

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

Lub filtruj dla pojedynczego stołu

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

Spójrz na SchemaCrawler - to moje bezpłatne narzędzie wiersza poleceń, które zaprojektowałem do robienia tego, czego szukasz. SchemaCrawler tworzy plik tekstowy ze wszystkimi obiektami schematu bazy danych. Ten tekst wyjściowy został zaprojektowany tak, aby był czytelny dla człowieka, a także odróżniał się od podobnych danych wyjściowych z innego serwera.

W praktyce odkryłem, że wyjście pliku tekstowego schematu bazy danych jest przydatne, gdy jest wykonywane jako część kompilacji. W ten sposób możesz sprawdzić plik tekstowy w systemie kontroli kodu źródłowego i mieć historię wersji, w której ewoluował twój schemat. SchemaCrawler jest również zaprojektowany do automatyzacji tego z poziomu wiersza poleceń.

21
Sualeh Fatehi

Jeśli kiedykolwiek jest napisane, dokumentacja składa się z dokumentu Word. Dołączonych zostanie kilka diagramów relacji. Listy tabel i krótki opis tego, co zawiera każda tabela i jak odnosi się do innych tabel. Jeden rozdział dokumentacji obejmuje ustawienia zabezpieczeń: jakich uprawnień potrzebuje „użytkownik” aplikacji?

Zasadniczo w firmach, w których pracowałem, dokumentacja bazy danych jest zapisywana tylko wtedy, gdy klient jest tym, który przeprowadza audyty, co ogranicza jej wykorzystanie do klientów finansowych i rządowych.

Oświadczenie: zdecydowanie zbyt wielu programistów uważa, że ​​kod to dokumentacja, i ja też byłem winny.

20
Tangurena

Używam rozszerzonych właściwości i Red Gates SQL Doc. Działa bardzo dobrze!

16
jrara

Zabawne, zastanawiałem się, jak robią to inni.

Podczas opracowywania mojego pierwszego dużego projektu bazy danych odkryłem, że Microsoft SQL Server Management Studio 10.0.1600.22 obsługuje diagramy baz danych, które możesz wyeksportować do dokumentu Word lub innego oprogramowania dokumentacyjnego, w którym możesz dodać tyle szczegółów dokumentacji, ile chcesz. Po prostu rozwiń bazę danych, z którą się połączyłeś w SQL Management Studio i kliknij prawym przyciskiem myszy „diagramy bazy danych” w Eksploratorze obiektów i wybierz „Nowy diagram bazy danych”, aby wygenerować interaktywny diagram, który pokaże wszystkie relacje między różnymi tabelami. Możesz nawet określić, które tabele chcesz uwzględnić na schematach, aby obraz nie uległ pogorszeniu, jeśli tylko próbujesz dokumentować go kawałek po kawałku. Eksportuj obraz do dowolnego innego oprogramowania do edycji i komentuj tyle, ile chcesz.

Polecam również dużo/komentarze/w skrypcie, który generuje bazę danych.

Zasadniczo spisywanie tego, po co to wszystko, jest dużo pracy, ale dobry pomysł na dłuższą metę, na przykład gdy ty lub inna biedna dusza wrócisz, aby zaktualizować swoje dzieło kilka lat później! :)

14
fa1c0n3r

Ustawiam rozszerzoną właściwość MS_description dla wszystkich obiektów, a następnie dokumentuję całą bazę danych za pomocą ApexSQL Doc . Wcześniej tworzyłem dokumenty HTML, ale ostatnio wolę PDF

13
Carol Baker West

Używam narzędzi do modelowania danych, ponieważ pozwalają mi dokumentować ważne informacje o bazie danych inne niż to, co „pasuje” do bazy danych. Metadane, takie jak obawy dotyczące prywatności/bezpieczeństwa/wrażliwości, zarządzanie, zarządzanie itp.

Może to wykraczać poza to, czego niektórzy potrzebują do udokumentowania bazy danych, ale te rzeczy są ważne dla firmy i pomagają jej zarządzać danymi.

Narzędzia formalne pomagają mi również w zarządzaniu danymi przechowywanymi w więcej niż jednej bazie danych/instancji/serwerze. To nigdy nie było bardziej prawdziwe niż w naszym świecie aplikacji pakietowych.

12
Karen Lopez

W przypadku serwera SQL Documenting bardzo polecam niedawno wydane:

SQL Server i dokumentacja systemu Windows za pomocą Windows PowerShell napisane przez Kendal Van Dyke

Krótki opis z linku:

SQL Power Doc to zbiór skryptów i modułów Windows PowerShell, które wykrywają, dokumentują i diagnozują instancje SQL Server oraz ich podstawowe konfiguracje systemu operacyjnego Windows i komputera. SQL Power Doc współpracuje ze wszystkimi wersjami SQL Server od SQL Server 2000 do 2012 oraz wszystkimi wersjami Windows Server i konsumenckich systemów operacyjnych Windows od Windows 2000 i Windows XP przez Windows Server 2012 i Windows 8 . SQL Power Doc jest również w stanie dokumentować bazy danych SQL Azure.

10
Kin Shah

DB Dictionary Creator

to narzędzie do dokumentacji baz danych typu open source z przyzwoitym GUI i opcjami eksportu/importu. Używa rozszerzonych właściwości do przechowywania dokumentacji. Generuje również automatyczne opisy dla kolumn klucza podstawowego i kolumny klucza obcego.

10
Sundeep Arun

Rzeczywiście, Rozszerzone właściwości (MS_Description) to droga. Dostępność tych opisów jako części metadanych może być wykorzystana nie tylko przez generatory dokumentów, ale także (mam nadzieję, że pewnego dnia) narzędzia zapewniające „inteligencję”, na przykład doskonały SQL Server Asystenta Softtree http: // www. softtreetech.com/isql.htm (ostatni raz sprawdziłem, że nie mają) lub wbudowany w Intellisense SQL Sever Management Studio (od sql2008)

Uważam również, że deweloperzy i DBA powinni łatwo dodawać te notatki, ponieważ jak słusznie zauważyli Tangurena i Nick Chammas - deweloperzy bardzo niechętnie aktualizują dokumentację i nienawidzą powielania pracy - co jest wystarczająco uczciwe, szczególnie dla osoby, która była nauczana w celu optymalizacji rzeczy przez całe życie zawodowe. Więc chyba, że ​​aktualizacja dokumentów w jednym miejscu blisko kodu źródłowego jest naprawdę łatwa - to nie zadziała. W pewnym momencie przeszukałem sieć i nie znalazłem rozwiązania tego problemu, więc napisałem LiveDoco (nie za darmo, przepraszam), aby to ułatwić. Więcej informacji tutaj, jeśli są zainteresowani: http://www.livedoco.com/why-livedoco

8
Zar Shardan

Możesz także rzucić okiem na wsSqlSrvDoc . To ładne, małe narzędzie, które działa z rozszerzonymi właściwościami SQL Server i tworzy dokument MS Word.

Wydruk wszystkich właściwości kolumny (z relacjami klucza obcego) działa natychmiast po wyjęciu z pudełka. Aby uzyskać dalsze opisy dla każdego pola, musisz skonfigurować rozszerzone właściwości tych kolumn w SQL Server Management Studio.

To nie jest darmowe, ale dość przystępne. Jeśli potrzebujesz tylko utworzyć dokumentację bazy danych „nie działa w toku”, która jest mniej lub bardziej ukończona, wystarczyłoby skorzystać z bezpłatnej wersji próbnej.

strona internetowa narzędzia

7
Kurresh

Używamy Dataedo do tworzenia słownika danych, dokumentowania przechowywanych procedur i funkcji. Wklejamy ERD utworzone w Visio. Cała dokumentacja jest przechowywana w repozytorium metadanych Dataedo (sformatowany tekst), a my eksportujemy ją do HTML do użytku wewnętrznego lub eksportujemy do PDF dla drukowanego dokumentu).

Przypisujemy każdy obiekt do modułu, a każdy moduł do osoby. Dataedo zawiera raportowanie stanu dokumentacji, dzięki czemu możemy stwierdzić, czy jest nowa kolumna lub tabela, którą należy udokumentować.

5
Ryszard Bocian

Możesz użyć zwykłego --- komentarze z prefiksem w .sql plik.

Korzyści obejmują to, że dokumentacja zawiera kod schematu bazy danych i można łatwo zatwierdzić go w systemie kontroli wersji, takim jak Git .

Przykład:

-- 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
);

Może mógłbyś również użyć 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)
);

Możesz także użyć składni podobnej do 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 <[email protected]>
-- @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)
);

Lub możesz użyć składni 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)
);
2
Fred

Diagramy ERD (diagramy bazy danych) były zawsze najbardziej przydatne dla mojego zespołu

Ale istnieje reguła, aby pisać „ Decription ” we Właściwości każdej tabeli i kolumnę, którą tworzymy.

Następnie używamy nazwy oprogramowania to Enterprise Architect do udokumentowania Tables przy pomocy wszystkich Indexes, Foreign Keys I Columns z Type i Opis .

enter image description here

1
El.Hum