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:

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;

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: