Versionierung (Eigenentwicklung)

Diese Seite ist ein Teil der IsyFact-Standards. Alle Inhalte der Seite, insbesondere Texte und Grafiken, sind urheberrechtlich geschützt. Alle urheberrechtlichen Nutzungs- und Verwertungsrechte liegen beim Bundesverwaltungsamt.

Creative Commons Namensnennung Die Nutzung ist unter den Lizenzbedingungen der Creative Commons Namensnennung 4.0 International gestattet.

Diese Seite dokumentiert die Versionierung von Datenbankschemas mittels einer Eigenentwicklung. Das empfohlene Vorgehen ist die Versionierung mit Liquibase.

Die Umsetzung der Versionierung beschreibt die Struktur der Versionsmetadaten, die Ablage der Skripte in den Projekten sowie weitere Anwendungsfälle wie z.B. das Prüfen eines Schemas auf Aktualität.

1. Struktur der Versionsmetadaten

Die Informationen über Versionen und durchgeführte Änderungen an einem Datenbankschema werden innerhalb des Schemas in eigenen Metadatentabellen gespeichert. Hierzu muss jedes Datenbankschema die folgenden Tabellen enthalten.

1.1. Tabelle `M_SCHEMA_VERSION`

Die Tabelle M_SCHEMA_VERSION enthält die Information über die aktuelle Version des Schemas. Die Tabelle hat die folgende Struktur:

Tabelle 1. Tabelle M_SCHEMA_VERSION
Spalte	Typ	Beschreibung
`version_nummer`	Zeichenkette (25 Zeichen)	Versionsnummer des Datenbankschemas. Diese Versionsnummer entspricht der Versionsnummer der Anwendung, mit der sich das Schema geändert hat.
`update_nummer`	Zeichenkette (5 Zeichen)	Update-Zähler, der jedes Mal hochgezählt wird, wenn sich das Datenbankschema ändert, aber die Anwendung unverändert bleibt.
`status`	Zeichenkette (25 Zeichen)	Status des Schemas: `gueltig`: Das Schema wurde korrekt installiert bzw. aktualisiert und kann verwendet werden. `bereit`: Das Schema ist bereit Schema-übergreifende Operationen durchzuführen. `ungueltig`: Das Schema befindet sich im Aufbau bzw. in der Änderung oder die Installation wurde nur teilweise durchgeführt und wurde mit Fehlern abgebrochen. Das Schema kann nicht verwendet werden und muss überprüft werden.

1.2. Tabelle `M_SCHEMA_LOG`

Die Tabelle M_SCHEMA_LOG enthält Information über eingespielte Skripte zur Anpassung des Schemas. Die Tabelle hat die folgende Struktur:

Tabelle 2. Tabelle M_SCHEMA_LOG
Spalte	Typ	Beschreibung
`schemaversion`	Zeichenkette (25 Zeichen)	Versionsnummer des Schemas, zu dessen Erstellung bzw. Anpassung das Skript genutzt wurde.
`schemaupdate`	Zeichenkette (5 Zeichen)	Update-Zähler, der jedes Mal hochgezählt wird, wenn sich das Datenbankschema ändert, aber die Anwendung unverändert bleibt.
`schritt`	Zeichenkette (10 Zeichen)	Nummer des Schrittes im Installationsablauf.
`beschreibung`	Zeichenkette (100 Zeichen)	Kurzbeschreibung des Installationsschrittes.
`skript`	Zeichenkette (100 Zeichen)	Name des ausgeführten Skripts.
`skript_start`	Zeitstempel	Zeitpunkt, an dem das Skript gestartet wurde.
`skript_ende`	Zeitstempel	Zeitpunkt, an dem das Skript beendet wurde.
`status`	Zeichenkette (25 Zeichen)	Status der Skriptausführung: wird ausgeführt: Skript wurde gestartet und läuft oder wurde abgebrochen erfolgreich: Skript wurde erfolgreich abgearbeitet

2. Ablage der Skripte und Namenskonventionen

Die Skripte werden im Source-Projekt der Anwendung, zu der sie gehören, im Verzeichnis src/main/skripte/sql/<dbschema-name> abgelegt. In diesem Verzeichnis liegen die Unterverzeichnisse db-install-<Versionsnummer> für Installationsskripte und db-update-<Versionsnummer> für Updateskripte. <Versionsnummer> gibt dabei die Versionsnummer des Datenbankschemas, einschließlich der Update-Nummer, an (z. B. 1.2.3_01).

Für die aktuelle Datenbankversion muss es ein vollständiges Installationsskript geben. Wurden Änderungen am Schema vorgenommen, gibt es zusätzlich ein entsprechendes Update-Skript von der Vorversion auf die aktuelle Version. Das Verzeichnis enthält so immer das Installationsskript für die aktuelle Datenbankversion und Update-Skripte, um jede beliebige Vorversion seit Einführung der Schema-Versionierung auf die aktuelle Datenbankversion anheben zu können.

Die einzelnen Skripte werden auf der Grundlage der Templates aus der Bibliothek isy-persistence erstellt und behalten auch deren Namen.

Die eigentlichen Installations- und Update-Skripte haben das feste Namensschema: <Schrittnummer>-<Unterschrittnummer>_<Name>.sql. Die Schrittnummer ist 2-stellig und entspricht der Schrittnummer aus dem Installationsablauf bei der Neuanlage bzw. Installationsablauf bei der Schemaänderung. Falls zu einem Schritt mehrere Skripte gehören, gibt die Unterschrittnummer die Reihenfolge an, in der diese ausgeführt werden. Der Name kann frei vergeben werden, sollte aber sprechend sein.

3. Schema-übergreifende Operationen

Sollte eine Anwendung Schema-übergreifende Operationen haben, wird das vorgestellte DB-Versionierungskonzept wie folgt erweitert. Die Skripte der Schema-übergreifenden Operationen werden gemäß der Ablage der Skripte und Namenskonventionen in einen eigenen Ordner unter src/main/skripte/sql/uebergreifend abgelegt. Die hier abgelegten Skripte werden immer als letztes ausgeführt. Zuvor werden alle anderen Schemata installiert.

Die Skripte im Ordner uebergreifend werden ebenfalls im gewohnten DB-Versionierungskonzept Format abgelegt. Die Schrittnummer ist 2-stellig und entspricht der Schrittnummer aus dem Installationsablauf bei der Neuanlage. Allerdings beginnt die Schrittnummer mit 91 statt mit 01. Die einzelnen Skripte werden in der richtigen Reihenfolge über das Hilfsskript 99_starte-skript-mit-logging.sql aufgerufen und in der Tabelle M_SCHEMA_LOG des Hauptschemas der Anwendung protokolliert.

Die Skripte im Hauptschema der Anwendung setzen, nach erfolgreicher Ausführung, den Status von M_SCHEMA_VERSION auf bereit statt auf gueltig. Das signalisiert, dass das Schema bereit ist, die Schema-übergreifenden Operationen durchzuführen. Vor der Ausführung der Skripte im Ordner uebergreifend wird geprüft, dass der Status des Hauptschemas auf bereit steht. Erst nach der erfolgreichen Ausführung aller Schritte des Schemas uebergreifend wird der Status auf gueltig gesetzt.

Mit den übergreifenden Skripten sollen auch die Zugriffsrechte für die Queue(s) eines Backends vergeben werden, sofern diese existieren. Die entsprechenden Datenbanknutzer der Systeme, die Zugriff auf die Queue(s) haben sollen, sind dann in der Datei 91_environment.sql einzutragen. In einem Skript 93-X.sql können dann die Rechte je nach Bedarf vergeben werden. Auf diese Weise legt das Backend selbst fest, welche anderen Systeme Zugriff auf die Queue(s) haben.

4. Prüfen der Schema-Version

Jede Anwendung prüft beim Start, ob das DB-Schema die erwartete Version hat. Diese Prüfung ist in der Bibliothek isy-persistence fest eingebaut. In der Anwendungskonfiguration müssen in application.properties die folgenden Properties gesetzt werden:

Listing 1. Konfiguration der Schema-Version

isy.persistence.datasource.schema-invalid-version-action=fail
isy.persistence.datasource.schema-version=1.2.3

In der Property schema-version wird die Versionsnummer des Datenbankschemas angegeben, das die Anwendung erwartet. Wird die Property schema-version oder der Wert für die Version nicht angegeben, so findet keine Überprüfung der Schema-Version statt.

In der Property schema-invalid-version-action wird festgelegt, wie die DataSource auf eine falsche Schema-Version reagieren soll. Der Wert fail legt fest, dass eine Exception geworfen wird. Das hat zur Folge, dass die Anwendung nicht gestartet werden kann. Der Wert warn legt fest, dass lediglich eine Warnung in die Log-Datei geschrieben wird.

Bei Datenmigrationen muss jedes Skript vor der Ausführung prüfen, ob die Datenbank die erwartete Version hat. Das kann mit dem folgenden SQL-Statement durchgeführt werden:

Listing 2. SQL-Query zur Prüfung der Schema-Version

SELECT version
  FROM m_schema_version
 WHERE version_nummer = '<schemaVersion>'
   AND status = 'gueltig';

Liefert dieses SQL-Statement einen Wert zurück, dann ist die erwartete Schema-Version vorhanden. Liefert es keinen Wert zurück, dann ist die erwartete Schema-Version nicht vorhanden.