Neuer Mechanismus fr SQL-Upgradedateien
----------------------------------------

Der alte Mechanismus fr SQL-Upgradescripte, der auf einer
Versionsnummer beruht und dann in sql/Pg-upgrade nach einem Script fr
diese Versionsnummer sucht, schrnkt sehr ein, z.B. was die parallele
Entwicklung im stable- und unstable-Baum betrifft.

Dieser Mechanismus wurde fr Lx-Office 2.4.1 deutlich erweitert. Es
werden weiterhin alle Scripte aus sql/Pg-upgrade
ausgefhrt. Zustzlich gibt es aber ein zweites Verzeichnis,
sql/Pg-upgrade2. In diesem Verzeichnis muss pro Datenbankupgrade eine
Datei existieren, die neben den eigentlich auszufhrenden SQL- oder
Perl-Befehlen einige Kontrollinformationen enthlt.

Neu sind die Kontrollinformationen, die Abhngigkeiten und Prioritten
definieren knnen werden, sodass Datenbankscripte zwar in einer
sicheren Reihenfolge ausgefhrt werden (z.B. darf ein "ALTER TABLE"
erst ausgefhrt 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 durchgefhrt wurde und fhrt 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 enthlt,
hat dabei das folgende Format:

Fr SQL-Upgradedateien:

-- @key: value


Fr Perl-Upgradedateien:

# @key: value


Leerzeichen vor "value" werden entfern.

Die folgenden Schlsselworte werden verarbeitet:

* tag: Wird zwingend bentigt. Dies ist der "Name" des
  Upgrades. Dieser "tag" kann von anderen Kontrolldateien in ihren
  Abhngigkeiten verwendet werden (Schlsselwort "depends"). Der "tag"
  ist auch der Name, der in der Datenbank eingetragen wird.

  Normalerweise sollte die Kontrolldatei genau so heien 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: Bentigt. Eine Beschreibung, was in diesem Update
  passiert. Diese wird dem Benutzer beim eigentlichen Datenbankupdate
  angezeigt. Whrend 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 abhngt. Lx-Office stellt sicher,
  dass die in dieser Liste aufgefhrten Scripte bereits durchgefhrt
  wurden, bevor dieses Script ausgefhrt wird.

  Abhngigkeiten werden rekursiv betrachtet. Wenn also ein Script "b"
  existiert, das von nderungen in "a" abhngt, und eine neue
  Kontrolldatei fr "c" erstellt wird, die von nderungen in "a" und
  "b" abhngt, so gengt es, in "c" nur den Tag "b" als Abhngigkeit
  zu definieren.

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

* priority: Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
  der Scripte ausgefhrt werden, die die gleichen Abhngigkeitstiefen
  besitzen. Fehlt dieser Parameter, so wird der Wert 1000 benutzt.

  Dies ist reine Kosmetik. Fr echte Reihenfolgen muss "depends"
  benutzt werden. Lx-Office sortiert die auszufhrenden Scripte zuerst
  nach der Abhngigkeitstiefe (wenn "z" von "y" abhngt und "y" von
  "x", so hat "z" eine Abhngigkeitstiefe von 2, "y" von 1 und "x" von
  0. "x" wrde hier zuerst ausgefhrt, dann "y", dann "z"), dann nach
  der Prioritt und bei gleicher Prioritt alphabetisch nach dem
  "tag".

Hilfsscript dbupgrade2_tool.pl
------------------------------

Um die Arbeit mit den Abhngigkeiten 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 dafr die gleichen Methoden wie Lx-Office selber,
sodass alle Fehlersituationen von der Kommandozeile berprft werden
knnen.

Wird dem Script kein weiterer Parameter bergeben, so wird nur eine
berprfung der Felder und Abhngigkeiten 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 ausfhren wrde. Es werden
   neben der Listenposition der Tag, die Abhngigkeitstiefe und die
   Prioritt ausgegeben.

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

   Listet alle Tags in Baumform basierend auf den Abhngigkeiten
   auf. Die "Wurzelknoten" sind dabei die Scripte, von denen keine
   anderen abhngen. Die Unterknoten sind Scripte, die beim
   bergeordneten Script als Abhngigkeit eingetragen sind.

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

   Listet alle Tags in Baumform basierend auf den Abhngigkeiten auf.
   Die "Wurzelknoten" sind dabei die Scripte mit der geringsten
   Abhngigkeitstiefe. Die Unterknoten sind Scripte, die das
   bergeordnete Script als Abhngigkeit eingetragen haben.

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

   Bentigt 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 knnen Knoten und all ihre
   Abhngigkeiten mehrfach ausgegeben werden.

5. Scripte, von denen kein anderes Script abhngt:
   "./scripts/dbupgrade2_tool.pl --nodeps"

   Listet die Tags aller Scripte auf, von denen keine anderen Scripte
   abhngen.

