CSV-Import: Groß-/Kleinschreibung bei Spaltennamen ignorieren
[kivitendo-erp.git] / 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