Eine Komponente aktualisieren

Wie Sie eine neue Fassung einspielen, ohne Daten zu verlieren — und wie Sie auf den Stand von vorher zurückkommen, wenn die neue nicht taugt.

Es gibt keine gemeinsame Fassung der Suite. Jede Komponente ist ein eigenes Paket mit eigenem Datum in plugin.info.txt und wird für sich aktualisiert. Sie müssen nicht alle auf einmal anfassen.

• Ein Administratorkonto und Schreibzugriff auf das Verzeichnis der Komponente. Der Erweiterungsmanager bricht eine Aktualisierung ab, wenn lib/plugins/<kennung>/ nicht schreibbar ist.
• Der aktuelle Stand ist bekannt. Notieren Sie das Datum, das Administration → Erweiterungsverwaltung für die Komponente anzeigt. Es kommt aus plugin.info.txt und ist die einzige Fassungsangabe, die es gibt.
• Ein Zeitfenster ohne Schreibzugriffe. Migrationen laufen beim ersten Seitenaufruf nach der Aktualisierung. Ein zweiter Aufruf, der zeitgleich in dieselbe Datenbank schreibt, trifft sie mitten in der Arbeit.
• Platz für die Sicherung in der Größe von data/ und conf/.

DokuWiki bringt keine Sicherungsfunktion mit. Sichern Sie auf Dateiebene, bei angehaltenem Webserver oder wenigstens in einem Moment ohne Schreibzugriffe:

tar czf sicherung-vor-update.tar.gz conf data lib/plugins/wkrequest

Beziehen Sie das Paket wie bei der Installation (Das Paket beziehen) und spielen Sie es über denselben Weg ein, den Sie zur Installation benutzt haben.

Rufen Sie eine gewöhnliche Wiki-Seite auf, danach die Oberfläche der aktualisierten Komponente. Damit sind die Migrationen erledigt — sie brauchen keinen Befehl und keine Wartungsseite.

Wie das abläuft. Speichernde Komponenten prüfen ihr Schema beim ersten Zugriff einer Anfrage auf ihre Datenbank. Eine Tabelle schema_migrations in der Datenbank selbst hält fest, welche Fassungen bereits angewandt wurden; offene Fassungen laufen in aufsteigender Reihenfolge, jede in einer eigenen Transaktion samt ihrem Vermerk. Steht nichts an, geschieht nichts — der Aufruf ist dann folgenlos.

Was dabei gesichert wird. Vor der ersten anstehenden Änderung kopiert der Migrationsläufer die Datenbankdatei nach data/dwdo/backup/<name>.sqlite.<JJJJMMTT-HHMMSS>.bak. Steht nichts an, wird auch nichts kopiert. Diese Kopie ist die einzige Rücknahme, die es für ein Schema gibt: Migrationen laufen ausschließlich vorwärts, weil sich SQLite-DDL — eine entfernte oder umbenannte Spalte — nicht allgemein durch eine Gegenanweisung zurücknehmen lässt.

Wenn eine Migration scheitert. Die betroffene Fassung wird vollständig zurückgerollt, ihr Vermerk ebenso; es bleibt weder ein halbes Schema noch ein falscher „erledigt„-Eintrag. Frühere Fassungen desselben Laufs bleiben jedoch angewandt — Fassung 002 kann scheitern, nachdem 001 bereits festgeschrieben wurde.

Welche Komponente ein Schema führt und wo dessen Datei liegt, steht in der Tabelle zu Datenbestand und Migrationen.

Zwei Dinge können sich ändern, ohne dass eine Fehlermeldung darauf hinweist:

• Konfigurationsschlüssel. Ein umbenannter oder entfallener Schlüssel steht weiterhin in conf/local.php und wird schlicht nicht mehr gelesen. Die Komponente arbeitet dann mit ihrer Voreinstellung, während die Konfiguration etwas anderes zu sagen scheint. Vergleichen Sie nach der Aktualisierung den Abschnitt der Komponente in Administration → Konfiguration mit dem, was in conf/local.php steht.
• Dienste und Verträge. Die Plattformereignisse und Dienstverträge sind als stabil oder experimentell gekennzeichnet; ein stabiler Vertrag bricht nicht ohne vorherige Abkündigung. Den aktuellen Stand zeigt ?do=wkcore_diag mit $conf['allowdebug'] = 1.

Wo die Änderungen einer Fassung stehen. Von den Komponenten dieses Hauses führt allein wkblog eine CHANGELOG.md im Paket. Für alle anderen ist die Historie des Repositorys die Quelle. Prüfen Sie zusätzlich README.md der neuen Fassung: Der Abschnitt Requirements ist der Ort, an dem eine neu hinzugekommene harte Abhängigkeit steht.

Die Rücknahme in der Reihenfolge, in der sie funktioniert:

1. Die Komponente deaktivieren.
2. Das Verzeichnis der neuen Fassung entfernen und das gesicherte Verzeichnis der alten Fassung an dieselbe Stelle zurücklegen.
3. Nur wenn Migrationen gelaufen sind: Die betroffene Datenbank durch die Kopie aus data/dwdo/backup/ mit dem passenden Zeitstempel ersetzen. Alles, was seit der Aktualisierung geschrieben wurde, geht dabei verloren — deshalb das Zeitfenster aus den Voraussetzungen.
4. conf/local.php anfassen (Änderungsdatum aktualisieren), um Seiten-, CSS- und JavaScript-Zwischenspeicher zu verwerfen.
5. Die Komponente wieder aktivieren und die Funktionsprüfung wiederholen.

Eine alte Programmfassung auf einem neueren Schema arbeiten zu lassen, ist nicht vorgesehen. Wenn Migrationen gelaufen sind, gehört Schritt 3 zur Rücknahme dazu.

1. Die neue Fassung ist geladen. Administration → Erweiterungsverwaltung zeigt für die Komponente das Datum der neuen Fassung. Zeigt es das alte, hat DokuWiki das alte plugin.info.txt gelesen — die Dateien liegen am falschen Ort oder ein Bytecode-Zwischenspeicher hält die alte Fassung fest.

2. Das Schema ist auf Stand. Die Datenbank enthält für jede Fassung eine Zeile in schema_migrations. Wenn Sie das Werkzeug zur Hand haben:

sqlite3 data/dwdo/request.sqlite "SELECT version, applied_at FROM schema_migrations ORDER BY version;"

Ein Lauf, der etwas zu tun hatte, hinterlässt zusätzlich eine frische Datei in data/dwdo/backup/. Findet sich dort keine und stand auch nichts an, ist das der erwartete Fall und kein Fehler.

3. Die Komponente arbeitet. Wiederholen Sie den Nachweis aus der Tabelle zur Funktionsprüfung — denselben, mit dem Sie die Installation abgeschlossen haben. Erst dieser Nachweis beendet die Aktualisierung.

• Komponentenmatrix — Datenbestand, Migrationen und Funktionsprüfung je Komponente.
• Fehlerdiagnose — wenn einer der drei Nachweise misslingt.
• Eine Komponente entfernen — wenn die Aktualisierung die Entscheidung war, die Komponente aufzugeben.
• Eine Komponente installieren — Bezugsquelle und Installationswege, die auch für die Aktualisierung gelten.