7efff6e9fe4341a0fcca6d79f078a3f99bd55763
[kivitendo-erp.git] / ch04s03.html
1 <html><head>
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.3.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>&nbsp;</td><th width="60%" align="center">Kapitel 4. Entwicklerdokumentation</th><td width="20%" align="right">&nbsp;<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>Datenbankupgrades werden über einzelne Upgrade-Scripte gesteuert, die sich im Verzeichnis <code class="filename">sql/Pg-upgrade2</code>
4         befinden. In diesem Verzeichnis muss pro Datenbankupgrade eine Datei existieren, die neben den eigentlich auszuführenden SQL- oder
5         Perl-Befehlen einige Kontrollinformationen enthält.</p><p>Kontrollinformationen definieren Abhängigkeiten und Prioritäten, sodass Datenbankscripte zwar in einer sicheren Reihenfolge
6         ausgeführt werden (z.B. darf ein <code class="literal">ALTER TABLE</code> erst ausgeführt werden, wenn die Tabelle mit <code class="literal">CREATE
7         TABLE</code> angelegt wurde), diese Reihenfolge aber so flexibel ist, dass man keine Versionsnummern braucht.</p><p>kivitendo merkt sich dabei, welches der Upgradescripte in <code class="filename">sql/Pg-upgrade2</code> bereits durchgeführt wurde und
8         führt diese nicht erneut aus. Dazu dient die Tabelle "<code class="literal">schema_info</code>", die bei der Anmeldung automatisch angelegt
9         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
10         Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
11         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
12         entfernt.</p><p>Die folgenden Schlüsselworte werden verarbeitet:</p><div class="variablelist"><dl><dt><span class="term">
13                      <code class="varname">tag</code>
14                   </span></dt><dd><p>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
15               Dieser "tag" kann von anderen Kontrolldateien in ihren
16               Abhängigkeiten verwendet werden (Schlüsselwort
17               "<code class="varname">depends</code>"). Der "tag" ist auch der Name, der
18               in der Datenbank eingetragen wird.</p><p>Normalerweise sollte die Kontrolldatei genau so heißen wie
19               der "tag", nur mit der Endung ".sql" bzw. "pl".</p><p>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
20               Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
21               erlaubt und sollten stattdessen mit Unterstrichen ersetzt
22               werden.</p></dd><dt><span class="term">
23                      <code class="varname">charset</code>
24                   </span></dt><dd><p>Empfohlen. Gibt den Zeichensatz an, in dem das Script geschrieben wurde, z.B. "<code class="literal">UTF-8</code>". Aus
25               Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
26               "<code class="literal">ISO-8859-15</code>" angenommen. Perl-Upgradescripte hingegen müssen immer in UTF-8 encodiert sein und sollten
27               demnach auch ein "<code class="literal">use utf8;</code>" enthalten.</p></dd><dt><span class="term">
28                      <code class="varname">description</code>
29                   </span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
30               passiert. Diese wird dem Benutzer beim eigentlichen
31               Datenbankupdate angezeigt. Während der Tag in Englisch gehalten
32               sein sollte, sollte die Beschreibung auf Deutsch
33               erfolgen.</p></dd><dt><span class="term">
34                      <code class="varname">depends</code>
35                   </span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
36               von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
37               dass die in dieser Liste aufgeführten Scripte bereits
38               durchgeführt wurden, bevor dieses Script ausgeführt wird.</p><p>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
39               Script "b" existiert, das von Änderungen in "a" abhängt, und
40               eine neue Kontrolldatei für "c" erstellt wird, die von
41               Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
42               Tag "b" als Abhängigkeit zu definieren.</p><p>Es ist nicht erlaubt, sich selbst referenzierende
43               Abhängigkeiten zu definieren (z.B. "a" -&gt; "b", "b" -&gt; "c"
44               und "c" -&gt; "a").</p></dd><dt><span class="term">
45                      <code class="varname">priority</code>
46                   </span></dt><dd><p>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
47               der Scripte ausgeführt werden, die die gleichen
48               Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
49               der Wert 1000 benutzt.</p><p>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
50               "depends" benutzt werden. kivitendo sortiert die auszuführenden
51               Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
52               abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
53               2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
54               dann "y", dann "z"), dann nach der Priorität und bei gleicher
55               Priorität alphabetisch nach dem "tag".</p></dd><dt><span class="term">
56                      <code class="varname">ignore</code>
57                   </span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
58               Skript bei der Anmeldung ignoriert und entsprechend nicht
59               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
60        halten. Dafür bekommen sie aber auch einige Komfortfunktionen bereitgestellt.</p><p>Ein Upgradescript stellt dabei eine vollständige Objektklasse dar, die vom Elternobjekt
61        "<code class="literal">SL::DBUpgrade2::Base</code>" erben und eine Funktion namens "<code class="literal">run</code>" zur Verfügung stellen muss. Das
62        Script wird ausgeführt, indem eine Instanz dieser Klasse erzeugt und darauf die erwähnte "<code class="literal">run</code>" aufgerufen
63        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
64        Zeichen, die in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche ersetzt. Insgesamt sieht der Paketname wie folgt
65        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
66        "<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
67 # @description: Ein schönes Beispielscript
68 # @depends: release_3_1_0
69 package SL::DBUpgrade2::beispiel_upgrade_file42;
70
71 use strict;
72 use utf8;
73
74 use parent qw(SL::DBUpgrade2::Base);
75
76 sub run {
77   my ($self) = @_;
78
79   # hier Aktionen ausführen
80
81   return 1;
82 }
83
84 1;
85 </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,
86         existiert ein Hilfsscript namens
87         "<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
88         kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
89         liest alle Datenbankupgradescripte aus dem Verzeichnis
90         <code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
91         gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
92         von der Kommandozeile überprüft werden können.</p><p>Wird dem Script kein weiterer Parameter übergeben, so wird nur
93         eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
94         sich aber auch Informationen auf verschiedene Art ausgeben
95         lassen:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Listenform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
96             --list</strong></span>"</p><p>Gibt eine Liste aller Scripte aus. Die Liste ist in der
97             Reihenfolge sortiert, in der kivitendo die Scripte ausführen
98             würde. Es werden neben der Listenposition der Tag, die
99             Abhängigkeitstiefe und die Priorität ausgegeben.</p></li><li class="listitem"><p>Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
100             --tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
101             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
102             denen keine anderen abhängen. Die Unterknoten sind Scripte, die
103             beim übergeordneten Script als Abhängigkeit eingetragen
104             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
105             --rtree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
106             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
107             der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
108             die das übergeordnete Script als Abhängigkeit eingetragen
109             haben.</p></li><li class="listitem"><p>Baumform mit Postscriptausgabe:
110             "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
111             --graphviz</strong></span>"</p><p>Benötigt das Tool "<span class="command"><strong>graphviz</strong></span>", um mit
112             seiner Hilfe die <a class="link" href="ch04s03.html#db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
113             Baumform</a> in eine Postscriptdatei namens
114             "<code class="filename">db_dependencies.ps</code>" auszugeben. Dies ist
115             vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
116             nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
117             können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
118             werden.</p></li><li class="listitem"><p>Scripte, von denen kein anderes Script abhängt:
119             "<span class="command"><strong>./scripts/dbupgrade2_tool.pl --nodeps</strong></span>"</p><p>Listet die Tags aller Scripte auf, von denen keine anderen
120             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>&nbsp;</td><td width="20%" align="center"><a accesskey="u" href="ch04.html">Nach oben</a></td><td width="40%" align="right">&nbsp;<a accesskey="n" href="ch04s04.html">Weiter</a></td></tr><tr><td width="40%" align="left" valign="top">4.2. Entwicklung unter FastCGI&nbsp;</td><td width="20%" align="center"><a accesskey="h" href="index.html">Zum Anfang</a></td><td width="40%" align="right" valign="top">&nbsp;4.4. Translations and languages</td></tr></table></div></body></html>