Schemaänderungen und Migrationen #

Diese Seite richtet sich an Ingenieure, die im Kernel, in einer Erweiterung oder in einer einzelnen Site eine Tabelle, eine Spalte oder einen Index hinzufügen oder ändern und diese Änderung auf jede Installation auf dieselbe Weise bringen müssen. Sie ist der Überblick: Sie sagt, welches der drei Werkzeuge Sie nehmen, wie jedes angewendet wird, und verlinkt die Anleitung, das Rezept und die Referenz zu jedem.

Inhalt #

1. Drei Wege, auf denen ein Schema eine Installation erreicht
2. Was Sie nehmen
3. Die beteiligten Dateien
4. Wie eine Installation eine Änderung anwendet
5. Migrationen für die eigenen Änderungen einer Site
6. Testen, Prüfen und Ausliefern
7. Die Werkzeuge
8. Checkliste für eine Schemaänderung
9. Bekannte Lücken
10. Verwandte Seiten

Drei Wege, auf denen ein Schema eine Installation erreicht #

Eine Änderung im Kernel oder in einer Erweiterung braucht meist die ersten beiden: die .dba-Änderung, damit neue Installationen sie haben, und einen Upgrade-Schritt, damit bestehende sie bekommen. Die Änderung einer Site braucht nur eine Migration. Die Upgrade-Schritte stehen auch unter den Migrationen, als Migrationen der Quelle kernel, und ein Migrationslauf führt die ausstehenden der Stufen database und scripts zuerst aus; eine Migration der Site nennt einen Schritt, den sie braucht, in requires: (Die Schritte unter den Migrationen).

Was Sie nehmen #

Der ausführliche Vergleich: Upgrade-Schritt oder Migration?.

Die beteiligten Dateien #

Die Update-Dateien für Oracle liegen in ezoracle; MongoDB hat keine, weil es kein SQL-Schema hat.

Wie eine Installation eine Änderung anwendet #

Seit 6.0.15 erledigen zwei Befehle die Arbeit, beide unter derselben Sperre der Installation und mit denselben Sicherungspunkten:

./console exp:upgrade --apply              # the kernel's and the extensions' upgrade steps, all stages, then deploy
./console exp:migration:migrate --apply    # pending database and scripts steps, then the site's migrations

exp:upgrade nimmt einen Sicherungspunkt, wendet jeden ausstehenden Upgrade-Schritt auf jeder Engine an, hält jeden fest und stellt bereit (Upgrade mit der Konsole). exp:migration:migrate nimmt einen Sicherungspunkt, führt die ausstehenden Migrationen der Reihe nach aus, jede in einer Transaktion, wo die Engine eine hat, stellt nach einem Fehler den Sicherungspunkt wieder her und committet, taggt und pusht die Aufzeichnung des Laufs (Migrationen).

Von Hand, wie vor 6.0.15 (Kompatibilität, Releases und Bereitstellung):

1. Sichern Sie Dateien und Datenbank.
2. Bringen Sie den neuen Code an seinen Platz, erzeugen Sie die Klassenzuordnungen neu und leeren Sie alle Caches; laden Sie PHP-FPM neu und starten Sie Velocity neu.
3. Wenden Sie die Datenbankaktualisierung einmal, vollständig, der Reihe nach an: die Datei in update/database/<driver>/6.0/, dann die Skripte in update/common/scripts/6.0/, die die Upgrade-Anleitung nennt.
4. Führen Sie die Upgrade-Prüfung aus: Setup > System Upgrade, Überprüfe Datenbankkonsistenz vergleicht die Tabellen mit den Schemadateien (Die Upgrade-Prüfung).

Die Update-Datei muss sagen, wie auf einer Datenbank vorzugehen ist, die bereits einen Teil davon hat; bei der Datei für 6.0.15 schlägt eine Anweisung für eine vorhandene Spalte mit deren Namen fehl, und nur diese Anweisung wird übersprungen. Ein Team, das von solchen Dateien zu Migrationen wechselt: Umstieg von SQL-Update-Dateien.

Migrationen für die eigenen Änderungen einer Site #

Eine Migration ist eine PHP-Klasse mit plan() (was sie ändern würde, für den Probelauf), up() (die Änderung) und, wo es geht, down() (der Weg zurück) und detect() (der Zustand, bei der Installation erfragt). Tabellen werden auf jeder Engine aus einer Definition im .dba-Format mit expKernelTableSchema::install() angelegt; Spalten und Indizes über den Schema-Handler der Engine, wie es expUpgradeSchemaStep des Kernels tut. Beginnen Sie mit dem Tutorial, dann PHP-Migrationen.

Die Entwurfsregeln: eine Änderung je Migration; Dinge über Namen oder Remote-ID finden, nie über eine numerische ID; nur anlegen, was fehlt, damit eine Migration auf jeder Installation sicher ist, die sie nicht aufgezeichnet hat; nie eine Migration bearbeiten, die irgendwo gelaufen ist (die Prüfsummen-Sperre lehnt sie ab); Geheimnisse heraushalten (das Laufprotokoll wird committet). Mehr dazu: Migrationen für Softwareingenieure.

Testen, Prüfen und Ausliefern #

Die Werkzeuge #

./console exp:upgrade:status               # every upgrade step and its state
./console exp:migration:status             # every migration (and step) and its state
./console exp:migration:check              # the lint of migration files, for CI
./console exp:migration:dry-run --simulate --diff   # run them in a transaction that is rolled back (PostgreSQL, SQLite)
php bin/php/ezsqldumpschema.php --help     # dump a database schema to a .dba file
php bin/php/ezsqlinsertschema.php --help   # load a .dba schema into an engine (--type)
php bin/php/ezsqldiff.php --help           # compare two schemas

Jeder Migrationsbefehl: Befehle. Eine .dba-Änderung anhand ihres Diffs zu prüfen ist irreführend: Zeilen liegen in einem numerisch geschlüsselten Array, das Entfernen einer Zeile nummeriert also jede Zeile danach neu. Vergleichen Sie stattdessen das Schema, das die Dateien ergeben, zum Beispiel mit ezsqldiff.php oder einem Test, der die Datei in eine Wegwerf-SQLite-Datenbank lädt (Schema und dba-Dateien).

Checkliste für eine Schemaänderung #

• To do: Die Änderung steht in share/db_schema.dba (und db_data.dba für Ausgangszeilen) des Kernels oder der Erweiterung, damit eine neue Installation sie hat; eine Änderung nur einer Site braucht keine .dba.
• To do: Bestehende Installationen bekommen sie: ein Upgrade-Schritt, der sie auf jeder Engine anwendet und erkennt (detect()), sodass exp:upgrade sie festhält und ein zweiter Lauf nichts ändert; oder, für eine Site, eine Migration.
• To do: Eine Migration nutzt $context->db() und die Schema-Handler, läuft auf jeder Engine, auf der die Site laufen kann (oder nennt sie in engines:), und legt nur an, was fehlt.
• To do: Für jeden Treiber mit SQL existiert eine Update-Datei, wenn Installationen von Hand aktualisiert werden: MySQL/MariaDB, PostgreSQL, SQLite und Oracle in ezoracle.
• To do: MongoDB ist abgedeckt: Der Adapter oder der Installer legt an, was der Code braucht.
• To do: Die Aktualisierung ist auf einer Datenbank sicher, die bereits einen Teil davon hat.
• To do: Eine Persistenzklasse (eZPersistentObject) beschreibt eine neue Tabelle.
• To do: Neue Tabellen verwenden das Präfix exp; Spalten, die ez-Tabellen hinzugefügt werden, behalten deren Stil (Regeln zu Schichtung und Benennung).
• To do: ./console exp:migration:check besteht, und die Migration wurde auf einer Kopie simuliert oder ausgeführt.
• To do: Das Changelog führt sie unter Added oder Updated, und die Upgrade-Hinweise in doc/eng-us/bc/6.0/ sagen, was auszuführen ist (Changelogs und Upgrade-Hinweise).
• To do: Die CI-Datenbankjobs (MySQL 8.0 und PostgreSQL 15) bestehen.

Bekannte Lücken #

• Eine Installation, die von Hand mit den SQL-Updatedateien aktualisiert wurde, hat keine Aufzeichnung, welche Anweisungen gelaufen sind; exp:upgrade hält jeden Schritt fest, den es anwendet, und exp:upgrade:verify findet Abweichungen.
• Migrationen werden in PHP, YAML, SQL oder INI geschrieben; eine Schemaänderung, die auf jeder Engine laufen muss, ist am besten ein Schritt schema (Migrationen: SQL und Einstellungen).
• Die Simulation läuft nur auf PostgreSQL und SQLite; auf MySQL/MariaDB, Oracle und MongoDB wird der Plan gelistet.
• MariaDB und Oracle haben im Kernel-Repository keinen CI-Job.

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
• Das Dateiformat, Die Funktion
• Wenn eine Migration scheitert, Fehlermeldungen
• Migrationen oder Umzug einer Site
• Persistenz und die Datenbankschicht
• Datenbankschema und dba-Dateien
• Aktualisieren, Upgrade mit der Konsole, Upgrade-Schritte für Erweiterungen
• Softwareingenieure: hier beginnen
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.