projects / kivitendo-erp.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Passwörter: Unterstützung für crypt, MD5 und SHA-1 entfernt
[kivitendo-erp.git] / doc / html / ch04s03.html
diff --git a/doc/html/ch04s03.html b/doc/html/ch04s03.html
index cae5a7b..7efff6e 100644 (file)
--- a/doc/html/ch04s03.html
+++ b/doc/html/ch04s03.html
@@ -1,22 +1,12 @@
 <html><head>
       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
 <html><head>
       <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-   <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="Lx-Office: 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
-        Versionsnummer beruht und dann in sql/Pg-upgrade nach einem Script für
-        diese Versionsnummer sucht, schränkt sehr ein, z.B. was die parallele
-        Entwicklung im stable- und unstable-Baum betrifft.</p><p>Dieser Mechanismus wurde für Lx-Office 2.4.1 deutlich erweitert.
-        Es werden weiterhin alle Scripte aus sql/Pg-upgrade ausgeführt.
-        Zusätzlich gibt es aber ein zweites Verzeichnis, sql/Pg-upgrade2. 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>Neu sind die Kontrollinformationen, die Abhängigkeiten und
-        Prioritäten definieren können werden, sodass Datenbankscripte zwar in
-        einer sicheren Reihenfolge ausgeführt werden (z.B. darf ein "ALTER
-        TABLE" erst ausgeführt werden, wenn die Tabelle mit "CREATE TABLE"
-        angelegt wurde), diese Reihenfolge aber so flexibel ist, dass man
-        keine Versionsnummern mehr braucht.</p><p>Lx-Office merkt sich dabei, welches der Upgradescripte in
-        sql/Pg-upgrade2 bereits durchgeführt wurde und führt diese nicht
-        erneut aus. Dazu dient die Tabelle "schema_info", 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
+   <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>
+        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
         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">
         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">
@@ -31,20 +21,19 @@
               erlaubt und sollten stattdessen mit Unterstrichen ersetzt
               werden.</p></dd><dt><span class="term">
                      <code class="varname">charset</code>
               erlaubt und sollten stattdessen mit Unterstrichen ersetzt
               werden.</p></dd><dt><span class="term">
                      <code class="varname">charset</code>
-                  </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 der Zeichensatz
-              "<code class="literal">ISO-8859-15</code>" angenommen.</p></dd><dt><span class="term">
+                  </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">
                      <code class="varname">description</code>
                   </span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
               passiert. Diese wird dem Benutzer beim eigentlichen
                      <code class="varname">description</code>
                   </span></dt><dd><p>Benötigt. Eine Beschreibung, was in diesem Update
               passiert. Diese wird dem Benutzer beim eigentlichen
-              Datenbankupdate angezeigt. Während der Tag in englisch gehalten
+              Datenbankupdate angezeigt. Während der Tag in Englisch gehalten
               sein sollte, sollte die Beschreibung auf Deutsch
               erfolgen.</p></dd><dt><span class="term">
                      <code class="varname">depends</code>
                   </span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
               sein sollte, sollte die Beschreibung auf Deutsch
               erfolgen.</p></dd><dt><span class="term">
                      <code class="varname">depends</code>
                   </span></dt><dd><p>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
-              von denen dieses Upgradescript abhängt. Lx-Office stellt sicher,
+              von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
               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
               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
@@ -58,7 +47,7 @@
               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
               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
-              "depends" benutzt werden. Lx-Office sortiert die auszuführenden
+              "depends" benutzt werden. kivitendo sortiert die auszuführenden
               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,
               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,
@@ -67,19 +56,45 @@
                      <code class="varname">ignore</code>
                   </span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
               Skript bei der Anmeldung ignoriert und entsprechend nicht
                      <code class="varname">ignore</code>
                   </span></dt><dd><p>Optional. Falls der Wert auf 1 (true) steht, wird das
               Skript bei der Anmeldung ignoriert und entsprechend nicht
-              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,
+              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
+# @description: Ein schönes Beispielscript
+# @depends: release_3_1_0
+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,
         existiert ein Hilfsscript namens
         "<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
         existiert ein Hilfsscript namens
         "<code class="filename">scripts/dbupgrade2_tool.pl</code>". Es muss aus dem
-        Lx-Office-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
+        kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
         liest alle Datenbankupgradescripte aus dem Verzeichnis
         <code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
         liest alle Datenbankupgradescripte aus dem Verzeichnis
         <code class="filename">sql/Pg-upgrade2</code> aus. Es benutzt dafür die
-        gleichen Methoden wie Lx-Office selber, sodass alle Fehlersituationen
+        gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
         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
         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
         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
         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
-            Reihenfolge sortiert, in der Lx-Office die Scripte ausführen
+            Reihenfolge sortiert, in der kivitendo die Scripte ausführen
             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
             --tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
             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
             --tree</strong></span>"</p><p>Listet alle Tags in Baumform basierend auf den
Unnamed repository; edit this file 'description' to name the repository.