Zero-Downtime-Migration in Magento-Shops: Datenbank-Changes ohne Ausfall

1. Warum Downtime bei Magento-Datenbank-Migrationen entsteht

Eine klassische ALTER TABLE-Anweisung auf einer grossen InnoDB-Tabelle sperrt in vielen Faellen die Tabelle fuer Schreibzugriffe, solange die Aenderung laeuft. Bei einer catalog_product_entity mit mehreren Millionen Zeilen kann das Hinzufuegen eines Index ohne Zero-Downtime-Migration-Strategie mehrere Minuten bis Stunden dauern. In dieser Zeit blockieren Schreiboperationen aus dem Checkout, aus Preisregeln und aus Cron-Jobs, was sich als haengender Warenkorb oder Timeout beim Bestellabschluss zeigt.

Magento selbst fuehrt seine eigenen Schema-Aenderungen ueber bin/magento setup:upgrade aus, das intern MySQL-DDL-Befehle generiert und ausfuehrt. Ohne zusaetzliche Vorsicht laeuft dieser Prozess mit Standard-ALTER TABLE-Semantik, was bei kleinen Shops kein Problem ist, bei Shops mit hoher Schreiblast aber zu spuerbaren Ausfaellen fuehrt. Genau hier setzt eine geplante Zero-Downtime-Migration an: Sie ersetzt blockierende DDL durch Online-Schema-Change-Verfahren, die eine Kopie der Tabelle im Hintergrund erzeugen und erst am Ende atomar umschalten.

Der Unterschied zwischen einer naiven Migration und einer echten Zero-Downtime-Migration liegt selten im Ziel-Schema selbst, sondern im Weg dorthin. Beide Ansaetze erzeugen am Ende dieselbe Tabellenstruktur, aber nur der zweite haelt die Tabelle waehrend der gesamten Migrationsdauer fuer Lese- und Schreibzugriffe verfuegbar. Fuer Shops mit einem SLA von 99,9 Prozent oder mehr ist das kein Nice-to-have, sondern eine harte Anforderung an jede Release-Pipeline.

2. Declarative Schema als Fundament fuer Zero-Downtime-Migration

Seit Magento 2.3 ersetzt das Declarative Schema in db_schema.xml die alten InstallSchema- und UpgradeSchema-Skripte. Der entscheidende Vorteil fuer eine Zero-Downtime-Migration: Die XML-Datei beschreibt den Zielzustand der Tabelle deklarativ, waehrend Magento selbst berechnet, welche ALTER TABLE-Befehle noetig sind, um vom aktuellen Ist-Zustand zum gewuenschten Soll-Zustand zu kommen. Das reduziert menschliche Fehler bei manuell geschriebenen Migrationsskripten und macht Schema-Aenderungen versionierbar und reproduzierbar.

Vor jedem Deployment sollte bin/magento setup:db:declaration:generate-whitelist ausgefuehrt werden, um die generierte db_schema_whitelist.json zu aktualisieren. Diese Datei dokumentiert, welche Tabellenaenderungen bereits produktiv ausgerollt wurden, und verhindert, dass Magento bei einem erneuten Deploy versehentlich Spalten oder Indizes wieder entfernt. Fuer eine saubere Zero-Downtime-Migration gehoert dieser Schritt in jede CI-Pipeline, direkt vor dem eigentlichen Deployment-Job.

-- db_schema.xml (Auszug): neue Spalte und Index deklarativ hinzufuegen
-- File: app/code/Mironsoft/CatalogExtension/etc/db_schema.xml
<table name="catalog_product_entity" resource="default" engine="innodb">
    <column xsi:type="varchar" name="external_sku" nullable="true" length="64"
            comment="External Reference SKU for Zero-Downtime-Migration Rollout"/>
    <index referenceId="CATALOG_PRODUCT_ENTITY_EXTERNAL_SKU" indexType="btree">
        <column name="external_sku"/>
    </index>
</table>

-- Generierter DDL-Befehl (durch Magento intern erzeugt, NICHT direkt ausfuehren)
-- Ohne Online-Schema-Change blockiert dieser Befehl Schreibzugriffe:
ALTER TABLE `catalog_product_entity`
  ADD COLUMN `external_sku` VARCHAR(64) NULL COMMENT 'External Reference SKU',
  ADD INDEX `CATALOG_PRODUCT_ENTITY_EXTERNAL_SKU` (`external_sku`);

Ein haeufiger Fehler: Teams pruefen die generierte db_schema_whitelist.json nicht in ihr Repository ein und wundern sich, warum setup:upgrade im Staging anders reagiert als in der Produktion. Fuer eine verlaessliche Zero-Downtime-Migration muss die Whitelist-Datei denselben Versionsstand haben wie db_schema.xml selbst, sonst generiert Magento inkonsistente DDL-Sequenzen zwischen den Umgebungen.

3. bin/magento setup:upgrade im Detail: Sperren und Reihenfolge

bin/magento setup:upgrade durchlaeuft mehrere Phasen: Zuerst werden alle db_schema.xml-Dateien aller Module eingelesen und zu einem Gesamtschema zusammengefuehrt, danach vergleicht Magento dieses Zielschema mit dem tatsaechlichen Datenbankschema und generiert die noetigen DDL-Statements. Erst danach laufen die Data-Patches. Fuer eine Zero-Downtime-Migration ist wichtig zu wissen, dass Magento diese DDL-Statements sequenziell und mit Standard-MySQL-Locking ausfuehrt, sofern man nicht manuell eingreift.

Bei kleinen Tabellen mit wenigen tausend Zeilen ist das unproblematisch, weil MySQL 8.0 fuer viele DDL-Operationen bereits Instant- oder In-Place-Algorithmen nutzt, etwa beim Hinzufuegen einer nullable Spalte am Tabellenende. Kritisch wird es bei Operationen, die eine vollstaendige Tabellenkopie erfordern, etwa das Aendern eines Spaltentyps, das Hinzufuegen eines Primaerschluessels oder bestimmte Index-Aenderungen auf sehr grossen Tabellen wie sales_order_grid oder catalog_product_index_eav. Genau diese Faelle sind der Ausgangspunkt fuer den Einsatz von Online-Schema-Change-Tools innerhalb der Zero-Downtime-Migration-Strategie.

4. Online Schema Change Tools: gh-ost und pt-online-schema-change

Beide Tools loesen dasselbe Grundproblem auf unterschiedliche Weise: Statt die Originaltabelle direkt zu sperren, erstellen sie eine Schattentabelle mit dem Zielschema, kopieren die Daten in Batches und synchronisieren laufende Aenderungen, bis am Ende ein kurzer, atomarer RENAME TABLE-Swap die alte durch die neue Tabelle ersetzt. Dieser Swap dauert typischerweise unter einer Sekunde, was den Kern jeder erfolgreichen Zero-Downtime-Migration ausmacht.

pt-online-schema-change aus dem Percona Toolkit nutzt dafuer Trigger, die auf der Originaltabelle installiert werden und jede Aenderung sofort in die Schattentabelle spiegeln. gh-ost von GitHub geht einen anderen Weg und liest stattdessen den Binlog der Datenbank, um Aenderungen asynchron nachzuziehen, ganz ohne Trigger auf der Produktionstabelle. Fuer eine belastbare Zero-Downtime-Migration lohnt sich ein genauer Blick auf beide Ansaetze, weil sie unterschiedliche Lastprofile und Risiken mitbringen.

Ein oft unterschaetzter Aspekt: Beide Tools throtteln sich selbst anhand von Replikationslag und Systemlast. gh-ost prueft standardmaessig den Lag auf Replikas und pausiert automatisch, wenn dieser einen Schwellenwert ueberschreitet. Diese eingebaute Drosselung ist der eigentliche Grund, warum eine Zero-Downtime-Migration mit diesen Tools auch auf Shops mit kontinuierlicher Schreiblast sicher funktioniert, waehrend ein blindes ALTER TABLE keine solche Ruecksicht nimmt.

5. gh-ost in der Praxis: Magento-Tabellen ohne Sperren migrieren

Fuer den produktiven Einsatz von gh-ost in einer Magento-Umgebung braucht der ausfuehrende Datenbankbenutzer REPLICATION SLAVE- und REPLICATION CLIENT-Rechte, weil das Tool sich als Replikations-Client gegenueber dem Binlog verhaelt. Der erste Schritt jeder Zero-Downtime-Migration mit gh-ost ist ein Testlauf im --dry-run-Modus, der die geplante Aenderung validiert, ohne tatsaechlich Daten zu bewegen.

# Dry-run: Aenderung validieren, keine Daten werden geschrieben
gh-ost \
  --host=db.mironsoft-shop.internal \
  --user=gh_ost_migration \
  --password="$GHOST_DB_PASSWORD" \
  --database=magento_prod \
  --table=catalog_product_entity \
  --alter="ADD COLUMN external_sku VARCHAR(64) NULL, ADD INDEX idx_external_sku (external_sku)" \
  --max-load=Threads_running=25 \
  --critical-load=Threads_running=50 \
  --chunk-size=1000 \
  --dry-run

# Produktivlauf mit kontrolliertem Cutover
gh-ost \
  --host=db.mironsoft-shop.internal \
  --user=gh_ost_migration \
  --password="$GHOST_DB_PASSWORD" \
  --database=magento_prod \
  --table=catalog_product_entity \
  --alter="ADD COLUMN external_sku VARCHAR(64) NULL, ADD INDEX idx_external_sku (external_sku)" \
  --max-lag-millis=1500 \
  --chunk-size=1000 \
  --cut-over=default \
  --execute

Der Parameter --max-lag-millis ist bei einer Zero-Downtime-Migration auf einem replizierten Magento-Cluster entscheidend: gh-ost pausiert die Kopie automatisch, sobald der Replikationslag den Schwellenwert ueberschreitet, und verhindert so, dass Read-Replicas mit veralteten Produktdaten ausgeliefert werden. Der --cut-over=default-Modus fuehrt den finalen Tabellentausch atomar durch und haelt kurz alle Schreibzugriffe an, typischerweise fuer wenige hundert Millisekunden, was fuer Endkunden nicht wahrnehmbar ist.

6. pt-online-schema-change: Trigger-Ansatz und Fallstricke

Der Trigger-basierte Ansatz von pt-online-schema-change ist einfacher aufzusetzen, weil kein Zugriff auf den Binlog noetig ist und das Tool direkt gegen den primaeren Datenbankserver arbeitet. Fuer eine Zero-Downtime-Migration in kleineren bis mittleren Magento-Installationen ohne komplexe Replikationstopologie ist das oft die pragmatischere Wahl. Die Trigger selbst erzeugen jedoch zusaetzliche Schreiblast auf der Originaltabelle, weil jede INSERT-, UPDATE- und DELETE-Operation dupliziert wird.

pt-online-schema-change \
  --alter "ADD COLUMN external_sku VARCHAR(64) NULL, ADD INDEX idx_external_sku (external_sku)" \
  --host=db.mironsoft-shop.internal \
  --user=pt_migration \
  --ask-pass \
  --max-load="Threads_running=25" \
  --critical-load="Threads_running=50" \
  --chunk-size=1000 \
  --recursion-method=none \
  --alter-foreign-keys-method=auto \
  D=magento_prod,t=catalog_product_entity \
  --execute

Ein bekannter Fallstrick bei Fremdschluessel-lastigen Magento-Tabellen wie sales_order oder quote_item: --alter-foreign-keys-method=auto laesst pt-online-schema-change selbst entscheiden, ob abhaengige Fremdschluessel via DROP_SWAP oder REBUILD_CONSTRAINTS aktualisiert werden. Bei sehr vielen referenzierenden Tabellen kann REBUILD_CONSTRAINTS die Laufzeit der Zero-Downtime-Migration erheblich verlaengern, weil jede abhaengige Tabelle einzeln angepasst wird. In solchen Faellen ist ein expliziter Test in einer Staging-Kopie mit produktionsnahem Datenvolumen Pflicht, bevor der Befehl gegen die Produktion laeuft.

7. Sichere Rollout-Patterns fuer Schema-Changes

Eine robuste Zero-Downtime-Migration endet nicht mit dem erfolgreichen DDL-Befehl, sondern beruecksichtigt auch den Anwendungscode, der auf das neue Schema zugreift. Das etablierte Pattern ist Expand-and-Contract: Zuerst wird die Datenbank um das neue Feld erweitert, waehrend die Anwendung weiterhin nur mit dem alten Schema arbeitet. Danach wird ein neuer Anwendungscode deployt, der beide Schemas gleichzeitig verstehen kann. Erst wenn dieser Code stabil in Produktion laeuft, folgt ein zweiter Migrationsschritt, der die alten Spalten entfernt.

Fuer risikoreichere Aenderungen empfiehlt sich zusaetzlich ein Canary-Rollout auf Anwendungsebene: Ein kleiner Anteil des Traffics, etwa ueber Feature Flags gesteuert, nutzt den neuen Code-Pfad zuerst, waehrend der Grossteil weiterhin die stabile Version faehrt. Erst nach einer definierten Beobachtungszeit ohne Fehleranstieg wird der neue Pfad auf 100 Prozent des Traffics ausgerollt. Diese Kombination aus Expand-and-Contract auf Datenbankebene und Canary-Rollout auf Anwendungsebene ist der Kern jeder produktionsreifen Zero-Downtime-Migration in grossen Magento-Umgebungen.

8. Grosse Tabellen: sales_order, quote, catalog_product_entity

Nicht jede Tabelle in Magento verlangt dieselbe Vorsicht bei einer Zero-Downtime-Migration. Kataloge mit wenigen tausend Produkten koennen auch mit einem klassischen ALTER TABLE innerhalb eines kurzen Wartungsfensters migriert werden. Bei sales_order, sales_order_item und quote mit mehreren Millionen Zeilen in gewachsenen B2B-Shops ist ein Online-Schema-Change-Tool dagegen praktisch alternativlos, weil diese Tabellen permanent von Checkout-Prozessen beschrieben werden.

Bei catalog_product_entity und den zugehoerigen EAV-Wertetabellen kommt eine zusaetzliche Komplexitaet hinzu: Reindexierungsprozesse laufen parallel zu Schema-Aenderungen und erzeugen selbst erhebliche Schreiblast. Eine Zero-Downtime-Migration auf diesen Tabellen sollte deshalb ausserhalb der taeglichen Indexer-Cron-Fenster geplant werden, oder die betroffenen Indexer temporaer auf den Modus "Schedule" mit verlaengertem Intervall umgestellt werden, um Ressourcenkonflikte mit dem laufenden gh-ost- oder pt-online-schema-change-Prozess zu vermeiden.

# Indexer-Status vor der Migration pruefen
bin/magento indexer:status

# Betroffene Indexer temporaer auf Schedule-Modus mit laengerem Intervall stellen
bin/magento indexer:set-mode schedule catalog_product_price catalog_product_category

# Nach erfolgreicher Zero-Downtime-Migration: Indexer zurueckstellen und neu aufbauen
bin/magento indexer:set-mode realtime catalog_product_price catalog_product_category
bin/magento indexer:reindex catalog_product_price

9. Monitoring und Rollback waehrend der Migration

Waehrend jeder Zero-Downtime-Migration gehoert kontinuierliches Monitoring zum Pflichtprogramm: Replikationslag, aktive Threads, Lock-Waits und die Fortschrittsanzeige des jeweiligen Tools muessen in Echtzeit sichtbar sein. Sowohl gh-ost als auch pt-online-schema-change geben periodisch Statuszeilen mit dem prozentualen Fortschritt und der geschaetzten Restlaufzeit aus, die in ein zentrales Logging-System gespiegelt werden sollten.

-- Aktive Threads und Locks waehrend der Migration ueberwachen
SHOW PROCESSLIST;

-- Detaillierte Sperrinformationen (MySQL 8.0 / Percona Server)
SELECT
    r.trx_id AS blocked_trx,
    r.trx_mysql_thread_id AS blocked_thread,
    b.trx_id AS blocking_trx,
    b.trx_mysql_thread_id AS blocking_thread
FROM performance_schema.data_lock_waits w
JOIN information_schema.innodb_trx b ON b.trx_id = w.blocking_engine_transaction_id
JOIN information_schema.innodb_trx r ON r.trx_id = w.requesting_engine_transaction_id;

-- Replikationslag pruefen, bevor der finale Cutover ausgeloest wird
SHOW REPLICA STATUS\G

Fuer den Ernstfall braucht jede Zero-Downtime-Migration einen klaren Rollback-Plan: Sowohl gh-ost als auch pt-online-schema-change lassen sich per Signal oder Steuerdatei sauber abbrechen, ohne die Originaltabelle zu beschaedigen, da diese bis zum finalen Cutover vollstaendig unangetastet bleibt. Ein Abbruch vor dem Cutover ist deshalb risikofrei. Kritisch wird es nur, wenn der Fehler erst nach dem Tabellentausch auffaellt, weshalb ein Backup unmittelbar vor dem Cutover-Zeitpunkt zur Standardprozedur gehoert.

10. Zusammenfassung

Eine belastbare Zero-Downtime-Migration fuer Magento-Shops beginnt mit sauberem Declarative Schema in db_schema.xml und einer gepflegten Whitelist-Datei. Fuer kleine Tabellen genuegt bin/magento setup:upgrade mit Standard-DDL. Sobald Tabellen wie catalog_product_entity, sales_order oder quote mehrere Millionen Zeilen und dauerhafte Schreiblast haben, sind gh-ost und pt-online-schema-change die richtigen Werkzeuge, um Sperren zu vermeiden und den finalen Tabellentausch auf wenige hundert Millisekunden zu begrenzen.

Der zweite Erfolgsfaktor liegt im Rollout-Pattern auf Anwendungsebene: Expand-and-Contract trennt Datenbankaenderung und Codeaenderung sauber voneinander, waehrend Canary-Rollouts das Risiko fuer den gesamten Traffic minimieren. Kontinuierliches Monitoring von Replikationslag und Lock-Waits waehrend der Migration und ein klarer Rollback-Plan vor dem Cutover machen aus einer riskanten Schema-Aenderung eine planbare, wiederholbare Zero-Downtime-Migration, die auch bei wachsenden Datenmengen zuverlaessig funktioniert.

11. FAQ: Zero-Downtime-Migration in Magento-Shops