Fixup-Skripte

Fixup-Skripte sind MongoDB-kompatible Skripte, die auf Datenbanken für Wartungs-, Migrations- und Datenkorrekturaufgaben angewendet werden können. Sie werden vom Bot-Dienst in einer definierten Reihenfolge ausgeführt und gewährleisten so konsistente und vorhersehbare Datenbankänderungen.

Fixup-Skripte werden typischerweise verwendet für:

• Datenbank-Upgrades: Migration der Datenstruktur aufgrund neuer Construction-Kit-Versionen
• Datenkorrekturen: Beheben inkonsistenter oder beschädigter Daten
• Datenanonymisierung: Entfernen oder Maskieren sensibler Informationen
• Bereinigungsoperationen: Entfernen veralteter oder ungültiger Daten
• Schema-Migrationen: Anpassen bestehender Daten an neue Datenmodelle

Skript-Struktur

Fixup-Skripte sind TypeScript-Dateien, die MongoDB-Shell-(mongosh)-kompatible Befehle enthalten. Die Skripte haben Zugriff auf die vollständige MongoDB-API und können jede beliebige Datenbankoperation durchführen.

Grundlegendes Skript-Beispiel

// MongoDB script for anonymizing email addresses and phone numbers
print("=== Starting Data Anonymization ===");

// Update customer email addresses
db.RtEntity_EnergyCommunityCustomer.updateMany(
    { "attributes.contact.attributes.email": { $exists: true, $ne: null } },
    {
        $set: {
            "attributes.contact.attributes.email": "test@meshmakers.io"
        }
    }
);

// Update phone numbers
db.RtEntity_EnergyCommunityCustomer.updateMany(
    { "attributes.contact.attributes.address.attributes.phone.attributes.number": { $exists: true, $ne: null } },
    {
        $set: {
            "attributes.contact.attributes.address.attributes.phone.attributes.number": "015199999001"
        }
    }
);

print("Anonymization completed");

Datenmigrations-Beispiel

// MongoDB Script: Migrate OperatingFacilities to correct tree structure
print("=== Starting Facility Migration ===");

// Get target tree structure
const targetTree = db.RtEntity_BasicNamedEntity.findOne({
    ckTypeId: "Basic/Tree",
    "attributes.name": "SBEG2"
});

if (!targetTree) {
    print("ERROR: Target tree not found!");
    exit;
}

// Get all facilities to migrate
const facilities = db.RtEntity_BasicNamedEntity.find({
    ckTypeId: "EnergyCommunity/OperatingFacility"
}).toArray();

let migratedCount = 0;

facilities.forEach((facility, index) => {
    // Perform migration logic
    const result = db.RtAssociation.updateOne(
        { originRtId: facility._id },
        { $set: { targetRtId: targetTree._id } }
    );
    
    if (result.modifiedCount > 0) {
        migratedCount++;
        print(`[${index + 1}] Migrated: ${facility.attributes.name}`);
    }
});

print(`Migration completed: ${migratedCount} facilities migrated`);

Skripte importieren

Fixup-Skripte werden mit dem octo-cli-Werkzeug importiert. Der Importvorgang registriert die Skripte im System und bereitet sie für die Ausführung vor.

Befehlssyntax

octo-cli -c createFixupScript -e true -n <script-name> -f <script-file> -o <order>

Parameter

Parameter	Description	Example
-c createFixupScript	Befehl zum Erstellen eines Fixup-Skripts	Erforderlich
-e true	Skript für die Ausführung aktivieren	true/false
-n <name>	Eindeutiger Name für das Skript	anonymize, fix-tree-nodes
-f <file>	Pfad zur Skriptdatei	./scripts/0_anonymize.ts
-o <order>	Ausführungsreihenfolge (Sequenz)	0, 1, 2

Beispiel für den Skript-Import

# Import multiple fixup scripts with proper sequencing
octo-cli -c createFixupScript -e true -n anonymize -f ./_fixup-scripts/0_anonymize.ts -o 0
octo-cli -c createFixupScript -e true -n fix-tree-nodes -f ./_fixup-scripts/1_fix_tree_nodes.ts -o 1
octo-cli -c createFixupScript -e true -n delete-old-tree-nodes -f ./_fixup-scripts/2_delete_old_tree.ts -o 2
octo-cli -c createFixupScript -e true -n cleanup-billings -f ./_fixup-scripts/4_cleanup_billings.ts -o 4

Skripte ausführen

Nach dem Import werden die Skripte vom Bot-Dienst ausgeführt mit:

octo-cli -c runFixupScripts -w

Das Flag -w aktiviert den Watch-Modus, mit dem Sie den Ausführungsfortschritt überwachen können.

Ausführungsverhalten

• Skripte werden in sequenzieller Reihenfolge basierend auf dem Parameter order ausgeführt
• Nur aktivierte Skripte (-e true) werden ausgeführt
• Skripte laufen nach Möglichkeit in einem einzigen Transaktionskontext
• Die Ausführung stoppt beim ersten Fehler, um die Datenintegrität zu wahren
• Der Bot-Dienst protokolliert alle Operationen zum Debuggen und Auditieren

Bewährte Vorgehensweisen

Namenskonvention

• Verwenden Sie aussagekräftige Namen, die den Zweck des Skripts angeben
• Nehmen Sie ein Reihenfolge-Präfix zur Verdeutlichung auf: 0_anonymize, 1_fix_tree_nodes
• Verwenden Sie kebab-case für Skriptnamen: fix-tree-nodes, cleanup-billings

Skript-Entwicklung

• Fügen Sie stets Logging mit print()-Anweisungen zur Fortschrittsverfolgung ein
• Fügen Sie Verifikationsabfragen hinzu, um zu bestätigen, dass Änderungen korrekt angewendet wurden
• Verwenden Sie nach Möglichkeit Transaktionen für Operationen über mehrere Collections hinweg
• Fügen Sie Fehlerbehandlung und frühe Abbruchbedingungen ein
• Testen Sie Skripte auf Entwicklungsdaten vor dem Produktiv-Deployment

Sequenzierung

• Planen Sie die Ausführungsreihenfolge sorgfältig – einige Skripte können von anderen abhängen
• Verwenden Sie sinnvolle Reihenfolge-Nummern: 0, 10, 20 (ermöglicht das Einfügen von Zwischenskripten)
• Gruppieren Sie zusammengehörige Operationen: 0-9 für Bereinigung, 10-19 für Migrationen usw.

Sicherheitsmaßnahmen

• Sichern Sie die Datenbank stets, bevor Sie Fixup-Skripte ausführen
• Testen Sie Skripte zuerst in einer Entwicklungsumgebung
• Verwenden Sie bedingte Logik, um Skripte nach Möglichkeit idempotent zu machen
• Fügen Sie Rollback-Verfahren für kritische Änderungen ein

warnung

Fixup-Skripte verändern den Datenbankinhalt direkt. Stellen Sie stets sicher, dass geeignete Backups vorhanden sind, bevor Sie sie ausführen – insbesondere in Produktivumgebungen.

tipp

Skripte sollten nach Möglichkeit idempotent sein, das heißt, sie können mehrfach ausgeführt werden, ohne Probleme oder doppelte Änderungen zu verursachen.