Datenbankupgrades werden über einzelne Upgrade-Scripte gesteuert, die sich im Verzeichnis sql/Pg-upgrade2
- befinden. In diesem Verzeichnis muss pro Datenbankupgrade eine Datei existieren, die neben den eigentlich auszuführenden SQL- oder
- Perl-Befehlen einige Kontrollinformationen enthält.
Kontrollinformationen definieren Abhängigkeiten und Prioritäten, 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 braucht.
kivitendo 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.
4.3.2. Format der Kontrollinformationen
Die Kontrollinformationen sollten sich am Anfang der jeweiligen
- Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
- hat dabei das folgende Format:
Für SQL-Upgradedateien:
-- @key: value
Für Perl-Upgradedateien:
# @key: value
Leerzeichen vor "value" werden
- entfernt.
Die folgenden Schlüsselworte werden verarbeitet:
-
-
tag
- Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
- Dieser "tag" kann von anderen Kontrolldateien in ihren
- Abhängigkeiten verwendet werden (Schlüsselwort
- "depends"). Der "tag" ist auch der Name, der
- in der Datenbank eingetragen wird.
Normalerweise sollte die Kontrolldatei genau so heiÃen wie
- der "tag", nur mit der Endung ".sql" bzw. "pl".
Ein Tag darf nur aus alphanumerischen Zeichen sowie den
- Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
- erlaubt und sollten stattdessen mit Unterstrichen ersetzt
- werden.
-
-
charset
- Empfohlen. Gibt den Zeichensatz an, in dem das Script geschrieben wurde, z.B. "UTF-8". Aus
- Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
- "ISO-8859-15" angenommen. Perl-Upgradescripte hingegen müssen immer in UTF-8 encodiert sein und sollten
- demnach auch ein "use utf8;" enthalten.
-
-
description
- Benötigt. Eine Beschreibung, was in diesem Update
- passiert. Diese wird dem Benutzer beim eigentlichen
- Datenbankupdate angezeigt. Während der Tag in Englisch gehalten
- sein sollte, sollte die Beschreibung auf Deutsch
- erfolgen.
-
-
depends
- Optional. Eine mit Leerzeichen getrennte Liste von "tags",
- 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.
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.
Es ist nicht erlaubt, sich selbst referenzierende
- Abhängigkeiten zu definieren (z.B. "a" -> "b", "b" -> "c"
- und "c" -> "a").
-
-
priority
- Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
- der Scripte ausgeführt werden, die die gleichen
- Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
- der Wert 1000 benutzt.
Dies ist reine Kosmetik. Für echte Reihenfolgen muss
- "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,
- dann "y", dann "z"), dann nach der Priorität und bei gleicher
- Priorität alphabetisch nach dem "tag".
-
-
ignore
- Optional. Falls der Wert auf 1 (true) steht, wird das
- Skript bei der Anmeldung ignoriert und entsprechend nicht
- ausgeführt.
4.3.3. Format von in Perl geschriebenen Datenbankupgradescripten
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.
Ein Upgradescript stellt dabei eine vollständige Objektklasse dar, die vom Elternobjekt
- "SL::DBUpgrade2::Base" erben und eine Funktion namens "run" zur Verfügung stellen muss. Das
- Script wird ausgeführt, indem eine Instanz dieser Klasse erzeugt und darauf die erwähnte "run" aufgerufen
- wird.
Zu beachten ist, dass sich der Paketname der Datei aus dem Wert für "@tag" ableitet. Dabei werden alle
- Zeichen, die in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche ersetzt. Insgesamt sieht der Paketname wie folgt
- aus: "SL::DBUpgrade2::tag".
Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit
- "perldoc SL/DBUpgrade2/Base.pm".
Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie folgt aus:
# @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;
-4.3.4. Hilfsscript dbupgrade2_tool.pl
Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
- existiert ein Hilfsscript namens
- "scripts/dbupgrade2_tool.pl". Es muss aus dem
- kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
- liest alle Datenbankupgradescripte aus dem Verzeichnis
- sql/Pg-upgrade2 aus. Es benutzt dafür die
- gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
- von der Kommandozeile überprüft werden können.
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:
Listenform: "./scripts/dbupgrade2_tool.pl
- --list"
Gibt eine Liste aller Scripte aus. Die Liste ist in der
- 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.
Baumform: "./scripts/dbupgrade2_tool.pl
- --tree"
Listet alle Tags in Baumform basierend auf den
- 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
- sind.
Umgekehrte Baumform: "./scripts/dbupgrade2_tool.pl
- --rtree"
Listet alle Tags in Baumform basierend auf den
- 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
- haben.
Baumform mit Postscriptausgabe:
- "./scripts/dbupgrade2_tool.pl
- --graphviz"
Benötigt das Tool "graphviz", um mit
- seiner Hilfe die umgekehrte
- Baumform in eine Postscriptdatei namens
- "db_dependencies.ps" auszugeben. Dies ist
- vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
- nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
- können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
- werden.
Scripte, von denen kein anderes Script abhängt:
- "./scripts/dbupgrade2_tool.pl --nodeps"
Listet die Tags aller Scripte auf, von denen keine anderen
- Scripte abhängen.
4.3. Programmatische API-Aufrufe
+ Es ist möglich, Funktionen in kivitendo programmatisch aus anderen Programmen aufzurufen. Dazu ist nötig, dass
+ Authentifizierungsinformationen in jedem Aufruf mitgegeben werden. Dafür gibt es zwei Methoden: die HTTP-»Basic«-Authentifizierung
+ oder die Ãbergabe als spziell benannte GET-Parameter. Neben den Authentifizierungsinformationen muss auch der zu verwendende Mandant
+ übergeben werden.
+
4.3.2. Wahl des Mandanten
+ Der zu verwendende Mandant kann als Parameter {AUTH}client_id mit jedem Request mitgeschickt werden. Der Wert
+ muss dabei die Datenbank-ID des Mandanten sein. kivitendo prüft, ob der Account, der über die Authentifizierungsinformationen
+ übergeben wurde, Zugriff auf den angegebenen Mandanten hat.
+
+ Wird in einem Request kein Mandant mitgegeben, so wird derjenige Mandant genommen, wer als Standardmandant markiert wurde. Gibt es
+ keinen solchen, kommt es zu einer Fehlermeldung.
+
4.3.3. HTTP-»Basic«-Authentifizierung
+ Für diese Methode muss jedem Request der bekannte HTTP-Header Authorization mitgeschickt werden (siehe RFC 7617). Unterstützt wird ausschlieÃlich die »Basic«-Methode. Loginname und
+ Passwort werden bei dieser Methode durch einen Doppelpunkt getrennt und Base64-encodiert im genannten HTTP-Header übertragen.
+
+ Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei Benutzung über den Webbrowser, ob
+ dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat.
+
+ Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschlieÃlich über HTTPS verschlüsselt
+ erfolgen.
+
4.3.4. Authentifizierung mit Parametern
+ Für diese Methode müssen jedem Request zwei Parameter mitgegeben werden: {AUTH}login und
+ {AUTH}password. Diese Informationen müssen einen vorhandenen Account benennen. kivitendo prüft genau wie bei
+ Benutzung über den Webbrowser, ob dieser Account Zugriff auf den Mandanten sowie auf die angeforderte Funktion hat.
+
+ Da die Logininformationen im Klartext im Request stehen, sollte der Zugriff auf kivitendo ausschlieÃlich über HTTPS verschlüsselt
+ erfolgen.
+
![[Anmerkung]](system/docbook-xsl/images/note.png) | Anmerkung |
|---|
+ Die Verwendung dieser Methode ist veraltet. Statt dessen sollte die oben erwähnte HTTP-»Basic«-Authentifizierung verwendet werden.
+ |
+ Das folgende Beispiel nutzt das Kommandozeilenprogramm »curl« und ruft die Funktion auf, die eine vorhandene Telefonnummer in den
+ Ansprechpersonen sucht und dazu Informationen zurückliefert. Dabei wird die HTTP-»Basic«-Authentifizierung genutzt.
+
$ curl --silent --user 'jdoe:SecretPassword!' \
+ 'https://â¦/controller.pl?action=PhoneNumber/look_up&number=053147110815'