doc/html/ch04s04.html

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