Entwicklung/Datenbankversionierung

Änderungen am Datenbankinhalt werden von den Entwicklern an vier Stellen eingepflegt:

• statische Daten in htdocs/doc/sql/static-data/data.sql
• stored procs & trigger in htdocs/doc/sql/stored-proc/maintain.php
• Änderungen an Tabellenstrukturen und Indizes in bin/dbsv-update.php
• Änderungen an der OKAPI-Datenbank in htdocs/okapi/views/update.php.

Das Script bin/dbupdate.php spielt alle diese Dinge in eine OC-Installation – z.B. ein Entwicklersystem – ein, bringt die Datenbank also auf den aktuellen Stand.

Der OKAPI-Code funktioniert nicht besonders gut, wenn man ihn von der Kommandozeile aus verwendet. Falls das OKAPI-Datenbankupdate einen Fehler produzieren sollte, muss man es anschließend von Hand via http://.../okapi/update aufrufen.

Versionierung der Datenbankstruktur

dbsv-update.php beinhaltet eine Versionierung der Datenbankstruktur.

In der Tabelle 'sysconfig' einer OC-Installation gibt es (ab Datenbankstand April 2013 bzw. Codestand a654761 vom 22. April) den Eintrag 'db_version' mit dem aktuellen Versionsstand der Datenbank, fortlaufend durchnumeriert ab 100. Für jede neue Version gibt es eine "Mutationsfunktion" in dbsv-update.php, die die Datenbank auf den neuen Versionsstand bringt.

Wenn du eine Änderung an einer Datenbanktabelle vornehmen (oder eine neue einfügen) möchtest, vergewissere dich zuerst sorgfältig, welche Folgen dies hat. Neue Informationen zu Caches und Logs müssen an vielen Stellen berücksichtigt werden, inklusive XML-Schnittstelle, OKAPI, evtl. auch Ocprop etc. Evtl. müssen Änderungen auch in vorhandene Trigger eingebaut werden oder benötigen neue Trigger, um Kosistenz zu gewährleisten (vgl. modification-dates.txt). Evtl. müssen Indizes geändert oder neu definiert werden, um die nötige Performance sicherzustellen.

Wenn du sicher bist, die Datenbank ändern zu wollen, ändere sie NICHT direkt, sondern schreibe eine neue Mutationsfunktion in dbsv-update.php, die die Änderung vornimmt. Vorhandene Funktionen können als Vorlage dienen. Teste deine Funktion anschließend mit "php dbsv-update.php" auf der Kommandozeile. Wenn es nicht wie beabsichtigt funktionierte, mache die Änderung rückgängig und setze sysconfig.db_version eins zurück, bevor du es wieder versuchst.

Wenn mehrere Entwickler gleichzeitig neue Mutationen definieren, ist es Aufgabe des Code-Maintainers, diese in passender Reihenfolge zusammenzuführen.

Felder oder Tabellen löschen oder umbenennen

Nicht mehr vorhandene Felder oder Tabellen sind inkompatibel zu älteren Versionsständen. Man kann dann auf einem Entwicklersystem nicht mehr testweise auf eine alte Codeversion zurückgehen, was sehr hilfreich ist um herauszufinden, wann ein Bug entstanden ist. Auch das Umschalten zwischen verschiedenen aktiven Branches kann schon zum Problem werden.

(Es gibt natürlich nie eine Garantie dass ein Downgrade 100%ig funktioniert, weil sich auch Datenbankinhalte in inkompatibler Weise geändert haben können. Im Großen und Ganzen funktioniert es aber.)

Umbenennung oder Löschungen sind daher nicht zu empfehlen. Nicht mehr verwendete Felder und Tabellen werden stattdessen mit dem Kommentar "obsolete" versehen.

Trigger & Stored Procedures

Um das Versionierungskonzept vollständig durchzuhalten, müssten eigentlich auch alle Änderungen an Triggern und Stored Procedures über die Mutationen erfolgen. Es bestünde dann allerdings die Gefahr von Inkonsistenzen zwischen den Mutationen den kompletten Funktionsdefinitionen in maintain.php, die der Übersicht halber weiter benötigt werden.

Solange es kein besseres Konzept gibt, wird daher wie folgt vorgegangen:

• Wenn eine Mutation geänderte/neue Trigger benötigt, die mit dem gleichen Codeupdate eingeführt werden, muss sie diese entweder zunächst definieren oder deren Funktionalität nachbilden (siehe z.B. Version 102: hier wird der neue sp_updateall_hiddenstat()-Code ausgeführt). Dies ist nötig, weil maintain.php erst nach den Mutationen durchläuft, da es neue Datenbankfelder benötigen kann (Henne-Ei-Problem).

• Bei Definition der Mutationen darauf achten, ob sie irgendwelchen SQL-Code enthalten der auf Trigger angewiesen ist. Wenn ja, entsprechende Maßnahmen ergreifen z.B.
  • Diese Trigger in der Mutation neu anlegen, oder
  • die Funktionalität der Trigger nachbilden, oder
  • eine Zwischenmutation mit einem versionierten Triggerupdate einfügen (siehe Mutation #113).

Als präventive Maßnahme kann in größeren Abständen pauschal ein komplettes Triggerupdate eingefügt werden (siehe Mutation #113).

OKAPI

Der OKAPI-Code greift parallel zum OC.de-Code auf die Datenbank zu. Bei Änderungen an Datenbankstruktur oder -inhalten ist daher immer zu prüfen, ob die OKAPI betroffen ist und angepasst werden muss.

Unter Umständen müssen Trigger aktualisiert werden, damit die OKAPI Änderungen an Cache- oder Logabhängigen Daten mitbekommt; siehe dazu modification-dates.txt.

Änderungen an OKAPI-eigenen Tabellen (okapi_*) werden von der OKAPI selbst verwaltet und spielen hier keine Rolle. Sie werden via okapi/views/update.php eingepflegt.