Datenmigrationen
Führt eine benannte Datenmigration aus, die mit einer Version ausgeliefert wird.
So funktioniert es
Manche Änderungen lassen sich nicht in SQL ausdrücken: Ereignisdaten in ein neues Binärformat umschreiben, Altdaten vereinheitlichen, abgeleitete Felder neu berechnen. Jede solche Änderung wird als programmierte Migration — eine Aufgabe — mit der Anwendung ausgeliefert.
Sie führen jeweils eine Aufgabe aus, nach Namen. Einen Modus „alles ausführen“ gibt es bewusst nicht: Alle Migrationen auf einmal auszuführen ist unbegrenzt und betrifft jeden Arbeitsbereich, und früher war das schon erreichbar, indem man ein Formularfeld leer ließ. Das Feld Aufgabe ist erforderlich, und seine Auswahlliste enthält genau die Aufgaben, die die installierte Version registriert.
Ein Lauf geht dann so vor:
- Standardmäßig als Vorschau — mit ausgeschaltetem Anwenden meldet die Aufgabe, was sie ändern würde, ohne etwas zu schreiben. Lesen Sie zuerst die Vorschau; dafür ist sie da
- Schreibt nur auf Ihre Anweisung — schalten Sie Anwenden ein, um die Änderungen zu speichern. Das Formular verlangt, dass Sie Mir ist bewusst, dass dabei Änderungen geschrieben werden, die nicht zurückgenommen werden können ankreuzen, bevor es abgeschickt werden kann, denn das Anwenden schreibt in jeden betroffenen Arbeitsbereich und lässt sich nicht zurücknehmen
- Baut optional Projektionen neu auf — eine Aufgabe, deren Änderungen die Projektionen übernehmen müssen, fordert das als Folgeschritt an. Nach Abschluss des Laufs wird Mitarbeitendenprojektionen neu aufbauen als neuer Lauf eingeplant. Er erscheint in der Liste der Jobausführungen als eigener Eintrag und startet erst, wenn der Migrationslauf abgeschlossen ist
Wann er läuft
Der Job wird manuell gesteuert. Er startet nie von selbst — weder nach Zeitplan noch beim Start der Anwendung. Starten Sie ihn bei Bedarf unter . Er kann nur aus dem Systemarbeitsbereich ausgeführt werden und wird in keinem anderen Arbeitsbereich aufgeführt.
Er startet nicht automatisch, weil sonst jede laufende Instanz der Anwendung ihren eigenen Lauf einplanen würde, und mehrere Läufe, die gleichzeitig dieselben Daten ändern, verlangsamen die Datenbank.
Parameter
| Parameter | Erforderlich | Bedeutung |
|---|---|---|
| Aufgabe | Ja | Die auszuführende Migration, ausgewählt aus den registrierten Aufgaben. Ein Lauf ohne Aufgabe wird abgelehnt, bevor irgendeine Arbeit beginnt, ebenso ein Name, der nicht registriert ist |
| Anwenden (Standard aus = Probelauf bei Migrationen, die das unterstützen) | Nein | Aus (Standard) zeigt eine Vorschau ohne zu schreiben, bei Aufgaben, die einen Probelauf unterstützen; Aufgaben, die immer anwenden, ignorieren die Option. Ein speichert die Änderungen, was nicht rückgängig gemacht werden kann |
| Mitarbeitende (optional, eine Migration auf eine Person eingrenzen) | Nein | Grenzt eine Aufgabe auf eine einzelne Person ein — nützlich, um sie an einer Person auszuprobieren, bevor sie für alle ausgeführt wird. Aufgaben, die immer alles abdecken, ignorieren die Option |
Die programmatische API akzeptiert dieselben Optionen und zusätzlich workspace_id, um eine Aufgabe auf einen Arbeitsbereich einzugrenzen; im Startformular gibt es keine Auswahl des Arbeitsbereichs.
{"jobs":["migrations"],"options":{"tasks":["<task-name>"]}}
{"jobs":["migrations"],"options":{"tasks":["<task-name>"],"apply":true}}Die Optionen eines Laufs werden in der Spalte Parameter der Liste angezeigt, die standardmäßig ausgeblendet ist — schalten Sie sie im Spaltenmenü ein, um zwei Läufe desselben Jobs zu unterscheiden.
Jobergebnisse
Das Ergebnis enthält dry_run (das Gegenteil von Anwenden) und einen Schlüssel pro ausgeführter Aufgabe:
| Schlüssel | Bedeutung |
|---|---|
dry_run | true, wenn nichts geschrieben wurde — der Lauf war nur eine Vorschau |
applied | Ob diese Aufgabe ihre Änderungen tatsächlich geschrieben hat |
affected_count | Wie viele Elemente die Aufgabe geändert hat oder ändern würde |
by_workspace | Anzahlen pro Arbeitsbereich, mit Namen der Arbeitsbereiche |
details | Die betroffenen Elemente, mit den Vorher-/Nachher-Angaben, die die Aufgabe festhält |
Ein Name, der keine registrierte Aufgabe ist, erscheint als "unknown task" bei diesem Namen.
Läuft eine Aufgabe, die als „baut Projektionen neu auf“ gekennzeichnet ist, enthält das Ergebnis zusätzlich next_jobs: ["rebuild-employee-projections"], und dieser Job wird automatisch eingeplant.
Erneut ausführen
Jede registrierte Aufgabe kann bei Bedarf erneut ausgeführt werden. Jede Aufgabe lässt bereits migrierte Daten aus. Ein erneuter Lauf nach einem Teilerfolg macht also dort weiter, wo der vorherige aufgehört hat, und ein erneuter Lauf einer abgeschlossenen Aufgabe ändert nichts und meldet keine betroffenen Elemente.
Fehlerbehebung
| Problem | Lösung |
|---|---|
| „Keine Aufgabe ausgewählt“ | Wählen Sie eine Aufgabe im Feld Aufgabe. Es gibt keinen Modus „alles ausführen“ — die Aufgabe zu benennen ist die einzige Möglichkeit, diesen Job auszuführen |
Der Lauf meldet "unknown task" | Der Name ist in der installierten Version nicht registriert — meist eine Aufgabe, die inzwischen entfernt wurde. Wählen Sie aus der Liste, statt einen Namen einzutippen |
| Job ausführen bleibt deaktiviert | Anwenden ist eingeschaltet und die Bestätigung darunter wurde nicht angekreuzt. Lesen Sie die Warnung und kreuzen Sie das Kästchen an, oder schalten Sie Anwenden wieder aus, um stattdessen eine Vorschau zu sehen |
affected_count ist 0 | Die Aufgabe hat keine ausstehenden Zeilen — der Normalzustand, sobald sie abgeschlossen ist |
| Fehler während einer Aufgabe | Öffnen Sie die Details des Laufs. Fehler einzelner Zeilen werden angezeigt; scheitert der ganze Lauf, liegt meist ein schwerwiegendes Problem vor. Korrigieren Sie die Daten und führen Sie ihn erneut aus |
| Der Folgeschritt zum Neuaufbau der Projektionen lief nicht | Wurde der Lauf nicht abgeschlossen (er ist auf halbem Weg fehlgeschlagen), wird der Folgeschritt nicht eingeplant. Beheben Sie den Fehler, führen Sie die Aufgabe erneut aus und starten Sie bei Bedarf Mitarbeitendenprojektionen neu aufbauen manuell |