kivitendo/doc/sql-upgrade-dateien.txt @ cf90d5d9
| 4c24a5f4 | Sven Schöling | Neuer Mechanismus für SQL-Upgradedateien
|
||
| 4fd8bdbf | Moritz Bunkus | ----------------------------------------
|
||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| 4fd8bdbf | Moritz Bunkus | Entwicklung im stable- und unstable-Baum betrifft.
|
||
| 4c24a5f4 | Sven Schöling | Dieser Mechanismus wurde für Lx-Office 2.4.1 deutlich erweitert. Es
|
||
| 4fd8bdbf | Moritz Bunkus | werden weiterhin alle Scripte aus sql/Pg-upgrade
|
||
| 4c24a5f4 | Sven Schöling | ausgeführt. Zusätzlich gibt es aber ein zweites Verzeichnis,
|
||
| 4fd8bdbf | Moritz Bunkus | sql/Pg-upgrade2. In diesem Verzeichnis muss pro Datenbankupgrade eine
|
||
| 4c24a5f4 | Sven Schöling | Datei existieren, die neben den eigentlich auszuführenden SQL- oder
|
||
Perl-Befehlen einige Kontrollinformationen enthält.
|
||||
| 4fd8bdbf | Moritz Bunkus | |||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| 4fd8bdbf | Moritz Bunkus | wurde), diese Reihenfolge aber so flexibel ist, dass man keine
|
||
Versionsnummern mehr braucht.
|
||||
Lx-Office merkt sich dabei, welches der Upgradescripte in
|
||||
| 4c24a5f4 | Sven Schöling | sql/Pg-upgrade2 bereits durchgeführt wurde und führt diese nicht
|
||
| 4fd8bdbf | Moritz Bunkus | 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
|
||||
| 4c24a5f4 | Sven Schöling | Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
|
||
| 4fd8bdbf | Moritz Bunkus | hat dabei das folgende Format:
|
||
| 4c24a5f4 | Sven Schöling | Für SQL-Upgradedateien:
|
||
| 4fd8bdbf | Moritz Bunkus | |||
-- @key: value
|
||||
| 4c24a5f4 | Sven Schöling | Für Perl-Upgradedateien:
|
||
| 4fd8bdbf | Moritz Bunkus | |||
# @key: value
|
||||
| 798b650e | Sven Donath | Leerzeichen vor "value" werden entfernt.
|
||
| 4fd8bdbf | Moritz Bunkus | |||
| 4c24a5f4 | Sven Schöling | Die folgenden Schlüsselworte werden verarbeitet:
|
||
| 4fd8bdbf | Moritz Bunkus | |||
| 4c24a5f4 | Sven Schöling | * tag: Wird zwingend benötigt. Dies ist der "Name" des
|
||
| 4fd8bdbf | Moritz Bunkus | Upgrades. Dieser "tag" kann von anderen Kontrolldateien in ihren
|
||
| 4c24a5f4 | Sven Schöling | Abhängigkeiten verwendet werden (Schlüsselwort "depends"). Der "tag"
|
||
| 4fd8bdbf | Moritz Bunkus | ist auch der Name, der in der Datenbank eingetragen wird.
|
||
| 4c24a5f4 | Sven Schöling | Normalerweise sollte die Kontrolldatei genau so heißen wie der
|
||
| 4fd8bdbf | Moritz Bunkus | "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.
|
||||
| 4c24a5f4 | Sven Schöling | * description: Benötigt. Eine Beschreibung, was in diesem Update
|
||
| 4fd8bdbf | Moritz Bunkus | passiert. Diese wird dem Benutzer beim eigentlichen Datenbankupdate
|
||
| 4c24a5f4 | Sven Schöling | angezeigt. Während der Tag in englisch gehalten sein sollte, sollte
|
||
| 4fd8bdbf | Moritz Bunkus | die Beschreibung auf Deutsch erfolgen.
|
||
* depends: Optional. Eine mit Leerzeichen getrennte Liste von "tags",
|
||||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| 4fd8bdbf | Moritz Bunkus | zu definieren.
|
||
| 4c24a5f4 | Sven Schöling | Es ist nicht erlaubt, sich selbst referenzierende Abhängigkeiten zu
|
||
| 4fd8bdbf | Moritz Bunkus | definieren (z.B. "a" -> "b", "b" -> "c" und "c" -> "a").
|
||
* priority: Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
|
||||
| 4c24a5f4 | Sven Schöling | der Scripte ausgeführt werden, die die gleichen Abhängigkeitstiefen
|
||
| 4fd8bdbf | Moritz Bunkus | besitzen. Fehlt dieser Parameter, so wird der Wert 1000 benutzt.
|
||
| 4c24a5f4 | Sven Schöling | 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
|
||||
| 4fd8bdbf | Moritz Bunkus | "tag".
|
||
Hilfsscript dbupgrade2_tool.pl
|
||||
------------------------------
|
||||
| 4c24a5f4 | Sven Schöling | Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern, existiert
|
||
| 4fd8bdbf | Moritz Bunkus | 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
|
||||
| 4c24a5f4 | Sven Schöling | aus. Es benutzt dafür die gleichen Methoden wie Lx-Office selber,
|
||
sodass alle Fehlersituationen von der Kommandozeile überprüft werden
|
||||
können.
|
||||
| 4fd8bdbf | Moritz Bunkus | |||
| 4c24a5f4 | Sven Schöling | Wird dem Script kein weiterer Parameter übergeben, so wird nur eine
|
||
Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann sich
|
||||
| 4fd8bdbf | Moritz Bunkus | 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
|
||||
| 4c24a5f4 | Sven Schöling | 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.
|
||||
| 4fd8bdbf | Moritz Bunkus | |||
2. Baumform: "./scripts/dbupgrade2_tool.pl --tree"
|
||||
| 4c24a5f4 | Sven Schöling | Listet alle Tags in Baumform basierend auf den Abhängigkeiten
|
||
| 4fd8bdbf | Moritz Bunkus | auf. Die "Wurzelknoten" sind dabei die Scripte, von denen keine
|
||
| 4c24a5f4 | Sven Schöling | anderen abhängen. Die Unterknoten sind Scripte, die beim
|
||
übergeordneten Script als Abhängigkeit eingetragen sind.
|
||||
| 4fd8bdbf | Moritz Bunkus | |||
3. Umgekehrte Baumform: "./scripts/dbupgrade2_tool.pl --rtree"
|
||||
| 4c24a5f4 | Sven Schöling | Listet alle Tags in Baumform basierend auf den Abhängigkeiten auf.
|
||
| 4fd8bdbf | Moritz Bunkus | Die "Wurzelknoten" sind dabei die Scripte mit der geringsten
|
||
| 4c24a5f4 | Sven Schöling | Abhängigkeitstiefe. Die Unterknoten sind Scripte, die das
|
||
übergeordnete Script als Abhängigkeit eingetragen haben.
|
||||
| 4fd8bdbf | Moritz Bunkus | |||
4. Baumform mit Postscriptausgabe: "./scripts/dbupgrade2_tool.pl --graphviz"
|
||||
| 4c24a5f4 | Sven Schöling | Benötigt das Tool "graphviz", um mit seiner Hilfe die Baumform aus
|
||
| 4fd8bdbf | Moritz Bunkus | 3. in eine Postscriptdatei namens "db_dependencies.ps"
|
||
| 4c24a5f4 | Sven Schöling | auszugeben. Dies ist vermutlich die übersichtlichste Form, weil
|
||
| 4fd8bdbf | Moritz Bunkus | hierbei jeder Knoten nur einmal ausgegeben wird. Bei den
|
||
| 4c24a5f4 | Sven Schöling | Textmodusbaumformen hingegen können Knoten und all ihre
|
||
Abhängigkeiten mehrfach ausgegeben werden.
|
||||
| 4fd8bdbf | Moritz Bunkus | |||
| 4c24a5f4 | Sven Schöling | 5. Scripte, von denen kein anderes Script abhängt:
|
||
| 4fd8bdbf | Moritz Bunkus | "./scripts/dbupgrade2_tool.pl --nodeps"
|
||
Listet die Tags aller Scripte auf, von denen keine anderen Scripte
|
||||
| 4c24a5f4 | Sven Schöling | abhängen.
|