Ein Shopware-6-Hauptversion-Update ist nicht dasselbe Problem wie eine Migration weg von Shopware 5. Shopware 5 ist eine tote Plattform, kompletter Neubau, kein Weg drumherum. Ein Hauptversion-Update innerhalb von Shopware 6 soll der einfache Weg sein: composer update, Migrationen ausführen, fertig.
Das stimmt, wenn der Shop aktuell geblieben ist. Es hört auf zu stimmen, sobald ein Shop abgedriftet ist, und genau das habe ich vorgefunden, als ich Anfang dieses Jahres ein Shopware-6.3-Projekt übernommen habe. Das steckte in diesem Shopware-6-Update tatsächlich drin: eine manuelle Migration weg von einem veralteten Projekt-Template, eine Kollision in Shopwares eigener Migrationshistorie, und das Skript, das ich geschrieben habe, um daran vorbeizukommen.
Warum “einfach das Update fahren” aufhört zu funktionieren
Ich habe bereits über die Migration weg von Shopware 5 geschrieben, ein anderes Projekt: neue Plattform, neues Templating, alles neu. Ein Hauptversion-Update innerhalb von Shopware 6 soll kleiner im Umfang sein, und bei einem Shop, der aktuell geblieben ist, ist es das meistens auch. Composer-Constraint anheben, Migrationen ausführen, fixen, was der Changelog als Breaking Change markiert hat, an einem Nachmittag erledigt.
Das hört auf, klein zu sein, sobald ein Shop genug Tooling-Wechsel übersprungen hat, dass der Update-Pfad selbst nicht mehr sauber ist. Das ist ein strukturelles Problem, kein Versionsnummer-Problem, und es zeigt sich erst, wenn man das Update tatsächlich startet. Man merkt es auf die harte Tour, meist mitten im Deployment, bei einem Shop, der bis dahin völlig gesund aussah.
Der Shop, den ich übernommen habe
Ich habe dieses Projekt mitten im Prozess übernommen, ohne Dokumentation dazu, was vorherige Entwickler ausgeführt hatten oder warum. Das ist ein üblicher Ausgangspunkt für Agentur- und Freelance-Arbeit: Ein Shop wechselt den Besitzer, die Übergabe-Notizen sind dünn oder nicht vorhanden, und man erbt, welche Entscheidungen auch immer unterwegs getroffen wurden. Genau diese Lücke lässt eine Shopware-Migration still fehlschlagen oder halb durchlaufen, ohne dass es jemand bemerkt, bis ein späteres Update das Problem erzwingt.
Was ich bei der Inspektion vorgefunden habe: Der Shop lief auf Shopware 6.3 und nutzte noch das alte shopware/production-Projekt-Template, von vor dem Umstieg auf Symfony Flex.
Dieses Detail zählt mehr als eine Versionsnummer. Das Production-Template und das Flex-basierte Skeleton unterscheiden sich nicht nur kosmetisch. Bin-Scripts, Bundle-Registrierung und die gesamte Projektkonfiguration sind zwischen beiden unterschiedlich aufgebaut. Ein Shop auf dem alten Template ist nicht nur “etwas zurück”. Er steht auf einer Struktur, die neuere Hauptversionen nicht mehr erwarten.
Das Production-Template von Hand zu Flex migrieren
Flex kam in Shopware 6.4.17.0, veröffentlicht im Oktober 2022, und wurde ab 6.5 zum Standard. Als ich dieses Projekt übernahm, lag ein Shop, der noch auf dem Pre-Flex-Production-Template lief, bereits seit Jahren hinter dem Standardpfad zurück.
Symfony Flex ändert mehr als ein, zwei Ordner. Es kontrolliert, wie composer.json Recipes deklariert, wie config/packages und config/bundles.php zusammengesetzt werden, und wie bin/console und die restlichen Bin-Scripts verdrahtet sind. Bei einem Shop, der von Anfang an Flex genutzt hat, ist davon im Alltag nichts sichtbar. Bei einem Shop, der nie umgestiegen ist, liegt jedes dieser Teile noch nach dem alten Muster vor, und eine neuere Hauptversion erwartet das neue Muster.
Es gab keinen dokumentierten Weg für einen Shop, der so weit vom üblichen Pfad abgekommen war. Also passierte der Umzug von Hand: Bin-Scripts verschieben, Bundle-Konfiguration neu aufbauen, das Projekt so umstrukturieren, wie Flex es erwartet. Ich will präzise sein, was das war und was nicht. Es war kein Fall von kaputtem oder fehlerhaftem composer recipes:update. Es war manuelle Übergangsarbeit, auf einem Pfad, den Shopwares eigenes Tooling für einen Shop, der schon so weit zurückliegt, nicht dokumentiert.
Wer meinen Beitrag über meinen Ansatz zur Shopware-6-Plugin-Entwicklung gelesen hat, erkennt hier dieselbe Lehre auf Projektebene wieder: Strukturelle Entscheidungen, die früh in einem Shopware-Build getroffen werden, summieren sich mit jedem Jahr, in dem sie unangetastet bleiben. Ein Plugin, das überschreibt statt zu dekorieren, bricht beim nächsten Update. Ein Projekt, das nie zu Flex gewechselt ist, bricht bei der nächsten Hauptversion.
Als die Core-Migrationen kollidierten
Nach der Umstrukturierung auf Flex war der nächste Schritt, den Shop bei Shopwares eigenen Core-Migrationen auf den aktuellen Stand zu bringen. Normalerweise der langweilige Teil. Hier nicht.
Einige von Shopwares Core-Migrationen waren bereits teilweise ausgeführt, bevor ich das Projekt übernommen habe. Ich weiß nicht, warum, und ich werde öffentlich nicht über die vorherige Entwicklungsgeschichte eines Kunden spekulieren. Was ich weiß: Was passierte, als ich versuchte, den Shop auf den aktuellen Stand zu bringen. Das erneute Ausführen dieser Migrationen kollidierte mit Schemaänderungen, die bereits in der Datenbank steckten.
Shopwares Migration-Runner markiert eine Migration erst als ausgeführt, wenn sie vollständig erfolgreich durchgelaufen ist, und wirft bei einem Fehler erneut. Es gibt keinen eingebauten Weg, eine Migration abzugleichen, die das Schema bereits geändert hat, aber nie als abgeschlossen in der Migrationstabelle markiert wurde.
Das lässt zwei schlechte Optionen und keine gute übrig. Blind erneut ausführen, und es scheitert an Spalten oder Tabellen, die bereits existieren. Überspringen, weil die Tabelle sagt, sie sei ausstehend, und man überspringt womöglich eine Migration, die wirklich nie gelaufen ist, was das gleiche Problem nur weiter den Update-Pfad hinunterschiebt. Keine der beiden ist für sich sicher, und bei einem Shop mit unklarer Historie lässt sich ohne Prüfung nicht sagen, welche der beiden man gerade vor sich hat.
Das Skript, das den Schemazustand prüfte, bevor es etwas anfasste
Die Lösung war, aufzuhören, der Migrationstabelle zu vertrauen, und stattdessen die Datenbank direkt zu prüfen. Ich habe ein Skript geschrieben, das für jede ausstehende Core-Migration das tatsächliche Schema inspiziert hat, Tabellen, Spalten, Indizes, was auch immer diese spezifische Migration erstellen oder ändern sollte, bevor entschieden wurde, ob sie ausgeführt, übersprungen oder für eine manuelle Prüfung markiert wird.
Diese eine Änderung machte aus einem blockierten Update ein funktionierendes. Das ist auch der Teil dieser Geschichte, der über diesen einen Shop hinaus verallgemeinert: Jedes Shopware-6-Hauptversion-Update auf einem übernommenen Projekt, oder jedem Shop, für dessen Deployment-Historie man nicht vollständig bürgen kann, braucht dieselbe Disziplin. Migrationen nicht gegen unbekannten Schemazustand ausführen. Erst prüfen, dann ausführen.
Der größere Punkt, den ich Shopware direkt sagen würde: Das sollte gar kein individuelles Skript sein müssen. Ein Migration-Runner, der den Schemazustand prüft, bevor er eine Änderung anwendet, statt seiner eigenen Tabelle zu vertrauen, ist auf jedem Shop sicherer, nicht nur bei denen mit unklarer Historie. Idempotente Migrationen sind in etlichen anderen Frameworks ein gelöstes Problem. Es ist eine vernünftige Sache, auch hier danach zu fragen.
Was das für ein geplantes Shopware-6-Hauptversion-Update bedeutet
Ein paar Dinge, die ich jedem sagen würde, der das auf einem Shop vorhat, den er nicht selbst von Grund auf gebaut hat.
- Migrationshistorie prüfen, bevor irgendetwas angefasst wird. Vergleichen, was die Migrationstabelle als gelaufen ausweist, mit dem, was das Schema tatsächlich enthält. Eine Abweichung ist das Warnsignal, nicht erst das Scheitern des Updates auf halbem Weg.
- Nicht annehmen, dass das Tooling eines übernommenen Shops aktuell ist. Speziell auf die Flex-Migration prüfen, wenn der Shop älter als 6.5 ist. Das ist leicht zu übersehen, weil der Shop auf der alten Struktur bis genau zu dem Moment einwandfrei läuft, in dem man versucht, darüber hinauszukommen.
- Den Update-Pfad gegen einen schema-verifizierten Klon testen, nicht gegen eine Neuinstallation. Eine saubere Shopware-Installation reproduziert niemals eine Kollision, die nur wegen der spezifischen Historie dieses einen Shops existiert.
- Wenn etwas wie ein Core-Bug aussieht statt wie die eigene Konfiguration, das konkret so benennen. Ich hatte dieselbe Erfahrung mit einem Shopware-Datumsfilter-Bug, der sich als in Shopwares eigenem Core liegend herausstellte: Die Details, die “unser Setup ist falsch” von “das ist ein Core-Problem” trennen, sind meist eng gefasst, und es lohnt sich, sie festzunageln, bevor man weiter Zeit investiert.
- Die strukturelle Arbeit separat vom Versionssprung budgetieren. Wenn ein Shop die Flex-Migration, eine Schema-Prüfung oder beides braucht, das als eigenständiges Arbeitspaket anbieten und einplanen. Es in “das Update” einzufalten, als wäre es gleich groß wie das Update eines sauberen Shops, ist der Grund, warum Zeitpläne kippen.
Shopwares Core-Team einbezogen
Ich habe diese Migrationsgeschichte öffentlich geschrieben, dieselbe, die hinter einem LinkedIn-Beitrag über Ehrlichkeit gegenüber Kunden stand und die besser lief, als ich erwartet hatte. Ein Shopware-Core-Entwickler hat das gesehen und sich direkt gemeldet, mit Fragen zu den Details des Updates. Ich habe angeboten, die genauen Migrationen und die genauen Fehler zu schicken.
Das ist der Teil, den ich jedem wiederholen würde, der auf etwas Ähnliches stößt: Ein vages “das Update ist kaputtgegangen” bekommt von niemandem Aufmerksamkeit. Genaue Migrationen und genaue Fehler übergeben zu können, schon.
Wenn vor Ihnen ein Shopware-6-Hauptversion-Update auf einem Shop mit unsicherer Historie liegt und Sie nicht auf die harte Tour herausfinden wollen, wo es kollidiert, nehmen Sie Kontakt auf. Genau diese Art von Update-Arbeit übernehme ich.
Häufig gestellte Fragen
Was ist der Unterschied zwischen einer Shopware-5-Migration und einem Shopware-6-Hauptversion-Update? Eine Migration von Shopware 5 zu 6 ist ein kompletter Plattform-Neubau. Ein Shopware-6-Hauptversion-Update bleibt auf derselben Plattform, kann aber echtes Risiko bergen, wenn der Shop weit zurückliegt oder eine unklare Migrationshistorie hat.
Ist ein Shopware-6-Hauptversion-Update nur composer update? Nur wenn der Shop beim Tooling aktuell geblieben ist und jede Migration eine bekannte, verifizierte Historie hat. Bei einem zurückliegenden Shop sind das die einfachen 10 % der Arbeit.
Was ist Symfony Flex und warum zählt es hier? Flex ist das recipe-basierte Skeleton, auf das Shopware umgestiegen ist, als Ersatz für das ältere Production-Template. Es kam in 6.4.17.0 und wurde ab 6.5 Standard. Ein Shop auf dem alten Template muss diese Struktur von Hand umziehen, bevor spätere Hauptversionen sauber updaten.
Was passiert, wenn Core-Migrationen teilweise ausgeführt wurden, bevor ich einen Shop übernommen habe? Shopware markiert eine Migration erst als ausgeführt, nachdem sie vollständig erfolgreich war. Ein Teil-Lauf lässt das Schema geändert, aber die Migration bleibt als ausstehend markiert, sodass ein blindes erneutes Ausführen mit dem kollidiert, was bereits da ist. Vor der Ausführung den tatsächlichen Schemazustand prüfen.
Woran erkenne ich, ob mein Shop Probleme mit der Migrationshistorie hat, bevor ich update? Migrationstabelle mit dem echten Schema vergleichen. Jede Abweichung, besonders bei einem übernommenen Shop, bedeutet: vor jedem weiteren Schritt prüfen.
Sollte ich einen Shopware-Core-Entwickler einbeziehen? Wenn Sie etwas Konkretes vorweisen können, ja. Genaue Migrationen und genaue Fehler bekommen eine nützliche Antwort. Ein vager Bug-Report nicht.
