Datenbank-Migrationen mit KI-Unterstützung planen

1. Warum Datenbank-Migrationen in Magento besondere Sorgfalt verlangen

Eine Datenbank-Migration in Magento betrifft selten nur eine isolierte Tabelle. Die EAV-Struktur des Produktkatalogs, Fremdschlüssel zwischen Bestellungen, Kunden und Zahlungsdaten sowie die Indexer-Pipeline reagieren empfindlich auf Schema-Änderungen. Wer eine Spalte entfernt oder einen Datentyp ändert, kann unbeabsichtigt Custom-Module, Drittanbieter-Erweiterungen oder Reporting-Queries brechen, die auf die ursprüngliche Struktur angewiesen sind. Genau in diesem Umfeld kann Claude als Werkzeug wertvoll sein: Es liefert schnell einen ersten, technisch korrekten Entwurf für db_schema.xml-Änderungen oder Data Patches, basierend auf einer natürlichsprachlichen Beschreibung der gewünschten Änderung.

Der entscheidende Punkt ist, dass diese Geschwindigkeit nicht mit Sicherheit verwechselt werden darf. Ein KI-generierter Vorschlag kennt weder die tatsächliche Datenverteilung in der Produktionsdatenbank noch alle Abhängigkeiten, die im Laufe der Jahre in einem gewachsenen Magento-Projekt entstanden sind. Migrationen, die Produktionsdaten anfassen, verdienen deshalb grundsätzlich denselben Prüfprozess wie jede andere kritische Codeänderung, unabhängig davon, wie überzeugend der Vorschlag auf den ersten Blick wirkt.

2. db_schema.xml verstehen: Deklaratives Schema statt InstallSchema

Seit Magento 2.3 ersetzt das deklarative Schema in db_schema.xml die alten imperativen InstallSchema- und UpgradeSchema-Skripte. Statt Befehle zu schreiben, die Schritt für Schritt eine Tabelle verändern, beschreibt man den gewünschten Endzustand deklarativ. Magento vergleicht diesen Zielzustand beim Aufruf von bin/magento setup:upgrade automatisch mit dem aktuellen Datenbankschema und generiert die notwendigen ALTER- und CREATE-Statements selbst. Das reduziert Boilerplate-Code erheblich und macht Schema-Änderungen über mehrere Module hinweg nachvollziehbarer.

Damit dieser Automatismus zuverlässig funktioniert, muss jede Änderung zusätzlich in db_schema_whitelist.json eingetragen werden, sonst ignoriert Magento sie beim Upgrade. Genau hier hilft Claude praktisch: Wenn man den bestehenden Inhalt der db_schema.xml und den gewünschten Endzustand als Kontext übergibt, kann das Modell sowohl den passenden XML-Diff als auch den zugehörigen Whitelist-Eintrag in einem Schritt vorschlagen. Das spart manuelles Nachschlagen von Attribut-Reihenfolge, Spaltentypen und Constraint-Namenskonventionen.

3. Von der fachlichen Anforderung zum Schema-Vorschlag

Die Qualität eines KI-generierten Schema-Vorschlags hängt fast vollständig vom Kontext ab, den man mitgibt. Eine vage Anfrage wie „füge ein Attribut für die Garantie hinzu" führt zu einem generischen, oft ungenauen Vorschlag. Deutlich bessere Ergebnisse entstehen, wenn man den bestehenden Tabellenauszug aus db_schema.xml einfügt, den exakten Spaltennamen, Datentyp, Nullable-Status und eventuelle Indizes benennt und explizit nach einem vollständigen Diff inklusive Whitelist-Eintrag fragt.

Ein weiterer wichtiger Baustein ist, Claude gezielt nach Risiken zu fragen, statt nur nach der Lösung: „Welche bestehenden Daten könnten durch diese Änderung ungültig werden?" oder „Braucht diese Spalte einen Default-Wert, um bestehende Zeilen nicht zu brechen?" liefert oft wertvollere Hinweise als der reine Code-Vorschlag selbst. In Claude Code lässt sich die bestehende db_schema.xml zudem direkt als Datei referenzieren, wodurch der Vorschlag konsistent zur tatsächlichen Projektstruktur bleibt, statt auf Trainingsdaten-Annahmen über eine generische Magento-Installation zu basieren.

4. Data Patches mit KI-Unterstützung entwerfen

Während db_schema.xml nur die Struktur beschreibt, übernehmen Data Patches (DataPatchInterface) die eigentliche Datenmigration: bestehende Werte umrechnen, aus einer alten Spalte in eine neue kopieren oder Standardwerte für bereits existierende Zeilen setzen. Claude kann aus einer Beschreibung wie „kopiere den Wert aus custom_price in die neue Spalte discounted_price, aber nur wenn er kleiner als price ist" ein vollständiges Patch-Klassengerüst inklusive getDependencies() und getAliases() erzeugen.

Ein Punkt, den KI-Vorschläge regelmäßig unterschätzen, ist die Größe der zu migrierenden Tabelle. Ein naiver Patch, der UPDATE-Statements ohne Batching gegen eine Tabelle mit Millionen Zeilen ausführt, kann Tabellen-Locks verursachen und den Shop während der Migration lahmlegen. Ein guter Prompt fordert deshalb explizit eine Batch-Verarbeitung mit konfigurierbarer Batch-Größe und Fortschritts-Logging an, damit der Patch auch auf großen Produktionsdatenbanken sicher läuft, statt nur auf einer kleinen Testdatenbank zu funktionieren.

<!-- db_schema.xml: add nullable warranty_months column via a separate extension table -->
<?xml version="1.0"?>
<schema xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Setup/Declaration/Schema/etc/schema.xsd">

    <table name="mironsoft_product_warranty" resource="default" engine="innodb" comment="Product Warranty Extension">
        <column xsi:type="int" name="entity_id" padding="10" unsigned="true" nullable="false" identity="false" comment="Product ID"/>
        <column xsi:type="smallint" name="warranty_months" padding="5" unsigned="true" nullable="true" identity="false" comment="Warranty in months, nullable until backfill patch runs"/>
        <constraint xsi:type="primary" referenceId="PRIMARY">
            <column name="entity_id"/>
        </constraint>
        <constraint xsi:type="foreign" referenceId="MIRONSOFT_WARRANTY_PRODUCT_ENTITY_ID_CPE_ENTITY_ID"
                    table="mironsoft_product_warranty" column="entity_id"
                    referenceTable="catalog_product_entity" referenceColumn="entity_id"
                    onDelete="CASCADE"/>
    </table>
</schema>

5. Warum KI-Vorschläge bei Produktionsdaten nie blind übernommen werden dürfen

Ein KI-Modell kann syntaktisch einwandfreien und stilistisch überzeugenden Code liefern, der inhaltlich trotzdem falsch ist, insbesondere wenn es um die tatsächliche Datenverteilung geht. Claude kennt weder, wie viele Zeilen im NULL-Zustand sind, noch ob eine vermeintlich eindeutige Spalte in der Praxis Duplikate enthält, noch welche Custom-Module stillschweigend auf die betroffene Tabelle zugreifen. Ein überzeugend formulierter Vorschlag ist deshalb kein Ersatz für eine Prüfung gegen die reale Datenbank, und die Überzeugungskraft der Formulierung sagt nichts über die Korrektheit aus.

In der Praxis bedeutet das: Jeder KI-generierte Schema- oder Datenvorschlag durchläuft denselben Review-Prozess wie jede andere Änderung, die auf Produktionsdaten wirkt, ohne Sonderweg nach dem Motto „das hat ja die KI schon geprüft". Dazu gehören ein Code-Review durch eine Person mit Kenntnis der gewachsenen Projektstruktur, ein Testlauf auf einer aktuellen Kopie der Produktionsdatenbank und eine explizite Prüfung der betroffenen Zeilenanzahl vor und nach der Migration. Diese Schritte sind bei manuell geschriebenen Migrationen selbstverständlich, bei KI-generierten aber ebenso zwingend, unabhängig davon, wie schlüssig der Vorschlag wirkt.

6. Praxisbeispiel: Neues Pflichtfeld plus Datenmigration Schritt für Schritt

Ein typisches Szenario: Ein Produktattribut warranty_months soll eingeführt werden, das langfristig als Pflichtfeld (NOT NULL) gelten soll. Ein direkter NOT NULL-Schritt ohne Default würde setup:upgrade sofort scheitern lassen, sobald auch nur eine bestehende Zeile NULL enthält. Der sichere Weg besteht aus zwei getrennten Schritten: Zuerst wird die Spalte nullable angelegt, danach läuft ein Data Patch, der bestehende Zeilen mit einem sinnvollen Wert befüllt, und erst in einem späteren Release wird die Spalte auf NOT NULL umgestellt.

Claude eignet sich gut, um genau diese zweistufige Struktur vorzuschlagen, wenn man explizit nach einer produktionssicheren Migrationsstrategie fragt statt nach der schnellsten Lösung. Das folgende Beispiel zeigt das zugehörige Data-Patch-Grundgerüst mit Batch-Verarbeitung, wie es aus einer solchen Anfrage entstehen kann, ergänzt um die Befehle zur Verifikation auf der Kommandozeile.

<?php
declare(strict_types=1);

namespace Mironsoft\ProductWarranty\Setup\Patch\Data;

use Magento\Framework\Setup\Patch\DataPatchInterface;
use Magento\Framework\Setup\ModuleDataSetupInterface;

/**
 * Backfills warranty_months for existing products in batches.
 */
class BackfillWarrantyMonths implements DataPatchInterface
{
    private const BATCH_SIZE = 500;
    private const DEFAULT_WARRANTY_MONTHS = 24;

    public function __construct(
        private readonly ModuleDataSetupInterface $moduleDataSetup
    ) {
    }

    /**
     * Applies the backfill in batches to avoid table locks on large catalogs.
     *
     * @return void
     */
    public function apply(): void
    {
        $connection = $this->moduleDataSetup->getConnection();
        $table = $this->moduleDataSetup->getTable('mironsoft_product_warranty');
        $productTable = $this->moduleDataSetup->getTable('catalog_product_entity');

        $lastEntityId = 0;
        do {
            $select = $connection->select()
                ->from(['e' => $productTable], ['entity_id'])
                ->joinLeft(['w' => $table], 'w.entity_id = e.entity_id', [])
                ->where('w.entity_id IS NULL')
                ->where('e.entity_id > ?', $lastEntityId)
                ->order('e.entity_id ASC')
                ->limit(self::BATCH_SIZE);

            $entityIds = $connection->fetchCol($select);
            foreach ($entityIds as $entityId) {
                $connection->insert($table, [
                    'entity_id' => $entityId,
                    'warranty_months' => self::DEFAULT_WARRANTY_MONTHS,
                ]);
                $lastEntityId = (int) $entityId;
            }
        } while (count($entityIds) === self::BATCH_SIZE);
    }

    /**
     * @return string[]
     */
    public static function getDependencies(): array
    {
        return [];
    }

    /**
     * @return string[]
     */
    public function getAliases(): array
    {
        return [];
    }
}

#!/usr/bin/env bash
# Generate the declarative schema diff and verify it before applying
set -euo pipefail

# Show pending schema changes without applying them
bin/magento setup:db:status

# Recreate the whitelist after adding a new table or column
bin/magento setup:db-declaration:generate-whitelist --module-name=Mironsoft_ProductWarranty

# Apply schema changes and run data patches
bin/magento setup:upgrade

# Verify affected row count before and after the data patch runs
bin/mysql -e "SELECT COUNT(*) AS total, SUM(warranty_months IS NULL) AS still_null FROM mironsoft_product_warranty;"

{
    "mironsoft_product_warranty": {
        "column": {
            "entity_id": true,
            "warranty_months": true
        },
        "constraint": {
            "PRIMARY": true,
            "MIRONSOFT_WARRANTY_PRODUCT_ENTITY_ID_CPE_ENTITY_ID": true
        }
    }
}

7. Rollback-Strategie: Backups, reversible Patches und Dry-Runs

Die deklarative Schema-Verwaltung kann eine Spalte beim Entfernen aus db_schema.xml zwar wieder aus der Datenbank entfernen, stellt aber niemals automatisch die zuvor gespeicherten Daten wieder her. Ein „Rollback" auf Schema-Ebene ist also kein Rollback der Daten, sondern nur der Struktur. Deshalb gehört vor jeder Migration, die Produktionsdaten verändert, ein vollständiges Datenbank-Backup mit mysqldump oder eine Snapshot-Kopie des Datenbank-Volumes zum Pflichtprogramm, unabhängig davon, ob die Änderung von einem Menschen oder mit KI-Unterstützung entworfen wurde.

Für Data Patches empfiehlt sich zusätzlich, die Migration selbst reversibel zu gestalten: alte Werte vor dem Überschreiben in eine temporäre Sicherungsspalte oder Sicherungstabelle kopieren, statt sie direkt zu überschreiben. So lässt sich im Fehlerfall gezielt zurückrechnen, ohne das komplette Backup einspielen zu müssen. Ein Dry-Run auf einer Staging-Kopie, bei dem die Anzahl betroffener Zeilen vor der eigentlichen Ausführung geloggt und mit der Erwartung verglichen wird, deckt die meisten Fehlannahmen auf, bevor sie die Produktionsdatenbank erreichen.

#!/usr/bin/env bash
# Backup before migration, plus rollback procedure if verification fails
set -euo pipefail

# 1. Full backup before any schema or data change touches production
bin/mysqldump --single-transaction --routines --triggers magento > "backup-$(date +%Y%m%d-%H%M%S).sql"

# 2. Dry-run on a staging copy first, log the affected row count
bin/mysql staging_db -e "SELECT COUNT(*) FROM catalog_product_entity WHERE entity_id NOT IN (SELECT entity_id FROM mironsoft_product_warranty);"

# 3. If verification fails after deploy, restore from the backup
bin/mysql magento < backup-20260712-090000.sql

# 4. Schema-only rollback: remove the table definition and regenerate the whitelist
# (does NOT restore data - the backup above is the actual safety net)
bin/magento setup:db-declaration:generate-whitelist --module-name=Mironsoft_ProductWarranty
bin/magento setup:upgrade

8. Testing-Pipeline: Staging-Kopie, Vergleich und Verifikation

Eine belastbare Testing-Pipeline für Datenbank-Migrationen beginnt mit einer aktuellen, anonymisierten Kopie der Produktionsdatenbank auf einer Staging-Umgebung, nicht mit einer kleinen Testdatenbank mit ein paar Beispielzeilen. Nur an einer realistischen Datenmenge zeigen sich Probleme wie fehlende Indizes, unerwartete NULL-Werte oder Laufzeitprobleme bei großen Tabellen zuverlässig. bin/magento setup:upgrade wird zunächst auf Staging ausgeführt, gefolgt von gezielten SQL-Abfragen, die Zeilenanzahl, Wertebereiche und Stichproben vor und nach der Migration vergleichen.

Automatisierte Tests ergänzen die manuelle Prüfung, ersetzen sie aber nicht vollständig. Ein Integrationstest kann prüfen, ob die neue Spalte existiert und den erwarteten Typ hat, aber nicht, ob die migrierten Werte fachlich korrekt sind. Deshalb gehört zur Verifikation immer auch eine stichprobenartige manuelle Prüfung durch jemanden, der die fachliche Bedeutung der Daten versteht, kombiniert mit einem Vergleich der Gesamtsummen oder Prüfsummen vor und nach der Migration, um systematische Fehler frühzeitig zu erkennen.

9. KI-Unterstützung im Vergleich: Aufgabe, Risiko, Kontrollaufwand

Nicht jede Migrationsaufgabe birgt dasselbe Risiko, und der nötige Kontrollaufwand sollte sich danach richten. Die folgende Übersicht ordnet typische Aufgaben nach dem Risiko, das ein unkritisch übernommener KI-Vorschlag bei Produktionsdaten mit sich bringt.

Auffällig ist, dass strukturell einfache Änderungen wie eine zusätzliche nullable Spalte tatsächlich ein geringes Risiko tragen und sich mit überschaubarem Aufwand prüfen lassen, während Datenmigration, Fremdschlüssel-Änderungen und das Entfernen von Spalten oder Tabellen einen deutlich höheren Kontrollaufwand rechtfertigen. Eine pauschale Regel „KI-Vorschläge immer manuell testen" ist richtig, aber die Tiefe dieser Prüfung sollte mit dem tatsächlichen Risiko der jeweiligen Aufgabe skalieren.

10. Zusammenfassung

Datenbank-Migrationen mit KI-Unterstützung lösen ein reales Problem: Der Entwurf eines db_schema.xml-Diffs oder eines Data Patches aus einer fachlichen Beschreibung geht mit Claude deutlich schneller als das manuelle Nachschlagen von Attribut-Syntax und Whitelist-Konventionen. Besonders bei zweistufigen Migrationen, etwa einer nullable Spalte gefolgt von einem Backfill-Patch und späterem NOT-NULL-Constraint, liefert ein gut formulierter Prompt einen soliden Ausgangspunkt.

Der entscheidende Punkt bleibt aber die manuelle Verifikation. Kein KI-Modell kennt die reale Datenverteilung, alle historisch gewachsenen Abhängigkeiten oder die tatsächliche Tabellengröße in Produktion. Backup vor der Migration, Dry-Run auf einer aktuellen Staging-Kopie, Code-Review durch eine Person mit Projektkenntnis und ein klarer Rollback-Plan gehören deshalb zu jeder Migration, die Produktionsdaten berührt, unabhängig davon, wie überzeugend der KI-Vorschlag wirkt.

11. FAQ: Datenbank-Migrationen mit KI-Unterstützung