wiki/e-compliance/Prozesse/20260528_datenbank-handling.md

Datenbank-Handling: Exports, Imports, Backups & Datensicherung

Dieses Dokument beschreibt, wie die PowerOn-Plattform ihre Datenbanken verwaltet — von der strukturierten Datensicherung über flexible Export- und Import-Werkzeuge bis hin zur sicheren Wiederherstellung.

---

1. Datenbankübersicht

Die Plattform betreibt 13 separate Datenbanken auf dem Datenbankserver db.poweron.swiss. Jede Datenbank gehört einem fachlichen Bereich:

Datenbank	Inhalt
poweron_app	Benutzer, Mandate, Berechtigungen, Features — Kern der Plattform
poweron_management	Workflows, Prompts, Verbindungen (Connections)
poweron_billing	Abonnements, Rechnungen, Stripe-Daten
poweron_chat	Chat-Konversationen und Nachrichten
poweron_chatbot	Chatbot-Feature: Konversationen, Logs
poweron_knowledge	RAG-Wissensdatenbank, Dokumentenindizes
poweron_workspace	Workspace-Daten
poweron_trustee	Treuhand-spezifische Daten
poweron_realestate	Immobilien-Daten
poweron_commcoach	CommCoach-Feature
poweron_neutralization	Content-Neutralisierung
poweron_teamsbot	Microsoft Teams Bot
poweron_test	Testdaten (wird bei Exports ausgeschlossen)

---

2. Export

Ein Export erstellt eine vollständige Kopie aller Daten in einem lesbaren JSON-Format. Er dient als Grundlage für Backups, Migrationen zwischen Umgebungen (z. B. Prod → Int) und als Sicherungspunkt vor grösseren Änderungen.

2.1 Export via Admin-UI (empfohlen)

Im SysAdmin-Bereich der Plattform gibt es einen integrierten Export-Button. Er erzeugt eine JSON-Datei, die direkt heruntergeladen wird.

• Zugriff: Nur für SysAdmins (höchste Berechtigungsstufe)
• Umfang: Alle Datenbanken oder einzelne auswählbar
• Dateiname: migration_backup_YYYY-MM-DD_HH-MM.json
• Rate-Limit: Max. 2 Exports pro Minute (Schutzmassnahme gegen versehentliche Mehrfachausführung)

Auch sehr grosse Datenbanken werden sicher übertragen, ohne dass der Server dabei überlastet wird.

2.2 Export via Script (für Entwickler / Server-Zugriff)

Direkt auf dem Server kann das Export-Script ausgeführt werden:

ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current
source .venv/bin/activate

# Alle Datenbanken exportieren
python scripts/script_db_export_migration.py --pretty

# Nur bestimmte Datenbanken
python scripts/script_db_export_migration.py --db poweron_app,poweron_management

# Ohne Metadaten (kleiner, für Archivierung)
python scripts/script_db_export_migration.py --exclude Token,AuthEvent

# Mit Zusammenfassung (zeigt Tabellen- und Zeilenanzahl)
python scripts/script_db_export_migration.py --summary

Das Script erstellt automatisch zwei Dateien:

• migration_export_TIMESTAMP.json — vollständige Daten
• migration_export_TIMESTAMP_structure.json — nur Tabellenstruktur, keine Daten

2.3 Was wird beim Export ausgeschlossen?

Aus Sicherheits- und Datenschutzgründen werden folgende Tabellen nie exportiert:

• Token (aktive Login-Sessions)
• AuthEvent (Login-Protokoll)
• poweron_test (Testdatenbank)

---

3. Import

Ein Import spielt einen zuvor erstellten Export wieder ein. Typische Anwendungsfälle:

• Wiederherstellung eines früheren Datenstands
• Migration zwischen Umgebungen (z. B. Produktionsdaten auf die Testumgebung übertragen)
• Initialisierung einer neuen Instanz

3.1 Zwei Import-Modi

Replace (Ersetzen): Löscht alle bestehenden Daten (ausser geschützte System-Objekte, siehe unten) und schreibt den Backup-Stand vollständig neu. Verwenden bei vollständiger Wiederherstellung.

Merge (Zusammenführen): Fügt nur Datensätze ein, die noch nicht existieren (anhand ID). Bestehende Daten bleiben unverändert. Verwenden wenn nur fehlende Daten ergänzt werden sollen.

3.2 Import via Admin-UI

1. JSON-Datei hochladen
2. Validation läuft automatisch (prüft Format-Version, Struktur, System-Objekte)
3. Import-Modus wählen: replace oder merge
4. Import starten — Ergebnis zeigt Anzahl eingespielter Datensätze pro Tabelle

Auch sehr grosse Backup-Dateien können problemlos importiert werden, ohne den Server zu überlasten.

3.3 Geschützte System-Objekte

Beim Import werden drei kritische Objekte nie gelöscht oder überschrieben, unabhängig vom Import-Modus:

• Root-Mandat
• Admin-Benutzer
• Event-Benutzer

Falls diese Objekte im Backup andere interne Kennungen hatten als in der Zielumgebung, passt das System alle betroffenen Verknüpfungen automatisch an. Das verhindert inkonsistente Daten nach dem Import.

3.4 Import via Script

ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current
source .venv/bin/activate
sudo systemctl stop gateway

# Import-Script (Pendant zum Export-Script)
# Datei übergeben, Modus wählen
python scripts/script_db_export_migration.py --help  # zeigt alle Optionen

sudo systemctl start gateway

---

4. Backups & Datensicherung

4.1 Backup-Strategie

Die Plattform verfügt über ein durchdachtes, mehrschichtiges Sicherungskonzept:

Infrastruktur-Ebene: Der Datenbankserver läuft auf der Infomaniak Public Cloud, die Snapshot-Funktionalitäten für Managed Databases bereitstellt.

Anwendungs-Ebene: Über die integrierte Admin-UI kann jederzeit ein vollständiger Export aller Datenbanken erstellt werden — on-demand, gezielt pro Datenbank oder als Gesamtexport. Die Backup-Dateien sind vollständig portabel und können auf jedem Speicher archiviert werden.

4.2 Empfohlene Backup-Praxis

Zeitpunkt	Aktion
Vor jedem Deployment	Export via Admin-UI, Datei lokal speichern
Vor Datenbank-Migrationen	Export erstellen und beschriftet archivieren
Wöchentlich	Export als Archiv-Backup ablegen

---

5. Datenbankmigrationen (Struktur-Änderungen)

Wenn sich das Datenmodell weiterentwickelt — z. B. durch neue Felder oder Tabellen — stellt die Plattform dedizierte Hilfsprogramme bereit, die Datenbankstruktur kontrolliert und sicher anzupassen:

Programm	Zweck
script_db_adapt_to_models.py	Passt die Datenbankstruktur automatisch an den aktuellen Code an (mit Vorschau-Modus ohne Änderungen)
script_db_audit_legacy_state.py	Analysiert den Datenbankzustand vor einem Bereinigungsschritt
script_db_migrate_*.py	Datenmigrations-Programme für spezifische Features
script_db_init_automation2.py	Erstellt die Datenbankstruktur für das Automation-Feature
script_db_init_chatbot.py	Erstellt die Datenbankstruktur für das Chatbot-Feature

Beim Start der Anwendung prüft die Plattform ausserdem automatisch, ob alle benötigten Tabellen vorhanden sind, und legt fehlende selbstständig an.

---

6. Datenschutz-Hinweise

• Export-Dateien enthalten alle Kundendaten (Mandate, Benutzer, Chats, Dokumente, etc.) und sind entsprechend zu behandeln
• Dateien dürfen nicht auf unsicheren Speichern (persönliche Dropbox, E-Mail, etc.) abgelegt werden
• Export-Dateien sollten nach Nutzung gelöscht werden wenn sie nicht mehr benötigt werden
• Der Zugriff auf Export/Import ist auf SysAdmins beschränkt und wird serverseitig geloggt

---

Zusammenfassung: Datenbankoperationen im Überblick

Aufgabe	Wie
Fehlende Tabellen beim Start anlegen	Automatisch beim Plattform-Start
Datenbank-Export / Backup	Admin-UI (ein Klick) oder Entwickler-Script
Datenbank-Import / Wiederherstellung	Admin-UI mit geführtem Prozess oder Entwickler-Script
Infrastruktur-Snapshots	Infomaniak Cloud (Serverebene)
Struktur-Anpassungen bei Updates	Kontrolliert durch Entwickler-Hilfsprogramme
Datenbankpflege & Bereinigung	Admin-UI