Projekt

Allgemein

Profil

« Zurück | Weiter » 

Revision 42298d2c

Von Moritz Bunkus vor mehr als 5 Jahren hinzugefügt

  • ID 42298d2ceb5206a3d8df0a5cd9989eff5ebb843e
  • Vorgänger 60b17b30
  • Nachfolger 822f5cf7

Dokumentation: HTML & PDF gebaut

Unterschiede anzeigen:

doc/html/ch04s03.html
1 1 
<html><head>
2 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.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>&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
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.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
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.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
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.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,


  		




  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="ch04s03.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="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>


  		




  
  3
  
    
   <title>4.3. Programmatische API-Aufrufe</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. SQL-Upgradedateien"></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. Programmatische API-Aufrufe</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. Programmatische API-Aufrufe"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dev-programmatic-api-calls"></a>4.3. Programmatische API-Aufrufe</h2></div></div></div><div class="sect2" title="4.3.1. Einführung"><div class="titlepage"><div><div><h3 class="title"><a name="dev-programmatic-api-calls.introduction"></a>4.3.1. Einführung</h3></div></div></div><p>


  		




  
  4
  
    
         Es ist möglich, Funktionen in kivitendo programmatisch aus anderen Programmen aufzurufen. Dazu ist nötig, dass


  		




  
  5
  
    
         Authentifizierungsinformationen in jedem Aufruf mitgegeben werden. Dafür gibt es zwei Methoden: die HTTP-»Basic«-Authentifizierung


  		




  
  6
  
    
         oder die Übergabe als spziell benannte GET-Parameter. Neben den Authentifizierungsinformationen muss auch der zu verwendende Mandant


  		




  
  7
  
    
         übergeben werden.


  		




  
  8
  
    
        </p></div><div class="sect2" title="4.3.2. Wahl des Mandanten"><div class="titlepage"><div><div><h3 class="title"><a name="dev-programmatic-api-calls.client_selection"></a>4.3.2. Wahl des Mandanten</h3></div></div></div><p>


  		




  
  9
  
    
         Der zu verwendende Mandant kann als Parameter <code class="varname">{AUTH}client_id</code> mit jedem Request mitgeschickt werden. Der Wert


  		




  
  10
  
    
         muss dabei die Datenbank-ID des Mandanten sein. kivitendo prüft, ob der Account, der über die Authentifizierungsinformationen


  		




  
  11
  
    
         übergeben wurde, Zugriff auf den angegebenen Mandanten hat.


  		




  
  12
  
    
        </p><p>


  		




  
  13
  
    
         Wird in einem Request kein Mandant mitgegeben, so wird derjenige Mandant genommen, wer als Standardmandant markiert wurde. Gibt es


  		




  
  14
  
    
         keinen solchen, kommt es zu einer Fehlermeldung.


  		




  
  15
  
    
        </p></div><div class="sect2" title="4.3.3. HTTP-»Basic«-Authentifizierung"><div class="titlepage"><div><div><h3 class="title"><a name="dev-programmatic-api-calls.http_basic_authentication"></a>4.3.3. HTTP-»Basic«-Authentifizierung</h3></div></div></div><p>


  		




  
  16
  
    
         Für diese Methode muss jedem Request der bekannte HTTP-Header <code class="constant">Authorization</code> mitgeschickt werden (siehe <a class="ulink" href="https://tools.ietf.org/html/rfc7617" target="_top">RFC 7617</a>). Unterstützt wird ausschließlich die »Basic«-Methode. Loginname und


  		




  
  17
  
    
         Passwort werden bei dieser Methode durch einen Doppelpunkt getrennt und Base64-encodiert im genannten HTTP-Header übertragen.


  		




  
  18
  
    
        </p><p>


  		




  
  19
  
    
         Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei Benutzung über den Webbrowser, ob


  		




  
  20
  
    
         dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat.


  		




  
  21
  
    
        </p><p>


  		




  
  22
  
    
         Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt


  		




  
  23
  
    
         erfolgen.


  		




  
  24
  
    
        </p></div><div class="sect2" title="4.3.4. Authentifizierung mit Parametern"><div class="titlepage"><div><div><h3 class="title"><a name="dev-programmatic-api-calls.authentication_via_parameters"></a>4.3.4. Authentifizierung mit Parametern</h3></div></div></div><p>


  		




  
  25
  
    
         Für diese Methode müssen jedem Request zwei Parameter mitgegeben werden: <code class="varname">{AUTH}login</code> und


  		




  
  26
  
    
         <code class="varname">{AUTH}password</code>. Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei


  		




  
  27
  
    
         Benutzung über den Webbrowser, ob dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat.


  		




  
  28
  
    
        </p><p>


  		




  
  29
  
    
         Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschließlich über HTTPS verschlüsselt


  		




  
  30
  
    
         erfolgen.


  		




  
  31
  
    
        </p><div class="note" title="Anmerkung" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Note"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Anmerkung]" src="system/docbook-xsl/images/note.png"></td><th align="left">Anmerkung</th></tr><tr><td align="left" valign="top"><p>


  		




  
  32
  
    
          Die Verwendung dieser Methode ist veraltet. Statt dessen sollte die oben erwähnte HTTP-»Basic«-Authentifizierung verwendet werden.


  		




  
  33
  
    
         </p></td></tr></table></div></div><div class="sect2" title="4.3.5. Beispiele"><div class="titlepage"><div><div><h3 class="title"><a name="dev-programmatic-api-calls.examples"></a>4.3.5. Beispiele</h3></div></div></div><p>


  		




  
  34
  
    
         Das folgende Beispiel nutzt das Kommandozeilenprogramm »curl« und ruft die Funktion auf, die eine vorhandene Telefonnummer in den


  		




  
  35
  
    
         Ansprechpersonen sucht und dazu Informationen zurückliefert. Dabei wird die HTTP-»Basic«-Authentifizierung genutzt.


  		




  
  36
  
    
        </p><pre class="programlisting">$ curl --silent --user 'jdoe:SecretPassword!' \


  		




  
  37
  
    
  'https://…/controller.pl?action=PhoneNumber/look_up&amp;number=053147110815'</pre></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. SQL-Upgradedateien</td></tr></table></div></body></html>


  		












Auch abrufbar als:  Unified diff