Bestehende Wagtail-Site sicher auf eine neue Version migrieren
Wagtail-Upgrades gehören zu den Aufgaben, für die ich am häufigsten gebucht werde — oft nachdem eine Site zwei, drei Jahre nicht angefasst wurde. Hier ist die Vorgehensweise, mit der ich das Risiko klein halte.
Warum regelmäßig upgraden?
- Sicherheits-Patches — veraltete Wagtail-/Django-Versionen sind ein echtes Risiko
- Wagtail folgt einem festen Release-Zyklus mit LTS-Versionen
- Je größer der Versionssprung, desto schmerzhafter — kleine, regelmäßige Schritte sind einfacher
Vorbereitung: Ist-Stand erfassen
# Aktuelle Versionen dokumentieren
pip freeze | grep -i -E "wagtail|django"
# Wagtail 5.2 (LTS), Django 4.2 (LTS) z.B.
# Ziel-Version und Zwischenschritte planenBevor irgendetwas geändert wird: sicherstellen, dass die bestehende Testabdeckung läuft — und ein frisches Datenbank-Backup existiert. Ohne Tests wird ein Upgrade zum Blindflug.
Schrittweise statt in einem Sprung
Von Wagtail 4.1 auf 6.x zu springen ist ein Rezept für Frust. Besser: Version für Version, jeweils mit Tests und Deploy dazwischen.
# Ein Minor-Schritt nach dem anderen
pip install "wagtail>=5.0,<5.1"
python manage.py migrate
python manage.py test
# ... prüfen, deployen, dann nächster Schritt
pip install "wagtail>=5.1,<5.2"Orientiere dich an den offiziellen Upgrade-Notizen. Wagtail dokumentiert pro Version alle Breaking Changes und Deprecations sehr sauber.
Deprecations abarbeiten
Wagtail warnt vor Entfernungen meist eine bis zwei Versionen im Voraus. Diese Warnungen sichtbar machen und abarbeiten:
# Deprecation-Warnungen beim Testlauf anzeigen
python -W error::DeprecationWarning manage.py test
# Häufige Migrationspunkte in neueren Wagtail-Versionen:
# - Page.get_admin_display_title -> get_admin_display_title entfällt teils
# - wagtail.core.* -> wagtail.* (seit Wagtail 3)
# - RichText-Features und StreamField-APIsStreamField-Datenmigrationen
Der heikelste Teil: Wenn sich Block-Strukturen ändern, müssen bestehende Inhalte migriert werden. Wagtail bietet dafür Hilfen:
# wagtail-Hilfe für StreamField-Migrationen
from wagtail.blocks.migrations.migrate_operation import MigrateStreamData
from wagtail.blocks.migrations import operations
class Migration(migrations.Migration):
operations = [
MigrateStreamData(
app_name="blog",
model_name="BlogPage",
field_name="body",
operations=[
# z.B. alten Block-Typ in neuen umbenennen
(operations.RenameStreamChildrenOperation(
old_name="paragraph", new_name="text"), "body"),
],
),
]Solche Datenmigrationen immer erst auf einer Kopie der Produktionsdaten testen — nie direkt auf Produktion.
Testen & Rollback
- Upgrade auf einer Staging-Umgebung mit echten (anonymisierten) Daten
- Admin durchklicken: Seiten bearbeiten, Bilder, StreamField-Blöcke, Vorschau
- Rollback-Plan: DB-Backup + vorheriger Requirements-Stand griffbereit
Fazit
Ein sicheres Wagtail-Upgrade ist vor allem Disziplin: kleine Schritte, Tests dazwischen, Deprecations ernst nehmen, StreamField-Migrationen auf Kopien testen. Wer regelmäßig upgradet, hat mit jedem einzelnen Schritt wenig Arbeit — wer es jahrelang aufschiebt, bekommt ein Projekt.
