doc/sql-upgrade-dateien.txt

   1 Neuer Mechanismus für SQL-Upgradedateien
   2 ----------------------------------------
   3
   4 Der alte Mechanismus für SQL-Upgradescripte, der auf einer
   5 Versionsnummer beruht und dann in sql/Pg-upgrade nach einem Script für
   6 diese Versionsnummer sucht, schränkt sehr ein, z.B. was die parallele
   7 Entwicklung im stable- und unstable-Baum betrifft.
   8
   9 Dieser Mechanismus wurde für Lx-Office 2.4.1 deutlich erweitert. Es
  10 werden weiterhin alle Scripte aus sql/Pg-upgrade
  11 ausgeführt. Zusätzlich gibt es aber ein zweites Verzeichnis,
  12 sql/Pg-upgrade2. In diesem Verzeichnis muss pro Datenbankupgrade eine
  13 Datei existieren, die neben den eigentlich auszuführenden SQL- oder
  14 Perl-Befehlen einige Kontrollinformationen enthält.
  15
  16 Neu sind die Kontrollinformationen, die Abhängigkeiten und Prioritäten
  17 definieren können werden, sodass Datenbankscripte zwar in einer
  18 sicheren Reihenfolge ausgeführt werden (z.B. darf ein "ALTER TABLE"
  19 erst ausgeführt werden, wenn die Tabelle mit "CREATE TABLE" angelegt
  20 wurde), diese Reihenfolge aber so flexibel ist, dass man keine
  21 Versionsnummern mehr braucht.
  22
  23 Lx-Office merkt sich dabei, welches der Upgradescripte in
  24 sql/Pg-upgrade2 bereits durchgeführt wurde und führt diese nicht
  25 erneut aus. Dazu dient die Tabelle "schema_info", die bei der
  26 Anmeldung automatisch angelegt wird.
  27
  28 Format der Kontrollinformationen
  29 --------------------------------
  30
  31 Die Kontrollinformationen sollten sich am Anfang der jeweiligen
  32 Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
  33 hat dabei das folgende Format:
  34
  35 Für SQL-Upgradedateien:
  36
  37 -- @key: value
  38
  39
  40 Für Perl-Upgradedateien:
  41
  42 # @key: value
  43
  44
  45 Leerzeichen vor "value" werden entfernt.
  46
  47 Die folgenden Schlüsselworte werden verarbeitet:
  48
  49 * tag: Wird zwingend benötigt. Dies ist der "Name" des
  50   Upgrades. Dieser "tag" kann von anderen Kontrolldateien in ihren
  51   Abhängigkeiten verwendet werden (Schlüsselwort "depends"). Der "tag"
  52   ist auch der Name, der in der Datenbank eingetragen wird.
  53
  54   Normalerweise sollte die Kontrolldatei genau so heißen wie der
  55   "tag", nur mit der Endung ".sql" bzw. "pl".
  56
  57   Ein Tag darf nur aus alphanumerischen Zeichen sowie den Zeichen _ -
  58   ( ) bestehen. Insbesondere sind Leerzeichen nicht erlaubt und
  59   sollten stattdessen mit Unterstrichen ersetzt werden.
  60
  61 * description: Benötigt. Eine Beschreibung, was in diesem Update
  62   passiert. Diese wird dem Benutzer beim eigentlichen Datenbankupdate
  63   angezeigt. Während der Tag in englisch gehalten sein sollte, sollte
  64   die Beschreibung auf Deutsch erfolgen.
  65
  66 * depends: Optional. Eine mit Leerzeichen getrennte Liste von "tags",
  67   von denen dieses Upgradescript abhängt. Lx-Office stellt sicher,
  68   dass die in dieser Liste aufgeführten Scripte bereits durchgeführt
  69   wurden, bevor dieses Script ausgeführt wird.
  70
  71   Abhängigkeiten werden rekursiv betrachtet. Wenn also ein Script "b"
  72   existiert, das von Änderungen in "a" abhängt, und eine neue
  73   Kontrolldatei für "c" erstellt wird, die von Änderungen in "a" und
  74   "b" abhängt, so genügt es, in "c" nur den Tag "b" als Abhängigkeit
  75   zu definieren.
  76
  77   Es ist nicht erlaubt, sich selbst referenzierende Abhängigkeiten zu
  78   definieren (z.B. "a" -> "b", "b" -> "c" und "c" -> "a").
  79
  80 * priority: Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
  81   der Scripte ausgeführt werden, die die gleichen Abhängigkeitstiefen
  82   besitzen. Fehlt dieser Parameter, so wird der Wert 1000 benutzt.
  83
  84   Dies ist reine Kosmetik. Für echte Reihenfolgen muss "depends"
  85   benutzt werden. Lx-Office sortiert die auszuführenden Scripte zuerst
  86   nach der Abhängigkeitstiefe (wenn "z" von "y" abhängt und "y" von
  87   "x", so hat "z" eine Abhängigkeitstiefe von 2, "y" von 1 und "x" von
  88   0. "x" würde hier zuerst ausgeführt, dann "y", dann "z"), dann nach
  89   der Priorität und bei gleicher Priorität alphabetisch nach dem
  90   "tag".
  91
  92 Hilfsscript dbupgrade2_tool.pl
  93 ------------------------------
  94
  95 Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern, existiert
  96 ein Hilfsscript namens "scripts/dbupgrade2_tool.pl". Es muss aus dem
  97 Lx-Office-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
  98 liest alle Datenbankupgradescripte aus dem Verzeichnis sql/Pg-upgrade2
  99 aus. Es benutzt dafür die gleichen Methoden wie Lx-Office selber,
 100 sodass alle Fehlersituationen von der Kommandozeile überprüft werden
 101 können.
 102
 103 Wird dem Script kein weiterer Parameter übergeben, so wird nur eine
 104 Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann sich
 105 aber auch Informationen auf verschiedene Art ausgeben lassen:
 106
 107 1. Listenform: "./scripts/dbupgrade2_tool.pl --list"
 108
 109    Gibt eine Liste aller Scripte aus. Die Liste ist in der Reihenfolge
 110    sortiert, in der Lx-Office die Scripte ausführen würde. Es werden
 111    neben der Listenposition der Tag, die Abhängigkeitstiefe und die
 112    Priorität ausgegeben.
 113
 114 2. Baumform: "./scripts/dbupgrade2_tool.pl --tree"
 115
 116    Listet alle Tags in Baumform basierend auf den Abhängigkeiten
 117    auf. Die "Wurzelknoten" sind dabei die Scripte, von denen keine
 118    anderen abhängen. Die Unterknoten sind Scripte, die beim
 119    übergeordneten Script als Abhängigkeit eingetragen sind.
 120
 121 3. Umgekehrte Baumform: "./scripts/dbupgrade2_tool.pl --rtree"
 122
 123    Listet alle Tags in Baumform basierend auf den Abhängigkeiten auf.
 124    Die "Wurzelknoten" sind dabei die Scripte mit der geringsten
 125    Abhängigkeitstiefe. Die Unterknoten sind Scripte, die das
 126    übergeordnete Script als Abhängigkeit eingetragen haben.
 127
 128 4. Baumform mit Postscriptausgabe: "./scripts/dbupgrade2_tool.pl --graphviz"
 129
 130    Benötigt das Tool "graphviz", um mit seiner Hilfe die Baumform aus
 131    3. in eine Postscriptdatei namens "db_dependencies.ps"
 132    auszugeben. Dies ist vermutlich die übersichtlichste Form, weil
 133    hierbei jeder Knoten nur einmal ausgegeben wird. Bei den
 134    Textmodusbaumformen hingegen können Knoten und all ihre
 135    Abhängigkeiten mehrfach ausgegeben werden.
 136
 137 5. Scripte, von denen kein anderes Script abhängt:
 138    "./scripts/dbupgrade2_tool.pl --nodeps"
 139
 140    Listet die Tags aller Scripte auf, von denen keine anderen Scripte
 141    abhängen.
 142