X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;ds=sidebyside;f=doc%2Fhtml%2Fch04s03.html;h=bef5e5ded26bc62eddefe1540259efe01d37f3b9;hb=2f4fdf754423ff264d4570c1f396456f7f7ea90c;hp=41d3b50b1dbee3532d100b2be70307e4e745336d;hpb=f8309cb7bc2507c19e17ec59c6c66dd7f49ea351;p=kivitendo-erp.git diff --git a/doc/html/ch04s03.html b/doc/html/ch04s03.html index 41d3b50b1..bef5e5ded 100644 --- a/doc/html/ch04s03.html +++ b/doc/html/ch04s03.html @@ -1,96 +1,120 @@
- -- 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. -
- 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. -
- 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. -
- 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. -
- 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: -
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.
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. -
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 der Zeichensatz "ISO-8859-15
"
- angenommen.
-
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. -
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. Lx-Office 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"). -
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. Lx-Office 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". -
- Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern, existiert ein Hilfsscript namens
- "scripts/dbupgrade2_tool.pl
". Es muss aus dem Lx-Office-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 Lx-Office 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 Lx-Office 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. -
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.
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_0_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; +
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.