it-swarm.com.de

So dokumentieren Sie eine Datenbank

(Hinweis: Mir ist klar, dass dies in der Nähe von Wie dokumentieren Sie Ihre Datenbankstruktur? liegt, aber ich denke nicht, dass es identisch ist.)

Ich habe angefangen, an einem Ort mit einer Datenbank mit buchstäblich Hunderten von Tabellen und Ansichten zu arbeiten, alle mit kryptischen Namen mit sehr wenigen Vokalen und ohne Dokumentation. Sie erlauben auch keine unbegründeten Änderungen am Datenbankschema und ich kann auch keine andere Datenbank als die Testdatenbank auf meinem eigenen Computer (die weggeweht und regelmäßig neu erstellt wird) berühren, sodass ich keine Kommentare hinzufügen kann, die irgendjemandem helfen würden.

Ich habe versucht, mit "Toad" ein ER-Diagramm zu erstellen, aber nachdem ich es 48 Stunden lang laufen ließ, hatte es immer noch nichts Sichtbares produziert und ich brauchte meinen Computer zurück. Ich habe mit einigen anderen Neueinstellungen gesprochen, und wir haben alle vorgeschlagen, dass wir sie im Entwickler-Wiki aktualisieren sollten, wenn wir uns über die Bedeutung einer bestimmten Tabelle oder einiger Spalten Gedanken gemacht haben.

Was ist also ein guter Weg, um dies zu tun? Listen Sie einfach Tabellen/Ansichten und ihre Spalten auf und füllen Sie sie aus, wenn wir gehen? Die grundlegenden Tools, die ich zur Hand habe, sind Toad, der "SQL Developer" von Oracle, MS Office und Visio.

57
Paul Tomblin

Nach meiner Erfahrung sind ER-Diagramme (oder UML-Diagramme) nicht das nützlichste Artefakt. Bei einer großen Anzahl von Tabellen sind Diagramme (insbesondere umgekehrt erstellte) oft ein großes, verworrenes Durcheinander, von dem niemand etwas lernt.

Für mein Geld erhalten Sie mit einer gut lesbaren Dokumentation (möglicherweise ergänzt durch Diagramme kleinerer Teile des Systems) die meisten Kilometer. Dies beinhaltet für jede Tabelle:

  • Beschreibungen der Bedeutung und Funktionsweise der Tabelle (in der Benutzeroberfläche usw.)
  • Beschreibungen, was jedes Attribut bedeutet, wenn es nicht offensichtlich ist
  • Erklärungen der Beziehungen (Fremdschlüssel) von dieser Tabelle zu anderen und umgekehrt
  • Erläuterungen zu zusätzlichen Einschränkungen und/oder Triggern
  • Zusätzliche Erklärung der wichtigsten Views & Procs, die die Tabelle berühren, wenn sie noch nicht gut dokumentiert sind

Dokumentieren Sie bei all dem nicht, um zu dokumentieren - Dokumentation, die das Offensichtliche wiedergibt, behindert nur die Menschen. Konzentrieren Sie sich stattdessen auf das, was Sie zuerst verwirrt hat, und schreiben Sie einige Minuten lang wirklich klare, prägnante Erklärungen. Das wird Ihnen helfen, darüber nachzudenken, und es wird massiv anderen Entwicklern helfen, die zum ersten Mal auf diese Tabellen stoßen.

Wie bereits erwähnt, gibt es eine Vielzahl von Tools, die Sie bei der Verwaltung unterstützen, z. B. Enterprise Architect , Red Gate SQL Doc und die integrierten Tools verschiedener Hersteller . Obwohl die Unterstützung von Tools hilfreich ist (und in größeren Datenbanken sogar von entscheidender Bedeutung ist), ist die harte Arbeit des Verstehens und Erklärens das konzeptionelle Modell der Datenbank das echter Gewinn. Unter diesem Gesichtspunkt können Sie es sogar in einer Textdatei tun (obwohl es in Wiki-Form möglich wäre, dass mehrere Personen zusammenarbeiten, um diese Dokumentation schrittweise zu ergänzen. Jedes Mal, wenn jemand etwas herausfindet, kann er es dem wachsenden Körper hinzufügen der Dokumentation sofort).

63
Ian Varley

In unserem Team haben wir einen nützlichen Ansatz zur Dokumentation älterer großer Oracle- und SQL Server-Datenbanken gefunden. Wir verwenden Dataedo zum Dokumentieren von Datenbankschemaelementen (Data Dictionary) und zum Erstellen von ERD-Diagrammen. Im Lieferumfang von Dataedo ist ein Dokumentations-Repository enthalten, sodass Ihr gesamtes Team die neuesten Dokumentationen online dokumentieren und lesen kann. Außerdem müssen Sie nicht in die Datenbank eingreifen (Oracle-Kommentare oder SQL Server MS_Description).

Zuerst importieren Sie das Schema (alle Tabellen, Ansichten, gespeicherten Prozeduren und Funktionen - mit Triggern, Fremdschlüsseln usw.). Anschließend definieren Sie logische Domänen/Module und gruppieren alle Objekte (Drag & Drop) in diese, um kleinere Datenbankabschnitte analysieren und bearbeiten zu können. Für jedes Modul erstellen Sie ein ERD-Diagramm und schreiben eine Beschreibung der obersten Ebene. Wenn Sie dann die Bedeutung von Tabellen und Ansichten entdecken, schreiben Sie für jede eine kurze Beschreibung. Machen Sie dasselbe für jede Spalte. In Dataedo können Sie jedem Objekt und jeder Spalte einen aussagekräftigen Titel hinzufügen. Dies ist hilfreich, wenn die Objektnamen vage oder ungültig sind. Mit der Pro-Version können Sie Fremdschlüssel, eindeutige Schlüssel/Einschränkungen und Trigger beschreiben. Dies ist nützlich, aber nicht unbedingt erforderlich, um eine Datenbank zu verstehen.

Sie können auf die Dokumentation über die Benutzeroberfläche zugreifen oder sie in PDF oder interaktives HTML) exportieren (letzteres ist nur in der Pro-Version verfügbar).

Hier wird eher ein kontinuierlicher Prozess als ein einmaliger Job beschrieben. Wenn sich Ihre Datenbank ändert (z. B. neue Spalten, Ansichten), sollten Sie Ihre Dokumentation regelmäßig synchronisieren (paar Klicks mit Dataedo).

Siehe Beispieldokumentation: http://dataedo.com/download/Dataedo%20repository.pdf

Einige Richtlinien zum Dokumentationsprozess:

Diagramme:

  • Halten Sie Ihre Diagramme klein und lesbar - schließen Sie nur wichtige Tabellen, Beziehungen und Spalten ein - nur die, die eine Bedeutung für das Verständnis des Gesamtbildes haben - Primär-/Geschäftsschlüssel, wichtige Attribute und Beziehungen,
  • Verwenden Sie eine andere Farbe für Schlüsseltabellen in einem Diagramm.
  • Sie können mehr als ein Diagramm pro Modul haben,
  • Sie können Diagramme zur Beschreibung der wichtigsten Tabellen/mit den meisten Beziehungen hinzufügen.

Beschreibungen:

  • Dokumentieren Sie nicht das Offensichtliche - schreiben Sie nicht die Beschreibung "Dokumentdatum" für die Spalte "document.date". Wenn Sie nichts hinzufügen möchten, lassen Sie das Feld leer.
  • Wenn in Tabellen gespeicherte Objekte Typen oder Status haben, empfiehlt es sich, sie in der allgemeinen Beschreibung einer Tabelle aufzulisten.
  • Definieren Sie das zu erwartende Format, z. "MM/TT/JJ" für ein Datum, das im Textfeld gespeichert ist,
  • Listen Sie alle bekannten/wichtigen Werte auf und geben Sie die Bedeutung an, z. für die Statusspalte könnte etwa so lauten: "Dokumentstatus: A - Aktiv, C - Abgebrochen, D - Gelöscht",
  • Wenn es zu einer Tabelle eine API gibt - eine Ansicht, die zum Lesen von Daten und Funktionen/Prozeduren zum Einfügen/Aktualisieren von Daten verwendet werden sollte -, listen Sie sie in der Beschreibung der Tabelle auf.
  • Beschreiben Sie, woher die Werte von Zeilen/Spalten stammen (Prozedur, Formular, Schnittstelle usw.).
  • Verwenden Sie die Markierung "[veraltet]" (oder eine ähnliche Markierung) für Spalten, die nicht verwendet werden sollen (Titelspalte ist hierfür hilfreich, erklären Sie, welches Feld stattdessen im Beschreibungsfeld verwendet werden soll).
7
Bad Pitt

Eine zu berücksichtigende Sache ist die in das DBMS eingebaute COMMENT-Funktion. Wenn Sie alle Tabellen und Spalten im DBMS selbst kommentieren, befindet sich Ihre Dokumentation im Datenbanksystem.

Mit der COMMENT-Funktion werden keine Änderungen am Schema selbst vorgenommen, sondern nur Daten zur Katalogtabelle USER_TAB_COMMENTS hinzugefügt.

7
Steven Huwig

Wir verwenden Enterprise Architect für unsere DB-Definitionen. Wir schließen gespeicherte Prozeduren, Trigger und alle in UML definierten Tabellendefinitionen ein. Die drei herausragenden Merkmale des Programms sind:

  1. Importieren Sie UML-Diagramme aus einer ODBC Verbindung.
  2. Generieren Sie SQL Scripts (DDL) für die gesamte Datenbank auf einmal
  3. Generieren Sie eine benutzerdefinierte Dokumentationsvorlage für Ihre Datenbank.

Sie können Ihre Klassen-/Tabellendefinitionen im UML-Tool bearbeiten und ein vollständig beschreibendes Dokument mit Bildern erstellen. Das automatisch generierte Dokument kann in mehreren Formaten vorliegen, einschließlich MSWord. Wir haben nur weniger als 100 Tabellen in unserem Schema und es ist ziemlich überschaubar.

Ich war in meinen über 10 Jahren als Entwickler noch nie so beeindruckt von einem anderen Tool. EA unterstützt Oracle, MySQL, SQL Server (mehrere Versionen), PostGreSQL, Interbase, DB2 und Access auf einen Schlag. Jedes Mal, wenn ich Probleme hatte, haben ihre Foren meine Probleme umgehend beantwortet. Sehr empfehlenswert!!

Wenn DB-Änderungen eingehen, nehmen wir diese in EA vor, generieren die SQL und checken sie in unsere Versionskontrolle (svn) ein. Wir verwenden Hudson zum Erstellen, und es erstellt automatisch die Datenbank aus Skripten, wenn Sie feststellen, dass Sie die eingecheckte SQL geändert haben.

( Meistens aus einer anderen Antwort von mir gestohlen )

7
Kieveli

Hier ist ein guter Beitrag zur Vorgehensweise bei der Datenbankdokumentation: http://www.simple-talk.com/sql/database-administration/database-documentation---lands-of-trolls-why-and -wie /

4
Bob

Eine Wiki-Lösung unterstützt Hyperlinks und kollaboratives Bearbeiten, aber ein Wiki ist nur so gut wie die Leute, die es organisiert und auf dem neuesten Stand halten. Sie benötigen jemanden, der die Verantwortung für das Dokumentprojekt übernimmt, unabhängig davon, welches Tool Sie verwenden. Diese Person kann andere sachkundige Personen einbeziehen, um die Details auszufüllen, aber eine Person sollte für die Organisation der Informationen verantwortlich sein.

Wenn Sie kein Tool zum Generieren einer ERD durch Reverse Engineering verwenden können, müssen Sie eine von Hand mit TOAD oder VISIO entwerfen.

Jedes ERD mit Hunderten von Objekten ist wahrscheinlich als Leitfaden für Entwickler nutzlos, da es mit so vielen Kästchen und Linien nicht lesbar ist. In einer Datenbank mit so vielen Objekten gibt es wahrscheinlich "Subsysteme" mit jeweils ein paar Dutzend Tabellen und Ansichten. Sie sollten daher benutzerdefinierte Diagramme dieser Subsysteme erstellen, anstatt ein Tool zu erwarten, das dies für Sie erledigt.

Sie können auch eine Pseudo-ERD entwerfen, bei der Gruppen von Tabellen in einem Diagramm durch ein einzelnes Objekt dargestellt werden und diese Gruppe in einem anderen Diagramm erweitert wird.

Eine einzelne ERD oder ein Satz von ERDs reicht nicht aus, um ein System dieser Komplexität zu dokumentieren. Mehr als ein Klassendiagramm wäre nicht ausreichend, um ein OO System zu dokumentieren. Sie müssen ein Dokument schreiben Verwenden der ERDs zur Veranschaulichung Sie benötigen Textbeschreibungen zur Bedeutung und Verwendung jeder Tabelle, jeder Spalte und der Beziehungen zwischen Tabellen (insbesondere, wenn solche Beziehungen implizit sind, anstatt durch referenzielle Integritätsbedingungen dargestellt zu werden).

All dies ist viel Arbeit, aber es wird sich lohnen. Wenn es einen klaren und aktuellen Ort gibt, an dem das Schema dokumentiert ist, wird das gesamte Team davon profitieren.

3
Bill Karwin

Diese Antwort erweitert Kieveli's oben, was ich positiv bewertet habe. Wenn Ihre Version von EA die Objektrollenmodellierung unterstützt (konzeptionelles Design vs. logisches Design = ERD), führen Sie einen Reverse Engineering durch, und füllen Sie das Modell mit dem Ausdrucksreichtum aus, den es Ihnen bietet.

Die günstige und leichtere Option ist, Visiomodeler kostenlos von MS herunterzuladen und das Gleiche damit zu tun.

Das ORM (als ORMDB bezeichnet) ist das einzige Tool, das ich jemals gefunden habe und das Datenbankdesign-Konversationen mit Nicht-IS-Stakeholdern über BL-Objekte und -Beziehungen unterstützt und fördert.

Reality Check - Auf dem Weg zur Generierung Ihrer DDL durchläuft diese eine vollständige ERD-Phase, in der Sie Ihre Fragen dazu beantworten können, ob etwas verkehrt läuft. Das tut es nicht. Es wird Ihnen wahrscheinlich Schwächen in der ERD zeigen, die Sie selbst entworfen haben.

ORMDB ist ein klassischer Fall des Prinzips, dass der Markt umso kleiner ist, je konzeptioneller das Tool ist. Mädchen wollen einfach nur Spaß haben und Programmierer wollen einfach nur Code.

3
dkretz

Wenn es Ihr primäres Ziel ist, Ihre Datenbanken Ihren Endbenutzern zu beschreiben Ooluk Data Dictionary Manager kann sich als nützlich erweisen. Es handelt sich um eine webbasierte Mehrbenutzer-Software, mit der Sie Beschreibungen an Tabellen und Spalten anhängen und Volltextsuchen für diese Beschreibungen durchführen können. Außerdem können Sie Tabellen mithilfe von Beschriftungen logisch gruppieren und Tabellen mithilfe dieser Beschriftungen durchsuchen. Tabellen und Spalten können mit Tags versehen werden, um ähnliche Datenelemente in Ihrer Datenbank/Ihren Datenbanken zu finden.

Mit der Software können Sie Metadateninformationen wie Tabellenname, Spaltenname, Spaltendatentyp und Fremdschlüssel über eine API in das interne Repository importieren. Die Unterstützung für JDBC-Datenquellen ist integriert und kann durch die Verteilung der API-Quelle unter ASL 2.0 erweitert werden. Es ist codiert, um die KOMMENTARE/ANMERKUNGEN aus vielen RDBMS zu lesen. Sie können die importierten Informationen jederzeit manuell überschreiben. Die Informationen, die Sie zu Tabellen und Spalten speichern können, können mithilfe benutzerdefinierter Felder erweitert werden.

Der Data Dictionary Manager verwendet die Terminologie "Datenobjekt" und "Attribut" anstelle von Tabelle und Spalte, da diese nicht speziell für relationale Datenbanken entwickelt wurden.

Anmerkungen

  • Wenn es darum geht, technische Aspekte Ihrer Datenbank wie Trigger, Indizes und Statistiken zu beschreiben, ist diese Software nicht die beste Option. Es ist jedoch möglich, eine technische Lösung mit dieser Software über benutzerdefinierte Hyperlinkfelder zu kombinieren.
  • Die Software erstellt keine ERD

Offenlegung: Ich arbeite bei der Firma, die dieses Produkt entwickelt.

1

Da Sie den Luxus haben, mit anderen Entwicklern zusammenzuarbeiten, die sich im selben Boot befinden, würde ich vorschlagen, sie zu fragen, was ihrer Meinung nach die benötigten Informationen am einfachsten vermitteln würde. In meiner Firma gibt es über 100 Tische, und mein Chef hat mir eine ERD für einen bestimmten Tischsatz gegeben, die alle miteinander verbunden sind. Vielleicht möchten Sie auch versuchen, eine massive ERD in eine Reihe kleinerer, handhabbarer ERDs aufzuteilen.

1
theman_on_vista

Nun, ein Bild sagt mehr als tausend Worte. Daher würde ich empfehlen, ER-Diagramme zu erstellen, in denen Sie die Beziehung zwischen Tabellen auf einen Blick sehen können, was mit einer Nur-Text-Beschreibung nur schwer möglich ist.

Sie müssen nicht die gesamte Datenbank in einem Diagramm erstellen, sondern sie in Abschnitte aufteilen. Wir verwenden Visual Paradigm bei der Arbeit, aber EA ist eine gute Alternative, ebenso wie ERWIN, und zweifellos gibt es viele andere, die genauso gut sind.

Wenn Sie die Geduld haben, erleichtert die Verwendung von HTML zum Dokumentieren der Tabellen und Spalten den Zugriff auf Ihre Dokumentation.

0
James Piggot