it-swarm.com.de

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 einige bessere Praktiken einzuführen, möchte ich wissen, welche Tools/Prozesse die Leute verwenden.

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

Ich spreche nicht von Reverse Engineering/Dokumentieren einer vorhandenen Datenbank, sondern hauptsächlich von Best Practices für die Dokumentation, während Sie Ihr System/Ihre Datenbank entwickeln.

234
user316

Ich habe erweiterte Eigenschaften verwendet, da sie sehr flexibel sind. Die meisten Standarddokumentationstools können von MS_Description, und dann können Sie Ihre eigenen mit benutzerdefinierten Tools verwenden.

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

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

80
Cade Roux

Microsoft Visio Pro (bis Visio 2010) kann eine Datenbank ebenso zurückentwickeln wie CA ERwin . Visio ist die billigere Option, aber ERwin ist die detailliertere und vollständigere Option. Erweiterte Eigenschaften sind schön, wenn sich die Leute die Mühe machen, sie anzusehen. Sie können auch etwas wie Red Gates SQL Doc verwenden, um Dokumentation im HTML-Format auszugeben.

Ich finde, dass Namenskonventionen und das ordnungsgemäße Einrichten von Fremdschlüsseln zu einer fast selbstdokumentierenden Datenbank führen. Sie sollten noch einige externe Dokumente haben, um den Zweck besser zu verstehen.

Versuchen Sie SchemaSpy: http://schemaspy.sourceforge.net/

27
Robert Durgin

Für SQL Server verwende ich erweiterte Eigenschaften.

Mit dem folgenden PowerShell-Skript kann ich ein Skript zum Erstellen einer Tabelle für eine einzelne Tabelle oder für alle Tabellen im dbo-Schema erstellen.

Das Skript enthält ein Create table Befehl, 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 ist eine SQL Server-Authentifizierung erforderlich.

Hier ist der vollständige Code, um die erweiterten Eigenschaften in ein gutes einfaches altes ASCII Dokument) umzuwandeln (Übrigens ist es gültig, SQL zum Erstellen Ihrer Tabellen zu verwenden):

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'
26
bernd_k

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 gegen ähnliche Ausgaben von einem anderen Server abweichbar 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 wurde entwickelt, um dies auch über die Befehlszeile zu automatisieren.

21
Sualeh Fatehi

Wenn es jemals geschrieben wurde, besteht die Dokumentation aus einem Word-Dokument. Einige Beziehungsdiagramme werden enthalten sein. Listen der Tabellen und eine kurze Beschreibung dessen, was jede Tabelle enthält und wie sie sich auf andere Tabellen bezieht. Ein Kapitel der Dokumentation enthält die Sicherheitseinstellungen: Welche Berechtigungen benötigt der "Benutzer", den die Anwendung benötigt?

In Unternehmen, für die ich gearbeitet habe, wird die Datenbankdokumentation im Allgemeinen nur geschrieben, wenn der Kunde derjenige ist, der Audits durchführt, was die Verwendung in der Regel auf Finanz- und Regierungskunden beschränkt.

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

20
Tangurena

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

16
jrara

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 erstellen, in dem alle Beziehungen zwischen den verschiedenen Tabellen angezeigt werden. Sie können sogar angeben, welche Tabellen Sie in die Diagramme aufnehmen möchten, damit das Bild nicht unangenehm 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, wie Sie möchten.

Ich empfehle auch viel/Kommentare/im Skript, das Ihre Datenbank generiert.

Im Allgemeinen ist es eine Menge Arbeit, aufzuschreiben, wofür es alles 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 Kreation zu aktualisieren! :) :)

14
fa1c0n3r

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, aber in letzter Zeit bevorzuge ich PDF

13

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- und Sensibilitätsbedenken, Verantwortungsbewusstsein, Governance usw.

Das geht möglicherweise über das hinaus, was manche für die Dokumentation 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 mehr als einer Datenbank/Instanz/einem Server gespeichert sind. Dies war noch nie so wahr wie in unserer Welt der verpackten Anwendungen.

12
Karen Lopez

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

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

Kurzbeschreibung über den Link:

SQL Power Doc ist eine Sammlung von Windows PowerShell-Skripten und -Modulen, mit denen SQL Server-Instanzen und die zugrunde liegenden Windows-Betriebssystem- und Computerkonfigurationen 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-Consumer-Betriebssystemen von Windows 2000 und Windows XP bis Windows Server 2012 und Windows 8) SQL Power Doc kann auch Windows Azure SQL-Datenbanken dokumentieren.

10
Kin Shah

DB Dictionary Creator

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

10
Sundeep Arun

In der Tat sind erweiterte Eigenschaften (MS_Description) der richtige Weg. Wenn diese Beschreibungen als Teil der Metadaten verfügbar sind, können sie nicht nur von Dokumentgeneratoren, sondern (hoffentlich eines Tages) auch von Tools verwendet werden, die "Intellisense" bereitstellen, beispielsweise den ausgezeichneten SQL-Assistenten von Softtree http: // www. softtreetech.com/isql.htm (das letzte Mal, als ich es überprüft habe) oder in Intellisense von SQL Sever Management Studio (seit sql2008)

Ich glaube auch, dass es für Entwickler und Datenbankadministratoren einfach sein sollte, diese Notizen hinzuzufügen, denn wie Tangurena und Nick Chammas richtig betonten, zögern Entwickler sehr, die Dokumente auf dem neuesten Stand zu halten und doppelte Arbeiten zu hassen - was besonders für eine Person, die unterrichtet wurde, fair genug ist Dinge während ihres gesamten Berufslebens zu optimieren. Wenn es also nicht wirklich einfach ist, Dokumente an einem Ort in der Nähe des Quellcodes zu aktualisieren, funktioniert dies nicht. Irgendwann habe ich im Internet gesucht und keine Lösung dafür gefunden, also habe ich LiveDoco (nicht kostenlos, sorry) geschrieben, um es einfach zu machen. Weitere Informationen hier bei Interesse: http://www.livedoco.com/why-livedoco

8
Zar Shardan

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

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

Es ist nicht kostenlos, aber ziemlich erschwinglich. Wenn Sie nur eine Dokumentation für eine Datenbank erstellen müssen, die nicht in Bearbeitung ist und mehr oder weniger fertig ist, reicht es aus, die kostenlose Testversion zu verwenden.

Tool Website

7
Kurresh

Wir verwenden Dataedo , um ein Datenwörterbuch 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 wir exportieren sie zur internen Verwendung in HTML oder exportieren sie nach PDF für gedruckte Dokumente).

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

5
Ryszard Bocian

Sie können reguläre -- - vorangestellte Kommentare in der Datei .sql 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 mit Ähnlichkeit von jsDoc / phpDoc verwenden.

-- 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önnen die 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)
);
2
Fred

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

Es gibt jedoch die Regel, " Decription " in Properties jeder Tabelle zu schreiben und Spalte, die wir erstellen.

Dann verwenden wir einen Software-Namen Enterprise Architect , um Tables mit allen Indexes, Foreign Keys Zu dokumentieren. Und Columns mit Type und Beschreibung .

(enter image description here

1
El.Hum