2 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
3 <title>4.3. SQL-Upgradedateien</title><link rel="stylesheet" type="text/css" href="style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1-RC2"><link rel="home" href="index.html" title="kivitendo 3.0.0: Installation, Konfiguration, Entwicklung"><link rel="up" href="ch04.html" title="Kapitel 4. Entwicklerdokumentation"><link rel="prev" href="ch04s02.html" title="4.2. Entwicklung unter FastCGI"><link rel="next" href="ch04s04.html" title="4.4. Translations and languages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4.3. SQL-Upgradedateien</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s02.html">Zurück</a> </td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right"> <a accesskey="n" href="ch04s04.html">Weiter</a></td></tr></table><hr></div><div class="sect1" title="4.3. SQL-Upgradedateien"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-upgrade-files"></a>4.3. SQL-Upgradedateien</h2></div></div></div><div class="sect2" title="4.3.1. Einführung"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.introduction"></a>4.3.1. Einführung</h3></div></div></div><p>Der alte Mechanismus für SQL-Upgradescripte, der auf einer
4 Versionsnummer beruht und dann in sql/Pg-upgrade nach einem Script für
5 diese Versionsnummer sucht, schränkt sehr ein, z.B. was die parallele
6 Entwicklung im stable- und unstable-Baum betrifft.</p><p>Dieser Mechanismus wurde für kivitendo 2.4.1 deutlich erweitert.
7 Es werden weiterhin alle Scripte aus sql/Pg-upgrade ausgeführt.
8 Zusätzlich gibt es aber ein zweites Verzeichnis, sql/Pg-upgrade2. In
9 diesem Verzeichnis muss pro Datenbankupgrade eine Datei existieren,
10 die neben den eigentlich auszuführenden SQL- oder Perl-Befehlen einige
11 Kontrollinformationen enthält.</p><p>Neu sind die Kontrollinformationen, die Abhängigkeiten und
12 Prioritäten definieren können werden, sodass Datenbankscripte zwar in
13 einer sicheren Reihenfolge ausgeführt werden (z.B. darf ein "ALTER
14 TABLE" erst ausgeführt werden, wenn die Tabelle mit "CREATE TABLE"
15 angelegt wurde), diese Reihenfolge aber so flexibel ist, dass man
16 keine Versionsnummern mehr braucht.</p><p>kivitendo merkt sich dabei, welches der Upgradescripte in
17 sql/Pg-upgrade2 bereits durchgeführt wurde und führt diese nicht
18 erneut aus. Dazu dient die Tabelle "schema_info", die bei der
19 Anmeldung automatisch angelegt wird.</p></div><div class="sect2" title="4.3.2. Format der Kontrollinformationen"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.format"></a>4.3.2. Format der Kontrollinformationen</h3></div></div></div><p>Die Kontrollinformationen sollten sich am Anfang der jeweiligen
20 Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
21 hat dabei das folgende Format:</p><p>Für SQL-Upgradedateien:</p><pre class="programlisting">-- @key: value</pre><p>Für Perl-Upgradedateien:</p><pre class="programlisting"># @key: value</pre><p>Leerzeichen vor "<code class="varname">value</code>" werden
22 entfernt.</p><p>Die folgenden Schlüsselworte werden verarbeitet:</p><div class="variablelist"><dl><dt><span class="term">
23 <code class="varname">tag</code>
24 </span></dt><dd><p>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
25 Dieser "tag" kann von anderen Kontrolldateien in ihren
26 Abhängigkeiten verwendet werden (Schlüsselwort
27 "<code class="varname">depends</code>"). Der "tag" ist auch der Name, der
28 in der Datenbank eingetragen wird.</p><p>Normalerweise sollte die Kontrolldatei genau so heißen wie
29 der "tag", nur mit der Endung ".sql" bzw. "pl".</p><p>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
30 Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
31 erlaubt und sollten stattdessen mit Unterstrichen ersetzt
32 werden.</p></dd><dt><span class="term">
33 <code class="varname">charset</code>
34 </span></dt><dd><p>Empfohlen. Gibt den Zeichensatz an, in dem das Script geschrieben wurde, z.B. "<code class="literal">UTF-8</code>". Aus
35 Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
36 "<code class="literal">ISO-8859-15</code>" angenommen. Perl-Upgradescripte hingegen müssen immer in UTF-8 encodiert sein und sollten
37 demnach auch ein "<code class="literal">use utf8;</code>" enthalten.</p></dd><dt><span class="term">
38 <code class="varname">description</code>
39 </span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
40 passiert. Diese wird dem Benutzer beim eigentlichen
41 Datenbankupdate angezeigt. Während der Tag in englisch gehalten
42 sein sollte, sollte die Beschreibung auf Deutsch
43 erfolgen.</p></dd><dt><span class="term">
44 <code class="varname">depends</code>
45 </span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
46 von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
47 dass die in dieser Liste aufgeführten Scripte bereits
48 durchgeführt wurden, bevor dieses Script ausgeführt wird.</p><p>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
49 Script "b" existiert, das von Änderungen in "a" abhängt, und
50 eine neue Kontrolldatei für "c" erstellt wird, die von
51 Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
52 Tag "b" als Abhängigkeit zu definieren.</p><p>Es ist nicht erlaubt, sich selbst referenzierende
53 Abhängigkeiten zu definieren (z.B. "a" -> "b", "b" -> "c"
54 und "c" -> "a").</p></dd><dt><span class="term">
55 <code class="varname">priority</code>
56 </span></dt><dd><p>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
57 der Scripte ausgeführt werden, die die gleichen
58 Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
59 der Wert 1000 benutzt.</p><p>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
60 "depends" benutzt werden. kivitendo sortiert die auszuführenden
61 Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
62 abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
63 2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
64 dann "y", dann "z"), dann nach der Priorität und bei gleicher
65 Priorität alphabetisch nach dem "tag".</p></dd><dt><span class="term">
66 <code class="varname">ignore</code>
67 </span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
68 Skript bei der Anmeldung ignoriert und entsprechend nicht
69 ausgeführt.</p></dd></dl></div></div><div class="sect2" title="4.3.3. Format von in Perl geschriebenen Datenbankupgradescripten"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.format-perl-files"></a>4.3.3. Format von in Perl geschriebenen Datenbankupgradescripten</h3></div></div></div><p>In Perl geschriebene Datenbankscripte werden nicht einfach so ausgeführt sondern müssen sich an gewisse Konventionen
70 halten. Dafür bekommen sie aber auch einige Komfortfunktionen bereitgestellt.</p><p>Ein Upgradescript stellt dabei eine vollständige Objektklasse dar, die vom Elternobjekt
71 "<code class="literal">SL::DBUpgrade2::Base</code>" erben und eine Funktion namens "<code class="literal">run</code>" zur Verfügung stellen muss. Das
72 Script wird ausgeführt, indem eine Instanz dieser Klasse erzeugt und darauf die erwähnte "<code class="literal">run</code>" aufgerufen
73 wird.</p><p>Zu beachten ist, dass sich der Paketname der Datei aus dem Wert für "<code class="literal">@tag</code>" ableitet. Dabei werden alle
74 Zeichen, die in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche ersetzt. Insgesamt sieht der Paketname wie folgt
75 aus: "<code class="literal">SL::DBUpgrade2::tag</code>".</p><p>Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit
76 "<span class="command"><strong>perldoc SL/DBUpgrade2/Base.pm</strong></span>".</p><p>Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie folgt aus:</p><pre class="programlisting"># @tag: beispiel-upgrade-file42
77 # @description: Ein schönes Beispielscript
78 # @depends: release_3_0_0
79 package SL::DBUpgrade2::beispiel_upgrade_file42;
84 use parent qw(SL::DBUpgrade2::Base);
89 # hier Aktionen ausführen
95 </pre></div><div class="sect2" title="4.3.4. Hilfsscript dbupgrade2_tool.pl"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.dbupgrade-tool"></a>4.3.4. Hilfsscript dbupgrade2_tool.pl</h3></div></div></div><p>Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
96 existiert ein Hilfsscript namens
97 "<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
98 kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
99 liest alle Datenbankupgradescripte aus dem Verzeichnis
100 <code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
101 gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
102 von der Kommandozeile überprüft werden können.</p><p>Wird dem Script kein weiterer Parameter übergeben, so wird nur
103 eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
104 sich aber auch Informationen auf verschiedene Art ausgeben
105 lassen:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Listenform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
106 --list</strong></span>"</p><p>Gibt eine Liste aller Scripte aus. Die Liste ist in der
107 Reihenfolge sortiert, in der kivitendo die Scripte ausführen
108 würde. Es werden neben der Listenposition der Tag, die
109 Abhängigkeitstiefe und die Priorität ausgegeben.</p></li><li class="listitem"><p>Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
110 --tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
111 Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
112 denen keine anderen abhängen. Die Unterknoten sind Scripte, die
113 beim übergeordneten Script als Abhängigkeit eingetragen
114 sind.</p></li><li class="listitem"><p><a name="db-upgrade-files.dbupgrade-tool.reverse-tree"></a>Umgekehrte Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
115 --rtree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
116 Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
117 der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
118 die das übergeordnete Script als Abhängigkeit eingetragen
119 haben.</p></li><li class="listitem"><p>Baumform mit Postscriptausgabe:
120 "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
121 --graphviz</strong></span>"</p><p>Benötigt das Tool "<span class="command"><strong>graphviz</strong></span>", um mit
122 seiner Hilfe die <a class="link" href="ch04s03.html#db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
123 Baumform</a> in eine Postscriptdatei namens
124 "<code class="filename">db_dependencies.ps</code>" auszugeben. Dies ist
125 vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
126 nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
127 können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
128 werden.</p></li><li class="listitem"><p>Scripte, von denen kein anderes Script abhängt:
129 "<span class="command"><strong>./scripts/dbupgrade2_tool.pl --nodeps</strong></span>"</p><p>Listet die Tags aller Scripte auf, von denen keine anderen
130 Scripte abhängen.</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s02.html">Zurück</a> </td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s04.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.2. Entwicklung unter FastCGI </td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top"> 4.4. Translations and languages</td></tr></table></div></body></html>