doc/html/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.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>&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>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
  35               geschrieben wurde, z.B. "<code class="literal">UTF-8</code>". Aus
  36               Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei
  37               Abwesenheit des Tags der Zeichensatz
  38               "<code class="literal">ISO-8859-15</code>" angenommen.</p></dd><dt><span class="term">
  39                      <code class="varname">description</code>
  40                   </span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
  41               passiert. Diese wird dem Benutzer beim eigentlichen
  42               Datenbankupdate angezeigt. Während der Tag in englisch gehalten
  43               sein sollte, sollte die Beschreibung auf Deutsch
  44               erfolgen.</p></dd><dt><span class="term">
  45                      <code class="varname">depends</code>
  46                   </span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
  47               von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
  48               dass die in dieser Liste aufgeführten Scripte bereits
  49               durchgeführt wurden, bevor dieses Script ausgeführt wird.</p><p>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
  50               Script "b" existiert, das von Änderungen in "a" abhängt, und
  51               eine neue Kontrolldatei für "c" erstellt wird, die von
  52               Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
  53               Tag "b" als Abhängigkeit zu definieren.</p><p>Es ist nicht erlaubt, sich selbst referenzierende
  54               Abhängigkeiten zu definieren (z.B. "a" -&gt; "b", "b" -&gt; "c"
  55               und "c" -&gt; "a").</p></dd><dt><span class="term">
  56                      <code class="varname">priority</code>
  57                   </span></dt><dd><p>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
  58               der Scripte ausgeführt werden, die die gleichen
  59               Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
  60               der Wert 1000 benutzt.</p><p>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
  61               "depends" benutzt werden. kivitendo sortiert die auszuführenden
  62               Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
  63               abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
  64               2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
  65               dann "y", dann "z"), dann nach der Priorität und bei gleicher
  66               Priorität alphabetisch nach dem "tag".</p></dd><dt><span class="term">
  67                      <code class="varname">ignore</code>
  68                   </span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
  69               Skript bei der Anmeldung ignoriert und entsprechend nicht
  70               ausgeführt.</p></dd></dl></div></div><div class="sect2" title="4.3.3. Hilfsscript dbupgrade2_tool.pl"><div class="titlepage"><div><div><h3 class="title"><a name="db-upgrade-files.dbupgrade-tool"></a>4.3.3. Hilfsscript dbupgrade2_tool.pl</h3></div></div></div><p>Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
  71         existiert ein Hilfsscript namens
  72         "<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
  73         kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
  74         liest alle Datenbankupgradescripte aus dem Verzeichnis
  75         <code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
  76         gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
  77         von der Kommandozeile überprüft werden können.</p><p>Wird dem Script kein weiterer Parameter übergeben, so wird nur
  78         eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
  79         sich aber auch Informationen auf verschiedene Art ausgeben
  80         lassen:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Listenform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
  81             --list</strong></span>"</p><p>Gibt eine Liste aller Scripte aus. Die Liste ist in der
  82             Reihenfolge sortiert, in der kivitendo die Scripte ausführen
  83             würde. Es werden neben der Listenposition der Tag, die
  84             Abhängigkeitstiefe und die Priorität ausgegeben.</p></li><li class="listitem"><p>Baumform: "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
  85             --tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
  86             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
  87             denen keine anderen abhängen. Die Unterknoten sind Scripte, die
  88             beim übergeordneten Script als Abhängigkeit eingetragen
  89             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
  90             --rtree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
  91             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
  92             der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
  93             die das übergeordnete Script als Abhängigkeit eingetragen
  94             haben.</p></li><li class="listitem"><p>Baumform mit Postscriptausgabe:
  95             "<span class="command"><strong>./scripts/dbupgrade2_tool.pl
  96             --graphviz</strong></span>"</p><p>Benötigt das Tool "<span class="command"><strong>graphviz</strong></span>", um mit
  97             seiner Hilfe die <a class="link" href="ch04s03.html#db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
  98             Baumform</a> in eine Postscriptdatei namens
  99             "<code class="filename">db_dependencies.ps</code>" auszugeben. Dies ist
 100             vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
 101             nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
 102             können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
 103             werden.</p></li><li class="listitem"><p>Scripte, von denen kein anderes Script abhängt:
 104             "<span class="command"><strong>./scripts/dbupgrade2_tool.pl --nodeps</strong></span>"</p><p>Listet die Tags aller Scripte auf, von denen keine anderen
 105             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>