Spezifikation: das Migrationsdateiformat #

Diese Seite ist die verbindliche Beschreibung einer Migrationsdatei von Exponential 6.0.15: der Dateiname, der Kopf, die PHP-Klasse, das YAML-Dokument mit seinen Schritten, Platzhaltern, Bedingungen und Schleifen, die ID-Zuordnung, die Prüfsumme, die Formate der Aufzeichnungsdateien, die ein Lauf schreibt (die Statusdatei und das Laufprotokoll), und die SQL- und INI-Migrationsdateien. Sie deckt ab, was der Kernel von 6.0.15 liest und schreibt. Die Anleitung ist Migrationen.

Version dieser Spezifikation: 1 (exp-migration/1, exp-migration-status/1, exp-migration-idmap/1).

Der Dateiname #

YYYYMMDDHHMMSS_<name>.<type>
YYYYMMDDHHMMSS_<name>.<engine>.sql
YYYYMMDDHHMMSS_<name>.mongodb.json

• Die ID ist der Dateiname ohne .<type> (und ohne .<engine>): 20261031120000_add_news_class.
• Dateien einer ID, die sich nur in der Engine unterscheiden (..._index.mysql.sql, ..._index.postgresql.sql und ein portables ..._index.sql), sind eine Migration mit einer Datei je Engine; die eigene Datei der Engine gewinnt, sonst die portable.
• Eine ID hat einen Typ: ein .php und ein .yml mit derselben ID sind ein Fehler.
• Eine Datei, deren Name nicht mit 14 Ziffern und _ beginnt, ist keine Migration und wird übersprungen (eine README, eine .gitkeep); eine, die so beginnt, aber eine Regel oben verletzt, ist ein Fehler.
• Nur die Dateien direkt in einem Migrationsordner werden gelesen; Unterordner nicht.
• Jeder Typ läuft: sql- und ini-Dateien laufen als YAML-Migration ihrer Schritte (die SQL-Migration, die INI-Migration). Eine portable .sql-Datei gilt für die SQL-Engines: Ohne .mongodb.json (oder engines im Kopf) läuft die Migration nicht auf MongoDB.

Der Kopf #

Der Kopf ist der Kommentarblock am Anfang der Datei, eine Zeile schlüssel: wert je Angabe, in der Kommentarsyntax der Datei. Für ihn werden höchstens die ersten 16 KiB einer Datei gelesen.

Der Kopf endet an der ersten Zeile, die kein Kommentar ist. Innerhalb davon ist eine Zeile, die kein kleingeschriebenes schlüssel: mit einem Wert ist, Fließtext und wird übergangen.

• Listen sind durch Kommas getrennt; ein Listenschlüssel darf sich wiederholen, und die Werte addieren sich.
• Ein Schlüssel, der nicht in der Tabelle steht, ist ein Fehler (damit ein vertippter nicht still durchgeht); ein Schlüssel, der keine Liste ist, zweimal angegeben, ist ein Fehler.
• environments: nur mit Namen läuft die Migration in diesen; nur mit !<name> überall außer in diesen; die Umgebung einer Installation ist site.ini [AdminEnvironment] Level, mit Level=auto die Variable EXP_ENV, oder das --environment des Befehls.

Beispiel (PHP):

<?php
// description: An index for the news list
// requires: 20261030090000_news_class, extension:expnews
// environments: staging, production
// engines: mysql, postgresql
// maintenance: no
// author: Site team
namespace MySite\Migrations;

Reihenfolge #

1. Nach ID: der Zeitstempel, dann der Name.
2. Eine Migration kommt nach jeder Migration, die sie in requires nennt, wohin deren Zeitstempel sie auch stellen.
3. Mit einer Umgebung bleiben nur die Migrationen, die in ihr laufen.

Fehler: eine zweimal definierte ID (die zuerst gefundene zählt; die Quellen werden in der Reihenfolge Site, Erweiterungen, Pakete durchsucht), eine Anforderung, die keine Migration nennt, eine Anforderung, die in der Umgebung nicht läuft, eine Anforderung extension:<name>, deren Erweiterung nicht aktiv ist, eine Migration, die sich selbst verlangt, und ein Zyklus. Eine Migration in einem Zyklus, oder eine, die auf einen wartet, bleibt am Ende der Reihenfolge, damit eine Liste sie noch zeigt. Solange ein Fehler da ist, läuft keine Migration.

Die PHP-Migration #

• Die Datei deklariert genau eine nicht abstrakte Klasse, die \expMigrationPhp erweitert. Keine andere Datei der Migrationen der Installation darf eine Klasse desselben Namens deklarieren.
• up( expMigrationContext $context ): string[] ist Pflicht; plan(), down(), detect() und transactional() sind frei (PHP-Migrationen).
• up() meldet einen Fehler, indem es wirft; es gibt die Zeilen dessen zurück, was es getan hat.
• detect() gibt done, pending, not-needed oder null zurück; null heißt, die Aufzeichnung entscheidet.

Die YAML-Migration #

Eine .yml-Datei wird mit symfony/yaml gelesen (^5.4 || ^6.4 || ^7.0; composer.json verlangt es, und migration.ini [YamlSettings] LibraryPath nennt eine Kopie außerhalb des Composer-vendor/). Ohne die Bibliothek wird jede YAML-Migration mit dem Installationshinweis abgelehnt. Gelesen wird nur einfaches YAML: Ein doppelter Schlüssel ist ein Fehler, !php/...-Tags werden abgelehnt, und ein Datum ohne Anführungszeichen ist kein Text (schreiben Sie '2026-11-01'). Der Kopf bleibt in den #-Kommentarzeilen am Anfang; als YAML-Schlüssel geschriebene Kopfschlüssel sind ein Fehler.

Das Dokument #

Das Dokument ist entweder die Liste der Schritte allein oder eine Zuordnung:

Jeder andere Schlüssel ist ein Fehler. Ein Dokument ohne Schritte ist gültig und tut nichts (eine Warnung in exp:migration:check).

# description: The languages of the news, checked before the import
steps:
    - type: reference
      set: { news_languages: [ eng-US, ger-DE ] }
    - foreach: "${ref.news_languages}"
      as: language
      steps:
          - type: assert
            that: { value: "${loop.language}", matches: "/^[a-z]{3}-[A-Z]{2}$/" }
down:
    - type: reference
      set: { news_languages: [] }

Ein Schritt #

Ein Schritt ist eine Zuordnung. Die Schlüssel, die die Engine liest:

Jeder andere Schlüssel gehört dem Schritttyp und wird gegen sein Schema geprüft: Unbekannte Schlüssel, fehlende Pflichtschlüssel, der Typ jedes Werts (string, int, number, bool, scalar, list, map, any, identifier, condition), die erlaubten Werte und Schlüssel eines anderen Modus sind Fehler. Ein Wert mit einem Platzhalter wird geprüft, wenn der Schritt läuft, nachdem der Platzhalter ersetzt ist; ein Schritttyp ergänzt eigene Prüfungen (expMigrationStepType::validate()). Die Standardwerte des Typs werden vor dem Lauf eingesetzt.

Ein Referenzname besteht aus Buchstaben, Ziffern und _ und beginnt nicht mit einer Ziffer. references: darf nur die Werte nennen, die das Schema des Schritttyps aufführt.

Schleifen #

Ein Schritt mit foreach oder while ist eine Schleife; er hat kein type.

In einer Schleife sind ${loop.<as>}, ${loop.<key>} und ${loop.index} (der Durchlauf, ab 0) gesetzt; eine verschachtelte Schleife sieht die Variablen der Schleifen um sie herum. Ein ${loop.<Name>}, das keine Schleife um ihn setzt, ist ein Fehler. Schleifen verschachteln höchstens 8 Ebenen tief.

Platzhalter #

${<Bereich>.<Name>[.<Schlüssel>...]} in einem Wert wird direkt vor dem Schritt ersetzt:

• Ein Wert, der nur aus einem Platzhalter besteht, behält den Typ dessen, wofür er steht (eine Zahl, eine Liste); in einem längeren Text wird der Wert hineingeschrieben (true/false für einen Wahrheitswert, nichts für null), und eine Liste oder Zuordnung ist dort ein Fehler.
• .<Schlüssel> geht in eine Liste oder Zuordnung hinein (${ref.node.id}, ${ref.list.0}).
• $${ ist ein wörtliches ${. Schlüssel von Zuordnungen werden nie ersetzt, nur Werte.
• Ein Platzhalter, der nichts benennt, lässt den Schritt scheitern. Im Probelauf bleibt er stehen, wie er geschrieben ist, und der Plan sagt, was erst beim Lauf der Migration entschieden wird.

Bedingungen #

if:, while: und das that: eines assert-Schritts nehmen eine Bedingung:

Operatoren: equals, not_equals (Zahlen und Zahlentexte werden als Zahlen verglichen), in, not_in (eine Liste), gt, gte, lt, lte (Zahlen), matches (ein PCRE-Muster mit seinen Begrenzern), empty (true oder false). Genau ein Operator je value.

Bezeichner und die ID-Zuordnung #

Ein Schlüssel vom Typ identifier nennt einen Knoten oder ein Objekt: eine Zahl (die ID), remote:<Remote-ID>, object-remote:<Remote-ID> (ein Knoten: der Hauptknoten dieses Objekts) oder path:<URL-Pfad> (path:media/images). IDs unterscheiden sich zwischen Installationen; eine Site hält die Namen ihrer IDs je Umgebung in <Repository>/idmap/<Umgebung>.json (default.json ohne Umgebung):

{
    "schema": "exp-migration-idmap/1",
    "ids": {
        "node": { "news": 1234, "media": "remote:media-root" }
    }
}

Arten und Namen bestehen aus Buchstaben, Ziffern, _ und -; ein Wert ist eine Zahl oder ein Bezeichnertext. Eine fehlende Datei ist eine leere Zuordnung; eine Datei, die keine ist, lässt jede YAML-Migration des Laufs scheitern.

Schritttypen #

Der Kernel registriert reference (set: eine Zuordnung von Referenzen), assert (that: eine Bedingung, message: der Text des Fehlers), content, location, content_version, content_class, content_class_group, user, user_group, role, section, language, object_state_group, tag, url_alias, trash, file, image, cache, search, autoload, layout, layout_block, layout_rule, http, mail und command; jeden Schlüssel jedes Typs nennt seine erzeugte Seite (die Schritttypen). Ein Bezeichner-Schlüssel nennt seine Art: node, object, class, section, language, user, role, state, class_group, state_group, tag oder url_alias; alle außer node, object und tag nehmen auch einen Namen (Bezeichner einer Klasse oder Sektion, eine Locale, ein Login, ein Rollenname, <gruppe>/<zustand>, der Name einer Klassengruppe, der Bezeichner einer Zustandsgruppe, die Adresse eines URL-Alias ab der Wurzel). Ein Tag wird über seine ID, remote:<Remote-ID> oder path:<Schlagwortpfad> genannt, und nur dort, wo die Erweiterung eztags installiert ist. Die Schritte file und image lesen ihre file: unterhalb des Ordners der Migrationsdatei. Die Caches, die jeder Schritt nennt, werden nach dem Lauf einmal geleert, und die Objekte, die die Schritte geändert haben, neu indiziert (Caches und der Suchindex). Die Layout-Schritte arbeiten nur, wo Exponential Layouts installiert ist; http, mail und command senden und starten in einem Probelauf nichts, und command führt nur die exp:*-Befehle der Positivliste aus (HTTP-Anfragen, E-Mails und Konsolenbefehle). Eine Erweiterung registriert ihre eigenen Schritttypen in ihrer migration.ini.append.php:

[StepSettings]
StepTypeList[news_import]=expNewsImportStep

Die Klasse implementiert expMigrationStepType (name(), schema(), validate(), caches(), plan(), apply(); expMigrationStepTypeBase hat die Standards). apply() gibt lines (was es getan hat) und values (was references: nehmen kann) zurück. Eine Klasse, die es nicht gibt, die einen anderen Namen nennt oder ein fehlerhaftes Schema hat, wird nicht registriert und ist ein Fehler jeder geprüften YAML-Migration.

Ausführen und zurücknehmen #

• up() führt die Schritte der Reihe nach aus; der erste, der scheitert, beendet die Migration mit seiner Stelle (steps[1].steps[0] (assert): ...), und die Transaktion der Migration wird zurückgerollt.
• plan() (der Probelauf) listet den Plan jedes Schritts; von einem reference-Schritt gesetzte Werte gelten für die Schritte danach, alles andere, was erst beim Lauf feststeht, wird so markiert.
• down() führt die down:-Schritte aus; ohne down: lässt sich eine Migration nur zurücknehmen, wenn der Typ jedes Schritts expMigrationRevertibleStepType implementiert und keiner eine Schleife ist: Dann läuft revert() jedes Schritts, der letzte zuerst, mit den Referenzen des Laufs, der zurücknimmt. reference und assert nehmen nichts zurück.

Die SQL-Migration #

Die Dateien einer ID (.sql, .<engine>.sql, .mongodb.json) sind eine Migration. Auf einer Engine läuft ihre eigene Datei, sonst die portable .sql (nur auf den SQL-Engines). Eine SQL-Datei besteht aus Anweisungen, die mit ; am Zeilenende enden; Zeilen, die mit -- beginnen, sind Kommentare; eine Zeile -- down (auch -- down:, gleich in welcher Schreibung) beendet die Anweisungen, die die Migration ausführen, und beginnt die, die sie zurücknehmen. Eine .mongodb.json-Datei ist eine JSON-Liste von Befehlen oder ein Objekt mit den Listen up und down (und description); ein Befehl ist ein Objekt mit einem von insert (documents), update (filter, set, unset), delete (filter), create_collection, drop_collection, create_index (keys, name, unique) und drop_index (name), dessen Wert die Collection ist. Die Migration ist die YAML-Migration steps: [ { type: sql, file: <id>.sql } ], mit down: [ { type: sql, file: <id>.sql, part: down } ], wenn eine Datei einen Down-Teil hat, und transactional aus dem Kopf. Die Prüfsumme ist die der Datei der Engine.

Die INI-Migration #

Eine INI-Datei, deren Blöcke ihre Datei nennen: [<file>.ini/<Block>] für settings/override/<file>.ini.append.php, [siteaccess:<name> <file>.ini/<Block>] für settings/siteaccess/<name>/<file>.ini.append.php (override oder global vor dem Dateinamen ist dasselbe wie nichts). In einem Block: Var=value setzt, Var[] gefolgt von Zeilen Var[]=value macht das Array zu diesen Werten, Var[]=value ohne Var[] davor fügt einen Wert hinzu, Var[key]=value setzt einen Schlüssel, und -Var, -Var[key], -Var[]=value entfernen. Zeilen, die mit # oder ; beginnen, sind Kommentare. Die Migration ist die YAML-Migration aus einem Schritt settings je Datei, in der Reihenfolge, in der die Dateien zuerst vorkommen; sie hat kein down:.

Die Prüfsumme #

Die Prüfsumme einer Migration ist der SHA-256 der Bytes ihrer Datei mit auf \n vereinheitlichten Zeilenenden (ein Checkout mit CRLF-Zeilenenden ergibt also dieselbe Prüfsumme), bei einer Migration mit einer Datei je Engine der Datei, die auf der Engine läuft, als kleingeschriebene Hex-Zeichenkette mit 64 Zeichen. Sie wird in exp_migration.checksum aufgezeichnet, wenn die Migration angewendet wird. Eine als done aufgezeichnete Migration mit abweichender Prüfsumme wird abgelehnt, es sei denn, der Lauf bekommt --force --reason=<text>.

Zustände und Aktionen #

Aktionen in einem Bericht: applied, would-apply, simulated, failed, not-run, blocked, refused, accepted, would-accept, undone, would-undo, restored, none.

Die Aufzeichnungstabellen #

exp_migration (Schlüssel: source + migration_id): source, migration_id, stage, version, state, started_at, finished_at, duration_ms, run_by, engine, checksum, message (höchstens 1000 Zeichen), file_path, environment, run_id, caption_id, revision. Quellen: site, extension:<name>, package:<name>, und kernel für die Schritte von exp:upgrade (Stufe code, libraries, database, scripts, finish) und ihre Sicherungspunkte (Stufe caption, migration_id caption:<id>).

exp_migration_run (Schlüssel: run_id): eine Zeile je Lauf mit seinem Zustand (running, done, failed, rolled-back), Zeiten, Benutzer, Umgebung, caption_pre, caption_post, commit_id, tag_name und push_state (pushed, pending, disabled, no-remote, none).

run_by ist cli <Systembenutzer> oder web <Systembenutzer>, nie ein Passwort. Eine Lauf-ID ist YYYYMMDD-HHMMSS-<6 hex>; jede ID aus Buchstaben, Ziffern, ., _ und - (höchstens 64, nicht mit einem Punkt beginnend) wird angenommen.

Die Statusdatei #

<repository>/status/<umgebung>.json, Schema exp-migration-status/1 (share/migration/schema/exp-migration-status-1.json):

Die Datei wird ganz und atomar geschrieben, sortiert, nur mit den Zeiten der Aufzeichnung, sodass dieselbe Aufzeichnung dieselben Bytes ergibt. Sie enthält nie run_by oder eine Meldung.

Das Laufprotokoll #

<repository>/runs/<run-id>.log, eine Zeile je Ereignis:

<UTC time, ISO 8601> <level> <text>
2026-11-01T02:30:20Z info applied 20261031120000_news_note_table in 3 ms: created exp_news_note | wrote the note 1

Stufen: debug, info, notice, warning, error. Bevor eine Zeile geschrieben wird, wird sie bereinigt von geheimen Werten, Zugangsdaten in URLs, Paaren password=..., Bearer-Tokens und E-Mail-Adressen. Dieselben Zeilen gehen mit der Lauf-ID davor nach var/log/migration.log.

Die Maschinenausgabe #

Jeder Befehl exp:migration:* mit --format=json gibt ein JSON-Objekt aus mit schema = exp-migration/1, command, mode (status, dry-run, simulate, apply, rollback, rollback-dry-run, check, generate, caption, ...), errors, warnings und exit, dazu, was der Modus meldet: run_id, environment, engine, transaction, user, migrations[] (id, source, state, action, detail, description, plan, messages, duration_ms, record, checksum, changed, ...), summary, captions, restore, repository, runs, orphans, pushes, lock. In späteren Versionen können Schlüssel hinzukommen; innerhalb von exp-migration/1 wird keiner umbenannt oder entfernt.

Aufgezeichnete Ereignisse (exp-migration-recording-event/1) #

Eine Aufzeichnung von Änderungen (die Anleitung) hält jede Änderung als ein Ereignis fest, den Inhalt einer Zeile von exp_migration_recording_event: ein JSON-Objekt in der Form des YAML-Schritts, für den es steht, so dass ein Generator den Schritt schreibt, ohne die Installation noch einmal zu lesen.

Das Ereignis nennt nie, wer die Änderung gemacht hat; die Zeile hält die Benutzer-ID (actor_id) nur für die Installation. Die Zeilen einer Aufzeichnung sortieren nach event_id (die Millisekunde, eine Folgenummer des Prozesses, fünf zufällige Hex-Ziffern) in der Reihenfolge der Änderungen.

Die Audit-Ereignisse, der Schritt, der aus jedem wird, und seine Schlüssel:

Ein Inhaltsobjekt einer Benutzerklasse wird als Schritt user aufgezeichnet. [RecordingSettings] EventList[] kann die Liste verkleinern, nie vergrößern. Innerhalb von exp-migration-recording-event/1 können Ereignisse und Schlüssel hinzukommen; keiner wird umbenannt oder entfernt.

Verwandte Seiten #

• Migrationen: der Einstieg, Alle Rezepte, Häufige Fragen
• Die Anleitung, das Tutorial, PHP-Migrationen, Zurücknehmen und Sicherungspunkte, Das Migrations-Repository
• In der Administration, Befehle, Einstellungen, Richtlinien, Ansichten und Ereignisse
• Die Funktion
• Wenn eine Migration scheitert, Fehlermeldungen
• Migrationen oder Umzug einer Site
• migration.ini
• Audit-Ereignismodell