Wie dokumentieren Sie Ihre Datenbanken?

Ich finde, dass die meisten meiner Kunden ihre Datenbanken überhaupt nicht dokumentieren, und ich finde das ziemlich beängstigend. Um eine bessere Praxis einzuführen, würde ich gerne wissen, welche Tools / Prozesse Menschen verwenden.

• Wie dokumentieren Sie Ihre Datenbank? (SQL Server)
• Welches Tool benutzt du?
• Dokumentationsspeicherformat für Datenbankschema / Metadaten?
  • Word-Dokumente
  • Excel Tabelle
  • Einfacher Text
• Dokumentationsprozess oder Richtlinien?

Ich spreche nicht vom Reverse Engineering / Dokumentieren einer vorhandenen Datenbank, sondern hauptsächlich von den Best Practices der Dokumentation, während Sie Ihr System / Ihre Datenbank entwickeln.

Ich habe erweiterte Eigenschaften verwendet, da sie sehr flexibel sind. Die meisten Standard-Dokumentationstools können entfernt werden MS_Description, und Sie können dann Ihre eigenen Tools mit benutzerdefinierten Tools verwenden.

Siehe diese Präsentation: # 41-Holen Sie sich einen Hebel und wählen Sie eine beliebige Schildkröte: Heben mit Metadaten

Und dieser Code: http://code.google.com/p/caderoux/wiki/LeversAndTurtles

Microsoft Visio Pro (bis Visio 2010) kann eine Datenbank zurückentwickeln, ebenso wie CAs ERwin . Visio ist die billigere Option, aber ERwin ist die detailliertere und vollständigere Option. Erweiterte Eigenschaften sind nett, wenn die Leute sich die Mühe machen, sie anzuschauen. Sie können auch so etwas wie das SQL- Dokument von Red Gate verwenden, um die Dokumentation im HTML-Format auszugeben.

Ich finde Namenskonventionen und das richtige Einrichten von Fremdschlüsseln führen zu einer fast selbstdokumentierenden Datenbank. Zum besseren Verständnis des Zwecks sollten Sie noch einige externe Dokumente haben.

Probieren Sie SchemaSpy aus: http://schemaspy.sourceforge.net/

Für SQL Server verwende ich erweiterte Eigenschaften.

Mit dem folgenden PowerShell-Skript kann ich ein Create Table-Skript für eine einzelne Tabelle oder für alle Tabellen im DBO-Schema generieren.

Das Skript enthält einen Create tableBefehl, Primärschlüssel und Indizes. Fremdschlüssel werden als Kommentare hinzugefügt. Die erweiterten Eigenschaften von Tabellen und Tabellenspalten werden als Kommentare hinzugefügt. Ja, mehrzeilige Eigenschaften werden unterstützt.

Das Skript ist auf meinen persönlichen Codierungsstil abgestimmt.

• Keine einzelnen Kollatierungen für einzelne Spalten.

• Derzeit erfordert es SQL Server-Authentifizierung.

Hier ist der vollständige Code, um die erweiterten Eigenschaften in ein gutes, einfaches, altes ASCII-Dokument umzuwandeln (übrigens, es ist ein gültiger SQL-Code, um Ihre Tabellen neu zu erstellen):

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"
        }
    }
} 
}

Sie können entweder das vollständige DBO-Schema einer bestimmten Datenbank skripten

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

Oder filtern Sie nach einer einzelnen Tabelle

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

Schauen Sie sich SchemaCrawler an - es ist mein kostenloses Befehlszeilentool, das ich entwickelt habe, um das zu tun, wonach Sie suchen. SchemaCrawler erstellt eine Textdatei mit allen Datenbankschemaobjekten. Diese Textausgabe ist so konzipiert, dass sie sowohl für Menschen lesbar als auch für ähnliche Ausgaben von einem anderen Server differenzierbar ist.

In der Praxis habe ich festgestellt, dass die Ausgabe einer Textdatei des Datenbankschemas nützlich ist, wenn dies als Teil des Builds erfolgt. Auf diese Weise können Sie die Textdatei in Ihr Quellcodeverwaltungssystem einchecken und einen Versionsverlauf darüber erhalten, wie sich Ihr Schema im Laufe der Zeit entwickelt hat. SchemaCrawler soll dies auch über die Befehlszeile automatisieren.

Wenn es jemals geschrieben wurde, besteht die Dokumentation aus einem Word-Dokument. Ein paar Beziehungsdiagramme werden beigefügt. Listen der Tabellen und eine kurze Beschreibung, was jede Tabelle enthält und in welcher Beziehung sie zu anderen Tabellen steht. Ein Kapitel der Dokumentation enthält die Sicherheitseinstellungen: Welche Berechtigungen benötigt der "Benutzer", den die Anwendung benötigt?

Im Allgemeinen wird in Unternehmen, für die ich gearbeitet habe, die Datenbankdokumentation nur dann erstellt, wenn der Kunde Audits durchführt, was die Verwendung auf Finanz- und Regierungskunden beschränkt.

Haftungsausschluss: Viel zu viele Entwickler sind der Meinung, dass der Code die Dokumentation ist , und ich habe mich auch schuldig gemacht.

Ich benutze erweiterte Eigenschaften und Red Gates SQL Doc. Funktioniert sehr gut!

Komisch, ich habe mich gefragt, wie andere Leute das auch machen.

Bei der Entwicklung meines ersten großen Datenbankprojekts stellte ich fest, dass Microsoft SQL Server Management Studio 10.0.1600.22 Datenbankdiagramme unterstützt, die Sie in ein Word-Dokument oder eine andere Dokumentationssoftware exportieren können, in der Sie so viele Dokumentationsdetails hinzufügen können, wie Sie möchten. Erweitern Sie einfach die Datenbank, mit der Sie in SQL Management Studio verbunden sind, und klicken Sie im Objekt-Explorer mit der rechten Maustaste auf "Datenbankdiagramme". Wählen Sie "Neues Datenbankdiagramm", um ein interaktives Diagramm zu generieren, das alle Beziehungen zwischen den verschiedenen Tabellen anzeigt. Sie können sogar angeben, welche Tabellen in die Diagramme aufgenommen werden sollen, damit das Bild nicht unübersichtlich wird, wenn Sie nur versuchen, es Stück für Stück zu dokumentieren. Exportieren Sie das Bild in eine andere Bearbeitungssoftware und kommentieren Sie so viel Sie möchten.

Ich habe auch viel / empfehlen Kommentare / in dem Skript , das Ihre Datenbank generiert.

Im Allgemeinen ist es eine Menge Arbeit, aufzuschreiben, wofür alles gedacht ist, aber auf lange Sicht eine gute Idee, zum Beispiel, wenn Sie oder eine andere arme Seele ein paar Jahre später zurückkommen, um Ihre Schöpfung zu aktualisieren! :)

Ich habe die erweiterte Eigenschaft MS_description für alle Objekte festgelegt und dann die gesamte Datenbank mit ApexSQL Doc dokumentiert . Früher habe ich HTML-Dokumente erstellt, in letzter Zeit bevorzuge ich PDF

Ich verwende Datenmodellierungswerkzeuge, weil sie es mir ermöglichen, wichtige Informationen über die Datenbank zu dokumentieren, die nicht in eine Datenbank passen. Metadaten wie Datenschutz- / Sicherheits- / Sensibilitätsbedenken, Verantwortungsbewusstsein, Governance usw.

Das mag über das hinausgehen, was manche zum Dokumentieren einer Datenbank benötigen, aber diese Dinge sind für das Unternehmen wichtig und helfen ihnen, ihre Daten zu verwalten.

Formale Tools helfen mir auch bei der Verwaltung von Daten, die in mehreren Datenbanken / Instanzen / Servern gespeichert sind. Dies war noch nie zutreffender als in unserer Welt der verpackten Anwendungen.

Für die Dokumentation von SQL Server empfehle ich dringend, erst kürzlich veröffentlicht:

SQL Server- und Windows-Dokumentation Verwenden von Windows PowerShell, geschrieben von Kendal Van Dyke

Kurzbeschreibung über den Link:

SQL Power Doc ist eine Sammlung von Windows PowerShell-Skripts und -Modulen, mit denen SQL Server-Instanzen und ihre zugrunde liegenden Windows-Betriebssystem- und Maschinenkonfigurationen erkannt, dokumentiert und diagnostiziert werden. SQL Power Doc funktioniert mit allen Versionen von SQL Server von SQL Server 2000 bis 2012 sowie mit allen Versionen von Windows Server und Windows-Betriebssystemen für Endverbraucher von Windows 2000 und Windows XP bis Windows Server 2012 und Windows 8. SQL Power Doc kann auch dokumentieren Windows Azure SQL-Datenbanken.

DB Dictionary Creator

ist ein Open Source-Datenbankdokumentationstool mit anständiger grafischer Benutzeroberfläche und Export- / Importoptionen. Zum Speichern der Dokumentation werden erweiterte Eigenschaften verwendet. Außerdem werden automatische Beschreibungen für Primärschlüsselspalten und Fremdschlüsselspalten generiert.

In der Tat ist Extended Properties (MS_Description) der richtige Weg. Wenn diese Beschreibungen als Teil der Metadaten zur Verfügung stehen, können sie nicht nur von Dokumentgeneratoren, sondern (hoffentlich eines Tages) auch von Tools verwendet werden, die "Intellisense" bieten, z. B. dem hervorragenden SQL-Assistenten von Softtree http://www.softtreetech.com/ isql.htm (das letzte Mal, als ich das überprüft habe) oder in SQL Server Management Studio's Intellisense (seit sql2008) integriert

Ich glaube auch, dass es für Entwickler und Datenbankadministratoren einfach sein sollte, diese Notizen hinzuzufügen, da Entwickler, wie Tangurena und Nick Chammas richtig hervorgehoben haben, nur sehr ungern die Dokumente auf dem neuesten Stand halten und doppelte Arbeiten hassen - was gerade für eine Person, die unterrichtet wurde, fair genug ist Dinge während ihres gesamten Berufslebens zu optimieren. Es sei denn, es ist wirklich einfach, Dokumente an einem Ort in der Nähe des Quellcodes zu aktualisieren - dies wird nicht funktionieren. Irgendwann suchte ich im Internet und fand keine Lösung dafür. Deshalb schrieb ich LiveDoco (nicht kostenlos, sorry), um es einfach zu machen. Mehr Infos hier bei Interesse: http://www.livedoco.com/why-livedoco

Sie können sich auch wsSqlSrvDoc ansehen . Es ist ein nettes kleines Tool, das mit erweiterten SQL Server-Eigenschaften zusammenarbeitet und ein MS Word-Dokument erstellt.

Der Ausdruck aller Spalteneigenschaften (mit Fremdschlüsselbeziehungen) funktioniert sofort. Für weitere Beschreibungen der einzelnen Felder müssen Sie erweiterte Eigenschaften dieser Spalten in SQL Server Management Studio einrichten.

Es ist nicht kostenlos, aber erschwinglich. Wenn Sie nur eine Dokumentation für eine "nicht in Arbeit" -DB erstellen müssen, die mehr oder weniger fertig ist, ist es ausreichend, die kostenlose Testversion zu verwenden.

Tool-Website

Wir verwenden Dataedo , um Datenwörterbücher zu erstellen, gespeicherte Prozeduren und Funktionen zu dokumentieren. Wir fügen in Visio erstellte ERDs ein. Die gesamte Dokumentation wird im Dataedo-Metadaten-Repository (formatierter Text) gespeichert und für den internen Gebrauch in HTML oder für gedruckte Dokumente in PDF exportiert.

Wir ordnen jedes Objekt einem Modul zu und ordnen jedes Modul einer Person zu. Dataedo wird mit Statusberichten zur Dokumentation geliefert, damit wir feststellen können, ob eine neue Spalte oder Tabelle dokumentiert werden muss.

Sie können reguläre --Kommentare in der .sqlDatei verwenden.

Zu den Vorteilen gehört, dass die Dokumentation den Code für das Datenbankschema enthält und Sie ihn problemlos an ein Versionskontrollsystem wie Git übergeben können .

Beispiel:

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

Vielleicht könnten Sie auch XML verwenden.

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

Sie können auch eine Syntax verwenden, die jsDoc / phpDoc ähnelt .

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

Oder Sie könnten MarkDown-Syntax verwenden.

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

ERD-Diagramme (Database Diagrams) waren für mein Team immer die nützlichsten

Es gibt jedoch die Regel, " Beschreibung " in die Eigenschaften jeder von uns erstellten Tabelle und Spalte zu schreiben .

Dann verwenden wir den Softwarenamen Enterprise Architect , um Tablesmit all Indexes, Foreign KeysAnd Columnswith Typeund Description zu dokumentieren .

Insbesondere für MySQL verwenden wir immer MySQL Workbench . Wir erstellen unsere Datenbankentwürfe im Designer und exportieren sie dann als ausführbares SQL-Skript. Durch Anwenden aller Änderungen im Design und anschließendes Ausführen des generierten Skripts wird sichergestellt, dass das Design und die tatsächliche Datenbank perfekt miteinander synchronisiert sind und die Dokumentation nicht so schnell veraltet ist.