kivitendo/doc/html/ch04s03.html @ 60b17b30
| f8309cb7 | Moritz Bunkus | <html><head>
|
||
| 06cb6b12 | Moritz Bunkus | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
|
||
| 25fc5ea4 | Jan Büren | <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.5.3: 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>Datenbankupgrades werden über einzelne Upgrade-Scripte
|
||
| 0e14ae06 | Andreas Zenklusen | gesteuert, die sich im Verzeichnis
|
||
<code class="filename">sql/Pg-upgrade2</code> befinden. In diesem Verzeichnis
|
||||
muss pro Datenbankupgrade eine Datei existieren, die neben den
|
||||
eigentlich auszuführenden SQL- oder Perl-Befehlen einige
|
||||
Kontrollinformationen enthält.</p><p>Kontrollinformationen definieren Abhängigkeiten und Prioritäten,
|
||||
sodass Datenbankscripte zwar in einer sicheren Reihenfolge 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 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
|
||||
führt diese nicht erneut aus. Dazu dient die Tabelle
|
||||
"<code class="literal">schema_info</code>", die bei der 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
|
||||
| 06cb6b12 | Moritz Bunkus | Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
|
||
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
|
||||
entfernt.</p><p>Die folgenden Schlüsselworte werden verarbeitet:</p><div class="variablelist"><dl><dt><span class="term">
|
||||
| f8309cb7 | Moritz Bunkus | <code class="varname">tag</code>
|
||
| 06cb6b12 | Moritz Bunkus | </span></dt><dd><p>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
|
||
| 3adb0cb7 | Moritz Bunkus | Dieser "tag" kann von anderen Kontrolldateien in ihren
|
||
| 06cb6b12 | Moritz Bunkus | Abhängigkeiten verwendet werden (Schlüsselwort
|
||
| 3adb0cb7 | Moritz Bunkus | "<code class="varname">depends</code>"). Der "tag" ist auch der Name, der
|
||
| 06cb6b12 | Moritz Bunkus | in der Datenbank eingetragen wird.</p><p>Normalerweise sollte die Kontrolldatei genau so heißen wie
|
||
| 3adb0cb7 | Moritz Bunkus | der "tag", nur mit der Endung ".sql" bzw. "pl".</p><p>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
|
||
Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
|
||||
erlaubt und sollten stattdessen mit Unterstrichen ersetzt
|
||||
werden.</p></dd><dt><span class="term">
|
||||
| f8309cb7 | Moritz Bunkus | <code class="varname">charset</code>
|
||
| 0e14ae06 | Andreas Zenklusen | </span></dt><dd><p>Empfohlen. Gibt den Zeichensatz an, in dem das Script
|
||
geschrieben wurde, z.B. "<code class="literal">UTF-8</code>". Aus
|
||||
Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei
|
||||
Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
|
||||
"<code class="literal">ISO-8859-15</code>" angenommen. Perl-Upgradescripte
|
||||
hingegen müssen immer in UTF-8 encodiert sein und sollten
|
||||
demnach auch ein "<code class="literal">use utf8;</code>"
|
||||
enthalten.</p></dd><dt><span class="term">
|
||||
| f8309cb7 | Moritz Bunkus | <code class="varname">description</code>
|
||
| 06cb6b12 | Moritz Bunkus | </span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
|
||
| 3adb0cb7 | Moritz Bunkus | passiert. Diese wird dem Benutzer beim eigentlichen
|
||
| 8aecfa7c | Geoffrey Richardson | Datenbankupdate angezeigt. Während der Tag in Englisch gehalten
|
||
| 3adb0cb7 | Moritz Bunkus | sein sollte, sollte die Beschreibung auf Deutsch
|
||
erfolgen.</p></dd><dt><span class="term">
|
||||
| f8309cb7 | Moritz Bunkus | <code class="varname">depends</code>
|
||
| 3adb0cb7 | Moritz Bunkus | </span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
|
||
| 5fa26f9a | Moritz Bunkus | von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
|
||
| 06cb6b12 | Moritz Bunkus | dass die in dieser Liste aufgeführten Scripte bereits
|
||
durchgeführt wurden, bevor dieses Script ausgeführt wird.</p><p>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 zu definieren.</p><p>Es ist nicht erlaubt, sich selbst referenzierende
|
||||
Abhängigkeiten zu definieren (z.B. "a" -> "b", "b" -> "c"
|
||||
| 3adb0cb7 | Moritz Bunkus | und "c" -> "a").</p></dd><dt><span class="term">
|
||
| f8309cb7 | Moritz Bunkus | <code class="varname">priority</code>
|
||
| 3adb0cb7 | Moritz Bunkus | </span></dt><dd><p>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
|
||
| 06cb6b12 | Moritz Bunkus | der Scripte ausgeführt werden, die die gleichen
|
||
Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
|
||||
der Wert 1000 benutzt.</p><p>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
|
||||
| 5fa26f9a | Moritz Bunkus | "depends" benutzt werden. kivitendo sortiert die auszuführenden
|
||
| 06cb6b12 | Moritz Bunkus | 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 "tag".</p></dd><dt><span class="term">
|
||||
| 0f1fb486 | Jan Büren | <code class="varname">ignore</code>
|
||
| 3adb0cb7 | Moritz Bunkus | </span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
|
||
Skript bei der Anmeldung ignoriert und entsprechend nicht
|
||||
| 0e14ae06 | Andreas Zenklusen | 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 halten. Dafür
|
||||
bekommen sie aber auch einige Komfortfunktionen bereitgestellt.</p><p>Ein Upgradescript stellt dabei eine vollständige Objektklasse
|
||||
dar, die vom Elternobjekt "<code class="literal">SL::DBUpgrade2::Base</code>"
|
||||
erben und eine Funktion namens "<code class="literal">run</code>" zur Verfügung
|
||||
stellen muss. Das Script wird ausgeführt, indem eine Instanz dieser
|
||||
Klasse erzeugt und darauf die erwähnte "<code class="literal">run</code>"
|
||||
aufgerufen 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 Zeichen, die
|
||||
in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche
|
||||
ersetzt. Insgesamt sieht der Paketname wie folgt 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
|
||||
"<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
|
||||
| f1a40f51 | Moritz Bunkus | # @description: Ein schönes Beispielscript
|
||
| fa324fa5 | Jan Büren | # @depends: release_3_1_0
|
||
| f1a40f51 | Moritz Bunkus | package SL::DBUpgrade2::beispiel_upgrade_file42;
|
||
use strict;
|
||||
use utf8;
|
||||
use parent qw(SL::DBUpgrade2::Base);
|
||||
sub run {
|
||||
my ($self) = @_;
|
||||
# hier Aktionen ausführen
|
||||
return 1;
|
||||
}
|
||||
1;
|
||||
</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,
|
||||
| 3adb0cb7 | Moritz Bunkus | existiert ein Hilfsscript namens
|
||
"<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
|
||||
| 5fa26f9a | Moritz Bunkus | kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
|
||
| 3adb0cb7 | Moritz Bunkus | liest alle Datenbankupgradescripte aus dem Verzeichnis
|
||
| 06cb6b12 | Moritz Bunkus | <code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
|
||
| 5fa26f9a | Moritz Bunkus | gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
|
||
| 06cb6b12 | Moritz Bunkus | von der Kommandozeile überprüft werden können.</p><p>Wird dem Script kein weiterer Parameter übergeben, so wird nur
|
||
eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
|
||||
| 3adb0cb7 | Moritz Bunkus | sich aber auch Informationen auf verschiedene Art ausgeben
|
||
lassen:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Listenform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
|
||||
--list</strong></span>"</p><p>Gibt eine Liste aller Scripte aus. Die Liste ist in der
|
||||
| 5fa26f9a | Moritz Bunkus | Reihenfolge sortiert, in der kivitendo die Scripte ausführen
|
||
| 06cb6b12 | Moritz Bunkus | würde. Es werden neben der Listenposition der Tag, die
|
||
Abhängigkeitstiefe und die Priorität ausgegeben.</p></li><li class="listitem"><p>Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
|
||||
| 3adb0cb7 | Moritz Bunkus | --tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
|
||
| 06cb6b12 | Moritz Bunkus | Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
|
||
denen keine anderen abhängen. Die Unterknoten sind Scripte, die
|
||||
beim übergeordneten Script als Abhängigkeit eingetragen
|
||||
| 3adb0cb7 | Moritz Bunkus | 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
|
||
--rtree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
|
||||
| 06cb6b12 | Moritz Bunkus | Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
|
||
der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
|
||||
die das übergeordnete Script als Abhängigkeit eingetragen
|
||||
| 3adb0cb7 | Moritz Bunkus | haben.</p></li><li class="listitem"><p>Baumform mit Postscriptausgabe:
|
||
"<span class="command"><strong>./scripts/dbupgrade2_tool.pl
|
||||
| 06cb6b12 | Moritz Bunkus | --graphviz</strong></span>"</p><p>Benötigt das Tool "<span class="command"><strong>graphviz</strong></span>", um mit
|
||
| 3adb0cb7 | Moritz Bunkus | seiner Hilfe die <a class="link" href="ch04s03.html#db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
|
||
Baumform</a> in eine Postscriptdatei namens
|
||||
"<code class="filename">db_dependencies.ps</code>" auszugeben. Dies ist
|
||||
| 06cb6b12 | Moritz Bunkus | vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
|
||
| 3adb0cb7 | Moritz Bunkus | nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
|
||
| 06cb6b12 | Moritz Bunkus | können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
|
||
werden.</p></li><li class="listitem"><p>Scripte, von denen kein anderes Script abhängt:
|
||||
| 3adb0cb7 | Moritz Bunkus | "<span class="command"><strong>./scripts/dbupgrade2_tool.pl --nodeps</strong></span>"</p><p>Listet die Tags aller Scripte auf, von denen keine anderen
|
||
| 06cb6b12 | Moritz Bunkus | 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>
|