4.3. SQL-Upgradedateien

4.3.1. Einführung

Datenbankupgrades werden über einzelne Upgrade-Scripte gesteuert, die sich im Verzeichnis sql/Pg-upgrade2 befinden. In diesem Verzeichnis muss pro Datenbankupgrade eine Datei existieren, die neben den eigentlich auszuführenden SQL- oder Perl-Befehlen einige Kontrollinformationen enthält.

Kontrollinformationen definieren Abhängigkeiten und Prioritäten, sodass Datenbankscripte zwar in einer sicheren Reihenfolge ausgeführt werden (z.B. darf ein ALTER TABLE erst ausgeführt werden, wenn die Tabelle mit CREATE TABLE angelegt wurde), diese Reihenfolge aber so flexibel ist, dass man keine Versionsnummern braucht.

kivitendo merkt sich dabei, welches der Upgradescripte in sql/Pg-upgrade2 bereits durchgeführt wurde und führt diese nicht erneut aus. Dazu dient die Tabelle "schema_info", die bei der Anmeldung automatisch angelegt wird.

4.3.2. Format der Kontrollinformationen

Die Kontrollinformationen sollten sich am Anfang der jeweiligen Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält, hat dabei das folgende Format:

Für SQL-Upgradedateien:

-- @key: value

Für Perl-Upgradedateien:

# @key: value

Leerzeichen vor "value" werden entfernt.

Die folgenden Schlüsselworte werden verarbeitet:

tag

Wird zwingend benötigt. Dies ist der "Name" des Upgrades. Dieser "tag" kann von anderen Kontrolldateien in ihren Abhängigkeiten verwendet werden (Schlüsselwort "depends"). Der "tag" ist auch der Name, der in der Datenbank eingetragen wird.

Normalerweise sollte die Kontrolldatei genau so heißen wie der "tag", nur mit der Endung ".sql" bzw. "pl".

Ein Tag darf nur aus alphanumerischen Zeichen sowie den Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht erlaubt und sollten stattdessen mit Unterstrichen ersetzt werden.

charset

Empfohlen. Gibt den Zeichensatz an, in dem das Script geschrieben wurde, z.B. "UTF-8". Aus Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz "ISO-8859-15" angenommen. Perl-Upgradescripte hingegen müssen immer in UTF-8 encodiert sein und sollten demnach auch ein "use utf8;" enthalten.

description

Benötigt. Eine Beschreibung, was in diesem Update passiert. Diese wird dem Benutzer beim eigentlichen Datenbankupdate angezeigt. Während der Tag in Englisch gehalten sein sollte, sollte die Beschreibung auf Deutsch erfolgen.

depends

Optional. Eine mit Leerzeichen getrennte Liste von "tags", von denen dieses Upgradescript abhängt. kivitendo stellt sicher, dass die in dieser Liste aufgeführten Scripte bereits durchgeführt wurden, bevor dieses Script ausgeführt wird.

Abhängigkeiten werden rekursiv betrachtet. Wenn also ein Script "b" existiert, das von Änderungen in "a" abhängt, und eine neue Kontrolldatei für "c" erstellt wird, die von Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den Tag "b" als Abhängigkeit zu definieren.

Es ist nicht erlaubt, sich selbst referenzierende Abhängigkeiten zu definieren (z.B. "a" -> "b", "b" -> "c" und "c" -> "a").

priority

Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in der Scripte ausgeführt werden, die die gleichen Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird der Wert 1000 benutzt.

Dies ist reine Kosmetik. Für echte Reihenfolgen muss "depends" benutzt werden. kivitendo sortiert die auszuführenden Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y" abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von 2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt, dann "y", dann "z"), dann nach der Priorität und bei gleicher Priorität alphabetisch nach dem "tag".

ignore

Optional. Falls der Wert auf 1 (true) steht, wird das Skript bei der Anmeldung ignoriert und entsprechend nicht ausgeführt.

4.3.3. Format von in Perl geschriebenen Datenbankupgradescripten

In Perl geschriebene Datenbankscripte werden nicht einfach so ausgeführt sondern müssen sich an gewisse Konventionen halten. Dafür bekommen sie aber auch einige Komfortfunktionen bereitgestellt.

Ein Upgradescript stellt dabei eine vollständige Objektklasse dar, die vom Elternobjekt "SL::DBUpgrade2::Base" erben und eine Funktion namens "run" zur Verfügung stellen muss. Das Script wird ausgeführt, indem eine Instanz dieser Klasse erzeugt und darauf die erwähnte "run" aufgerufen wird.

Zu beachten ist, dass sich der Paketname der Datei aus dem Wert für "@tag" ableitet. Dabei werden alle Zeichen, die in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche ersetzt. Insgesamt sieht der Paketname wie folgt aus: "SL::DBUpgrade2::tag".

Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit "perldoc SL/DBUpgrade2/Base.pm".

Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie folgt aus:

# @tag: beispiel-upgrade-file42
# @description: Ein schönes Beispielscript
# @depends: release_3_1_0
package SL::DBUpgrade2::beispiel_upgrade_file42;

use strict;
use utf8;

use parent qw(SL::DBUpgrade2::Base);

sub run {
  my ($self) = @_;

  # hier Aktionen ausführen

  return 1;
}

1;

4.3.4. Hilfsscript dbupgrade2_tool.pl

Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern, existiert ein Hilfsscript namens "scripts/dbupgrade2_tool.pl". Es muss aus dem kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool liest alle Datenbankupgradescripte aus dem Verzeichnis sql/Pg-upgrade2 aus. Es benutzt dafür die gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen von der Kommandozeile überprüft werden können.

Wird dem Script kein weiterer Parameter übergeben, so wird nur eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann sich aber auch Informationen auf verschiedene Art ausgeben lassen:

  • Listenform: "./scripts/dbupgrade2_tool.pl --list"

    Gibt eine Liste aller Scripte aus. Die Liste ist in der Reihenfolge sortiert, in der kivitendo die Scripte ausführen würde. Es werden neben der Listenposition der Tag, die Abhängigkeitstiefe und die Priorität ausgegeben.

  • Baumform: "./scripts/dbupgrade2_tool.pl --tree"

    Listet alle Tags in Baumform basierend auf den Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von denen keine anderen abhängen. Die Unterknoten sind Scripte, die beim übergeordneten Script als Abhängigkeit eingetragen sind.

  • Umgekehrte Baumform: "./scripts/dbupgrade2_tool.pl --rtree"

    Listet alle Tags in Baumform basierend auf den Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte, die das übergeordnete Script als Abhängigkeit eingetragen haben.

  • Baumform mit Postscriptausgabe: "./scripts/dbupgrade2_tool.pl --graphviz"

    Benötigt das Tool "graphviz", um mit seiner Hilfe die umgekehrte Baumform in eine Postscriptdatei namens "db_dependencies.ps" auszugeben. Dies ist vermutlich die übersichtlichste Form, weil hierbei jeder Knoten nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben werden.

  • Scripte, von denen kein anderes Script abhängt: "./scripts/dbupgrade2_tool.pl --nodeps"

    Listet die Tags aller Scripte auf, von denen keine anderen Scripte abhängen.