4Max/shutterstock.com

31. Januar 2013 / von Kay Dörnemann

Datenbank-

beschreibung

leicht

gemacht

Zu jeder guten Software-Entwicklung gehört auch die Dokumentation. Neben der Code-Dokumentation auch eine Komponentenbeschreibung und darin enthalten eine detaillierte Beschreibung des Datenmodells, wie es zum Beispiel in der Datenbank vorhanden ist. Im Rahmen dieses Beitrags wird eine Methode zur Erzeugung und Aktualisierung einer solchen Dokumentation vorgestellt, die dem Entwickler das Leben leichter und effizienter macht. Dieser Artikel richtet sich hauptsächlich an Entwickler, aber auch an Architekten und Projektleiter.

Solange der Entwickler noch aktiv an einer Komponente im Projekt arbeitet hat er meistens kein Problem zu verstehen, wie der Code funktioniert. Anders sieht es aus wenn mehrere Personen an einem Projekt arbeiten, ein größerer zeitlicher Abstand zur letzten Änderung besteht oder eine Weiterentwicklung durch andere Entwickler ansteht. Für diese Fälle hat es sich eingebürgert den Code zu kommentieren – nicht immer mit der richtigen Gewichtung (zum Beispiel 80% Abdeckung aber hauptsächlich GET- und SET-Methoden kommentiert) und nötigen Ausführlichkeit. Anders sieht es oftmals bei der Beschreibung des Datenmodells aus. Meist findet sich ein umfassender Abschnitt in der Komponentenbeschreibung oder einem ähnlichen Dokument, gerne am Anfang der Entwicklung erstellt, so dass es am Ende nicht mehr richtig zum Projekt passen mag. Spätestens aber mit der Weiterentwicklung ergeben sich zwangsläufig Unterschiede, die es auszugleichen gilt. Bestehen zu diesem Zeitpunkt bereits Unterschiede oder Lücken, sinkt die Motivation hier noch viel Zeit zu investieren. Vielleicht herrscht auch die Meinung, dass die Struktur sowieso nicht sonderlich aufwändig ist und sie sich von alleine erklärt. Möglicherweise existiert auch noch ein (dokumentiertes) Mapping. Die Anpassungen einer Dokumentation werden schnell aufwändig, da die Dokumentation oftmals händisch erzeugt wurde, zum Beispiel in Form eines Word-Dokuments und einer Visio-Grafik.

In diesem Beitrag geht es darum, wie die Erzeugung und Aktualisierung einer solchen Beschreibung automatisiert und vereinfacht werden kann. Als Beispiel wähle ich als Datenbank-Software Microsoft SQL. Bei anderen Datenbanken gibt es sicherlich ähnliche Methoden und Möglichkeiten um ebenfalls zum Ergebnis zu kommen. Dieser Beitrag soll kein Tutorial darstellen, sondern viel mehr einige interessante Möglichkeiten aufzeigen.

Die Beziehungen innerhalb der Datenbank lassen sich relativ schnell mit dem Microsoft SQL Management Studio (MS SMS) visualisieren und in eine Grafik gießen. Über die ODBC-Schnittstelle unter Windows kann die Datenbank zum Beispiel auch von Visio gelesen werden und grafisch aufbereitet dargestellt werden. Damit erhält der Entwickler eine visuelle Beschreibung der Beziehungen, aber die Bedeutung von Tabellen, Schlüssel, Stored Procedures usw. ergibt sich daraus nicht.

Auf den ersten Blick bietet es sich hier an das SQL-Skript, das zur Erzeugung verwendet wird, zu kommentieren. Grundsätzlich keine schlechte Idee, aber spätestens bei einer Weiterentwicklung, bei der die Datenbank nicht komplett neu aufgesetzt wird, ergeben sich zwangsläufig neue Skripte mit partiellen Änderungen. Es wird schnell unübersichtlich und unstrukturiert.

Hier kommen nun die „Extended Properties“ ins Spiel. Jede Tabelle, jede Stored Procedure, jeder Schlüssel kann mit den Extended Properties erweitert werden. Damit lassen sich maschinenlesbare Informationen unterbringen. Für die Dokumentation einer Datenbank gibt es ein spezielles Property mit dem Namen „MS_Description“. In dieser Eigenschaft kann die komplette Beschreibung des Datenbank-Elements untergebracht werden. Der erste Schritt zu einer einfacheren Datenbank Beschreibung. Diese Eigenschaft lässt sich mit dem MS SMS anlegen und bearbeiten. Sie lässt sich aber auch bequemer über eine Stored Procedure setzen.

sp_addextendedproperty
[ @name = ] { 'property_name' }
    [ , [ @value = ] { 'value' }
        [ , [ @level0type = ] { 'level0_object_type' }
          , [ @level0name = ] { 'level0_object_name' }
                [ , [ @level1type = ] { 'level1_object_type' }
                  , [ @level1name = ] { 'level1_object_name' }
                        [ , [ @level2type = ] { 'level2_object_type' }
                          , [ @level2name = ] { 'level2_object_name' }
                   ]
                ]
        ]
    ]
[;]

Die unterschiedlichen Level ergeben sich aus der Verschachtelungstiefe der Datenbank (z. B. 0: Schema à 1: Tabelle à 2: Column) und der Name gibt jeweils das konkret zu ändernde Objekt an.

Wird dieses Verfahren von Anfang an angewendet, bedeutet es für jedes Element im Erzeugungsskript jeweils eine weitere Zeile mit der Beschreibung. Kommen dabei Werkzeuge wie die des SQL Toolbelts von Red Gate zum Einsatz, können die Beschreibungen auch direkt in der Oberfläche eingegeben werden und landen dann automatisch im erzeugten Skript bzw. in der erzeugten Datenbank.

Bei bestehenden, undokumentierten Datenbanken empfiehlt es sich eine Kopie der Datenbank anzulegen und die Beschreibung direkt in die Datenbank einzugeben und anschließend mit einem geeigneten Werkzeug ein Skript erzeugen zu lassen, dass nur die Unterschiede enthält. Hier bietet sich zum Beispiel SQL Compare von Red Gate oder Adept SQL Diff von Adept an. Alternativ kann natürlich auch ein Skript, mit der oben genannten Stored Procedure, per Hand angelegt werden, das die Dokumentation in die Datenbank einspielt.

Ist die Datenbank einmal in dieser Form dokumentiert, ist die Dokumentation nur noch bei Änderungen, zum Beispiel im Rahmen einer Weiterentwicklung, an einer Stelle anzupassen und jeweils in das SQL-Skript einzufügen. Im laufenden Betrieb kann die Dokumentation nun direkt in der Datenbank betrachtet werden. Muss sie neu aufgesetzt werden, wird automatisch auch die Dokumentation wieder eingespielt. Die Performance der Abfragen wird nicht beeinflusst und der zusätzlich benötigte Speicherplatz richtet sich nach der Menge der eingegebenen Dokumentation und der Menge der beschriebenen Elemente.

Nun ist aber eine Dokumentation in der Datenbank zwar sehr schön und immer dann verfügbar, wenn auch die Datenbank verfügbar ist. Aber sonderlich gut arbeiten lässt es sich damit nicht. Besser wäre es nun diese Dokumentation in einer handlicheren Form zur Verfügung zu haben. Hier bieten sich diverse Werkzeuge an, SQLDoc von Red Gate, SQLDoc oder Turtle SQL von amit_ary (beide Open Source) und viele mehr. Damit lassen sich zum Beispiel html-Seiten, XML-Dokumente oder die in der .Net/Windows-Welt beliebten kompilierten html-Hilfe-Dateien (chm) erzeugen.

Die so erzeugte Dokumentation ist handlich und lässt sich jederzeit auf Knopfdruck erneut erzeugen. Manches Werkzeug lässt sich auch in MSBuild, Nant und weitere automatische Build-Systeme integrieren, so dass nicht nur für den Code sondern auch für die Datenbank eine aktuelle Dokumentation automatisch erzeugt werden kann. Die Integration erfolgt dabei über Tasks, die die genannten Erzeugungswerkzeuge teilweise anbieten.

Der hier beschriebene Aufwand hält sich in Grenzen und lohnt sich aus meiner Sicht sehr. Wird es konsequent betrieben, sollte der Aufwand geringer sein als die Pflege einer eigenständigen Dokumentation.

[1] http://www.red-gate.com

 

Autor

Kay Dörnemann Kay ist seit Juli 2011 als Senior Software Ingenieur bei der Accelerated Solutions GmbH und beschäftigt sich dort mit Software-Entwicklung, hauptsächlich in Java.
Weitere Artikel

Das könnte Sie auch interessieren