Datenmigrationen

Das Format, in dem das Plugin Inhalte speichert, hat eine Version. Ändert ein Update dieses Format, baut eine Migration die vorhandenen Daten um. Das passiert von selbst. Du kannst es aber auch beobachten und von Hand anstoßen.

Wie es funktioniert

• Die Option wpce_db_version sagt, bei welchem Schritt die Daten einer Website stehen. Eine frische Installation beginnt beim neuesten Schritt, sie hat nichts zu migrieren. Eine Website, die schon Daten hat, bleibt bei ihrer Version.
• Jede Migration ist eine Klasse in includes/Setup/Migrations/ mit einer Nummer. Neue Migrationen werden angehängt, nie eingefügt.
• Sie sind idempotent: Läuft eine Migration auf Daten, die sie schon umgebaut hat, ändert sie nichts.
• Jeder Lauf steht im Protokoll, der Option wpce_db_migration_log: Datum, Schritt, Zahl der geänderten Datensätze.
• Das Plugin vergleicht beim init (Priorität 100) die Datenversion mit der neuesten und führt die fehlenden Schritte der Reihe nach aus. Das passiert bei der ersten Seitenabfrage nach einem Update, ob sie ins Backend oder auf die Website geht, auch bei einem Besucher, der nicht angemeldet ist. Dafür gibt es keinen Knopf und keine Meldung. Der Versionswert ist geladen, die Prüfung kostet nichts.
• Nach jedem Schritt steht die neue Datenversion in der Option. Bricht ein Schritt mit einem Fehler ab, bleiben die davor erledigten Schritte stehen, und der Schritt, der abgebrochen ist, läuft bei der nächsten Anfrage noch einmal. Das Plugin fängt den Fehler nicht ab: Die Anfrage, in der er auftritt, kann mit einer Fehlermeldung enden. Die Sperre wird danach freigegeben.
• Eine Sperre (ein Transient wpce_db_upgrading, fünf Minuten) verhindert, dass zwei Anfragen zugleich dieselben Schritte starten. Die zweite wartet auf die nächste Anfrage.

Eine Website wird also bei ihrer ersten Anfrage nach dem Update migriert, nicht erst, wenn jemand das Backend öffnet.

Mit WP-CLI

Du brauchst WP-CLI, um sie zu beobachten und von Hand zu starten:

wp wpce status              # Version, ausstehende Migrationen, Protokoll
wp wpce upgrade --dry-run   # zählt, was sich änderte; schreibt nichts
wp wpce upgrade             # führt die ausstehenden Migrationen aus

wp wpce status nennt die Datenversion und, was aussteht. Die Ausgabe auf einer Website, die auf dem neuesten Stand ist:

Data version 17 of 17.
Success: Nothing pending.

Darunter steht das Protokoll: je Lauf eine Zeile wie 2026-09-15T10:36:06+00:00 v2 M002_JsonToArrays: 65 changed. Steht etwas aus, listet status es mit Nummer und Beschreibung. wp wpce upgrade meldet je Schritt, was er tat:

Ran v<Nr.> <Name>: <Zahl> changed. <Satz, was der Schritt tut>
Success: Data now at version 17.

Mit --dry-run heißt es „Would run … would change“, und die Datenversion bleibt.

Geprüft: Die Zahl der Schritte (17), die Reihenfolge und die Ausgabetexte von wp wpce sind aus dem Quelltext des Plugins 1.0.0 gelesen (Upgrader::MIGRATIONS, UpgradeCommand). Gestartet habe ich wp wpce für diese Fassung der Seite nicht, und auch keinen Schritt.

Vor dem Update

• Mach vor jedem Update ein Backup der Datenbank. Eine Migration ändert Datensätze.
• Lauf zuerst mit --dry-run, wenn du ein Update auf einer größeren Website vorbereitest. Du siehst, wie viele Datensätze jeder Schritt anfasst.
• Ein Update einer Hauptversion kommt nie von selbst. Lies vorher die Hinweise im readme.txt (Abschnitt „Upgrade Notice“) des Plugins. Wie eine Website von 0.x auf 1.0.0 kommt, steht unter Von 0.x auf 1.0.0 umsteigen.

Die bisherigen Schritte

Der Stand zum Zeitpunkt dieser Doku (Plugin 1.0.0): 17 Schritte. Sie bringen Daten aus dem Format von 0.0.x auf das von 1.0.0.

Nr.	Name	Was sie tut
1	M001_Baseline	der Ausgangspunkt: „Version 1“ heißt Daten, wie 0.0.x/0.1.0 sie speicherte
2	M002_JsonToArrays	zusammengesetzte Feldwerte waren JSON-Strings, jetzt sind es Arrays
3	M003_ReferencesAsRows	Verweise auf andere Einträge: eine Meta-Zeile je ID statt einer serialisierten Liste
4	M004_LegacyFormats	Altlasten von 0.0.x: Galerie-Schlüssel, Kontaktpersonen, Orte und Zeiten von Kursen und Terminen
5	M005_ClubSetting	die Vereinsdaten aus sechs Optionen in die eine Einstellung wpce_club
6	M006_DemoIdentity	die Herkunft von Demo-Einträgen als allgemeine Kennung (_wpce_source)
7	M007_ClubDataCapability	entfernt das eigene Recht für die Vereinsdaten; es gilt manage_options
8	M008_ScheduleSortKeys	schreibt den Sortierwert für Zeiten von Kursen und Terminen
9	M009_CourseIndex	füllt den Filterindex der Kurse (Wochentag, Ort, Leitung)
10	M010_PersonTitles	gibt Personen ohne Titel ihren Namen als Titel
11	M011_EventIndex	füllt den Filterindex der Termine (letzter Tag, Ort, Ansprechpersonen)
12	M012_EntryChecks	prüft jeden Eintrag einmal und merkt sich die Zahl der Warnungen
13	M013_FieldBlocksSetting	entfernt die Einstellung „Blöcke für einzelne Felder im Block-Einfüger zeigen“
14	M014_SiteIdentity	entscheidet den Schalter „Als Website-Titel und Website-Logo verwenden“ für Vereine von vorher
15	M015_ScheduleEnd	entfernt eine doppelte Zeile für den letzten Tag eines Termins
16	M016_StaleRewriteRules	bittet um neue Permalink-Regeln für Downloads und Einträge, die keine eigene Seite haben
17	M017_IncompleteEntries	prüft jeden Eintrag noch einmal und merkt die Personen ohne Namen und die Mitgliedsbeiträge ohne Betrag, die die Website auslässt

Dazu zwei Eigenheiten, die du kennen solltest:

• M014 lässt Titel und Logo der Website in Ruhe, wenn dort schon etwas steht, das jemand gewählt hat. Es schaltet den Schalter nur ein, wo die Website kein Logo hat und ihr Titel leer, ein WordPress-Standard oder schon der Vereinsname ist. Der Verein schaltet ihn sonst selbst in den Vereinsdaten ein.
• M005 lässt die alten Optionen für eine Hauptversion unangetastet stehen. Ein späterer Schritt löscht sie.

Nicht jede Änderung ist eine Migration

Manche Änderungen sind einmalig und nicht Sache des Upgraders. Das readme.txt des Plugins nennt eine: Der Block-Namensraum wechselte mit 0.1.0 von wpce-plugin/ auf wpce/. Wer von 0.0.x kommt, führt auf bestehendem Inhalt vor dem Umstieg auf 1.0.0 einmal aus:

wp search-replace 'wp:wpce-plugin/' 'wp:wpce/'

Das steht im „Upgrade Notice“ des Plugins. Es betrifft Websites, die aus der Zeit vor dem eigenen Repository kommen. Eine Website, die schon eine 0.1.0-Vorabversion (-rc.1, -rc.2) hat, braucht es nicht.

Migrationen in einem Add-on

Ein Add-on versioniert eigene Änderungen am Speicherformat selbst, mit eigener Option und eigenem Upgrader nach dem Muster der Basis, siehe Eigene Inhaltstypen. Der Upgrader der Basis kennt die Migrationen eines Add-ons nicht.

Was schiefgeht

• Kein Backup. Eine Migration ändert Datensätze, und ein Rückweg ist nicht vorgesehen.
• Ein Schritt bricht ab. Die Schritte davor bleiben erledigt, der abgebrochene läuft bei der nächsten Anfrage noch einmal. Siehst du nach einem Update eine Fehlermeldung, prüfe mit wp wpce status, bei welcher Datenversion die Website steht, und starte den Rest mit wp wpce upgrade, dann siehst du die Meldung des Schrittes im Terminal. Kommt der Fehler dort wieder, spiel das Backup zurück und schick mir die Meldung.
• Zwei Anfragen auf einmal. Die Sperre fängt es ab. Die zweite läuft einfach nicht. Rechne bei einer großen Website damit, dass die Migration beim ersten Aufruf ein paar Sekunden braucht.
• Ein Update, das nur die Dateien tauscht. Wer das Plugin von Hand in den Ordner kopiert, bekommt die Migration trotzdem bei der nächsten Anfrage.
• Eine Migration, die du für abgeschlossen hältst. wp wpce status sagt, wo die Daten stehen.