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.