projekt kivitendo

Neuer Mechanismus für SQL-Upgradedateien

----------------------------------------

Der alte Mechanismus für SQL-Upgradescripte, der auf einer

Versionsnummer beruht und dann in sql/Pg-upgrade nach einem Script für

diese Versionsnummer sucht, schränkt sehr ein, z.B. was die parallele

Entwicklung im stable- und unstable-Baum betrifft.

Dieser Mechanismus wurde für Lx-Office 2.4.1 deutlich erweitert. Es

werden weiterhin alle Scripte aus sql/Pg-upgrade

ausgeführt. Zusätzlich gibt es aber ein zweites Verzeichnis,

sql/Pg-upgrade2. In diesem Verzeichnis muss pro Datenbankupgrade eine

Datei existieren, die neben den eigentlich auszuführenden SQL- oder

Perl-Befehlen einige Kontrollinformationen enthält.

Neu sind die Kontrollinformationen, die Abhängigkeiten und Prioritäten

definieren können werden, 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 mehr braucht.

Lx-Office 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.

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 entfern.

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.

* 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. Lx-Office 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. Lx-Office 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".

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

Lx-Office-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 Lx-Office 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:

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

Gibt eine Liste aller Scripte aus. Die Liste ist in der Reihenfolge

sortiert, in der Lx-Office die Scripte ausführen würde. Es werden

neben der Listenposition der Tag, die Abhängigkeitstiefe und die

Priorität ausgegeben.

2. 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.

3. 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.

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

Benötigt das Tool "graphviz", um mit seiner Hilfe die Baumform aus

3. 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.

5. 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.