Datenbank-Migration

Diese Anleitung beschreibt den Prozess der PostgreSQL-Datenbankmigration für das charly-System mit dem Befehl charly-server db-migration. Sie umfasst die Vorbereitung, Durchführung und Verifizierung der Migration sowie spezielle Hinweise zu Benutzerinteraktionen und Fehlerbehebung.

1. Übersicht

Die db-migration Funktion führt ein In-Place-Update der PostgreSQL-Datenbank durch. Das bedeutet, die bestehende PostgreSQL-Installation wird gesichert, eine neue Version (aktuell PostgreSQL 16, bzw. 13 auf Windows Server 2016) wird installiert und die Daten werden in die neue Instanz importiert, ohne Änderung des Installationspfad oder des PostgreSQL Port.

Wichtige Hinweise:

Voraussetzung: Die bestehende PostgreSQL-Installation muss Version 9.4 oder höher sein.
Empfehlung: Für Systeme, welche geeignet sind (siehe charly-server check-system), oder wenn ein Serverumzug geplant ist, wird dringend ein Container-Update empfohlen. Das Container-Update bietet eine modernere und isolierte Umgebung für den charly-Server.
Dauer: Der Prozess kann je nach Datenbankgröße und Systemleistung zwischen 10 und 50 Minuten dauern. Planen Sie die Migration außerhalb der Praxiszeiten (da charly während der Migration nicht zur Verfügung steht).
Interaktivität: Die Migration erfordert eine lokale PowerShell-Sitzung mit Administratorrechten und GUI-Zugriff, da der PostgreSQL-Installer eine grafische Oberfläche benötigt. Remote- oder nicht-interaktive Sitzungen werden nicht unterstützt.

2. Kurzanleitung & Ablauf

Der Migrationsprozess läuft größtenteils automatisch ab, erfordert jedoch an einigen Stellen Benutzerinteraktion. Folgendes Diagramm stellt den Ablauf der Migration dar:

Hinweis: Für eine visuelle Darstellung des Migrationsprozesses, siehe das Flussdiagramm PostgreSQL Migrationsablauf

PostgreSQL Migrationsablauf

Migrationsschritte im Überblick:

Schritt	Beschreibung	Benutzer- interaktion
1. Start	`charly-server db-migration` ausführen
2. Konfiguration bestätigen	Anzeige erkannter Einstellungen	✓
3. Vorherige Ergebnisse	Optional: Nutzung vorheriger Prüfungsergebnisse	✓
4. Prüfungen	Disk, Bloat, TOAST-Prüfungen werden durchgeführt
5. Datenexport	Datenbanken werden exportiert
6. Backup	Der alte PostgreSQL-Installationsordner wird gesichert
7. Installation	Neue PostgreSQL-Version wird installiert
8. Datenimport	Exportierte Daten werden in neue Instanz importiert
9. Verifizierung	Datenintegrität wird überprüft
10. Konfiguration	Übernahme der alten Einstellungen oder alternativer Ansatz	✓
11. pgTune-Wizard	Optional: Leistungsoptimierung mit pgTune	✓
12. pgAdmin	Optional: Installation von pgAdmin 4	✓
13. Abschluss	Migration abgeschlossen

Schritte mit Benutzerinteraktion sind mit ✓ gekennzeichnet.

Interaktive Schritte:

Konfigurationsbestätigung: Zu Beginn werden die erkannten Einstellungen angezeigt.
Wiederverwendung vorheriger Ergebnisse (Optional): Wenn die Migration bereits zuvor gestartet wurde, fragt das Skript für bestimmte Schritte (z.B. BloatCheck, TOASTErrorCheck), ob die Ergebnisse der letzten Durchläufe (innerhalb eines Zeitfensters) wiederverwendet werden sollen. Dies kann Zeit sparen, wenn ein vorheriger Lauf abgebrochen wurde.
Übernahme alter Konfiguration / pgTune: Nach dem Datenimport wird gefragt, ob Einstellungen (max_connections, shared_buffers etc.) aus der alten postgresql.conf übernommen werden sollen. Alternativ kann der pgTune-Wizard gestartet werden, um Empfehlungen basierend auf der Systemhardware zu erhalten und anzuwenden.
pgAdmin Installation: Am Ende wird optional die Installation von pgAdmin 4 angeboten. Dies erfordert eine Benutzerbestätigung im grafischen Installer.

3. Detaillierte Beschreibung mit Beispielausgabe

Hier ist ein Beispiel für den Ablauf des charly-server db-migration Befehls mit Erläuterungen:

PS C:\WINDOWS\system32> charly-server db-migration
Charly Server Version: 2.2.7
Charly Server Environment: release # oder 'vorabversion'
Native Installation

Aktuelle Konfiguration:
====================
Befehl: db-migration
Solutio Path: C:\Solutio
Export Path: C:\solutio_export # Temporärer Pfad für den Export

PostgreSQL Konfiguration: # Erkannte aktuelle Konfiguration
Path: C:\Solutio\Server\PostgreSQL
Host: 192.168.2.40
Port: 5432
Username: postgres
Service Name: Solutio_PostgreSQL
Version: 9.4.6 # Beispiel für eine ältere Version

Ist die Konfiguration korrekt? (Ja/Nein) [Ja]: # Erste Benutzerinteraktion
[2025-04-27 09:16:39] [INFO] Starting database migration process...

# --- Phase: Vorprüfungen ---
# Optional: Wiederverwendung des Gesamtstatus (falls Migration schon lief)
Moechten Sie die Ergebnisse der vorherigen Durchlaeufe fuer DatabaseMigration verwenden? (Ja/Nein) [Nein]: n
# Erläuterung: Wenn Sie hier 'Ja' wählen, werden Schritte, die im letzten Lauf (innerhalb 24h) erfolgreich waren, übersprungen.

[2025-04-27 09:17:11] [INFO] Starting MigrationBloatCheck...
# Optional: Wiederverwendung des BloatCheck-Status (falls schon gelaufen)
Moechten Sie die Ergebnisse der vorherigen Durchlaeufe fuer MigrationBloatCheck verwenden? (Ja/Nein) [Nein]: n
# Erläuterung: 'Ja' überspringt Datenbanken, die kürzlich (innerhalb 3 Tagen) geprüft wurden.
[2025-04-27 09:18:03] [INFO] Database cde-import has been processed for MigrationBloatCheck within the last 3 days. Skipping.
# ... weitere Datenbanken ...
[2025-04-27 09:18:03] [INFO] MigrationBloatCheck completed.
[2025-04-27 09:18:03] [INFO] Operation 'BloatAndVacuum' completed in 52.6401734 seconds. Success: True
# Erläuterung: Prüft auf Datenbank-Fragmentierung (Bloat) und führt ggf. VACUUM durch.

[2025-04-27 09:18:03] [INFO] Pruefe auf TOAST & LOB Fehler...
[2025-04-27 09:18:03] [INFO] Starting TOASTErrorCheck...
# Optional: Wiederverwendung des TOASTErrorCheck-Status (falls schon gelaufen)
Moechten Sie die Ergebnisse der vorherigen Durchlaeufe fuer TOASTErrorCheck verwenden? (Ja/Nein) [Nein]: n
# Erläuterung: Prüft auf spezielle Datenkorruption (TOAST). Bei Fehlern wird die Migration normalerweise angehalten.

# --- Phase: Export & Backup ---
[INFO] Starting ExportDatabases... # Exportiert alle Datenbanken
[INFO] Starting ExportDatabaseMetadata... # Exportiert Metadaten (z.B. LOB-Anzahl) für spätere Verifizierung
[INFO] Starting DisableOldDatabaseService... # Stoppt und deaktiviert den alten PostgreSQL-Dienst
[INFO] Starting BackupOldInstallation... # Verschiebt das alte PostgreSQL-Verzeichnis (z.B. nach PostgreSQL_backup_JJJJMMDD_HHMMSS)
# Hinweis: Falls der Dienst nicht gestoppt werden kann oder der Ordner nicht verschoben werden kann,
# folgen Sie den Anweisungen auf dem Bildschirm. Möglicherweise müssen Sie Explorer-Fenster schließen
# oder PostgreSQL manuell mit pg_ctl.exe stoppen.

# --- Phase: Installation & Import ---
[INFO] Starting InstallNewPostgreSQL... # Lädt PostgreSQL 16 herunter und installiert es
# Hier wird der grafische Installer von PostgreSQL erscheinen.
[INFO] Starting RegisterPostgreSQLService... # Richtet den neuen Dienst "Solutio_PostgreSQL" ein
[INFO] Starting EnableMD5Encryption... # Stellt sicher, dass die Passwortverschlüsselung auf MD5 gesetzt ist (Kompatibilität)
[INFO] Starting ImportDatabases... # Importiert die zuvor exportierten Datenbanken in die neue Instanz

# --- Phase: Verifizierung & Konfiguration ---
[INFO] Starting VerifyDatabaseContents... # Vergleicht Metadaten (z.B. LOB-Anzahl) mit dem Stand vor dem Export
[INFO] Starting StartSolutioServices... # Startet Charly-Dienste neu
[INFO] Starting VerifyMigration... # Prüft Datenbankverbindung und Dienststatus
[INFO] Starting VerifyFlgConnection... # Prüft Verbindung mit Parametern aus Solutio.flg (falls abweichend)

[INFO] Starting ImportOldPostgreSQLConfig... # Liest alte postgresql.conf aus dem Backup
PgTune-Einstellungen in der alten Konfiguration gefunden:
----------------------------------------
max_connections = 500
shared_buffers = 4GB
effective_cache_size = 12GB
# ... weitere Einstellungen ...
Moechten Sie diese Einstellungen auf die aktuelle PostgreSQL-Installation anwenden? (Ja/Nein) [Ja]: n # Benutzerinteraktion
Moechten Sie stattdessen Empfehlungen von pgTune erhalten? (Ja/Nein) [Ja]: # Benutzerinteraktion

[2025-04-27 09:22:13] [INFO] Starting PostgreSQL tuning wizard # Startet bei Ja
# ... Systeminformationen ...
Empfehlung:
  Bitte besuchen Sie https://pgtune.leopard.in.ua/ und geben Sie folgendes ein:
  # ... Parameter für pgTune ...

Moechten Sie die Ausgabe von pgTune einfuegen?
# ... Anleitung zum Einfügen ...
Fuegen Sie die pgTune-Ausgabe ein und druecken Sie Enter zweimal, um abzuschliessen: # Benutzerinteraktion (mehrzeilig)
# Hier können die Einstellungen von der pgTune Webseite eingefügt werden.
# Das Skript wendet die eingefügten Einstellungen an und startet PostgreSQL neu.

[INFO] Starting InstallPgAdmin... # Optionaler Schritt
# Benutzerinteraktion: Hier öffnet sich der pgAdmin-Installer, falls die Installation gewünscht wird.
# Der Benutzer muss die Installation im GUI bestätigen oder kann sie abbrechen.

[INFO] Database migration completed successfully.

4. Troubleshooting

Fehler bei der Migration / Rollback

Sollte die Migration fehlschlagen, versucht das Skript automatisch, die vorherige PostgreSQL-Version wiederherzustellen (Restore-OldInstallation).

WICHTIGE UNTERSCHEIDUNG: - rollback-db-migration: Nur nach einer Datenbank-Migration verwenden! Dieser Befehl stellt eine PostgreSQL-Installation wieder her, die durch db-migration gesichert wurde. - manage start: Verwenden Sie diesen Befehl, wenn Sie nach einem Container-Update (siehe Container-Update) zum alten System zurückkehren möchten. Dieser Befehl startet die bestehenden Charly-Dienste wieder.

Falls dies nicht automatisch geschieht oder Sie manuell zur alten Version zurückkehren möchten (z.B. weil Tests fehlschlagen), können Sie dies bevor Sie mit dem neuen System arbeiten mit folgendem Befehl tun:

charly-server rollback-db-migration

Dieser Befehl führt die Funktion Start-ManualRestore aus. Sie versucht: 1. Die gesicherte alte PostgreSQL-Installation (PostgreSQL_backup_*) an den ursprünglichen Ort zurückzuverschieben. 2. Die neue PostgreSQL-Installation zu löschen. 3. Den ursprünglichen PostgreSQL-Dienst wieder zu registrieren und zu starten. 4. Die Charly-Dienste zu starten.

Voraussetzung für den Rollback: Der Befehl benötigt die Datei pg_backup_info.json im CharlyServerDataPath (normalerweise C:\ProgramData\CharlyServer). Diese Datei wird während des db-migration-Laufs erstellt, nachdem die alte Installation erfolgreich gesichert wurde. Wenn diese Datei fehlt (z.B. weil db-migration nie lief oder den Backup-Schritt nicht erreichte), kann der Rollback nicht durchgeführt werden und bricht mit einer Warnung ab:

PS C:\WINDOWS\system32> charly-server rollback-db-migration
Charly Server Version: 2.2.7
Charly Server Environment: release
Native Installation

Aktuelle Konfiguration:
====================
Befehl: rollback-db-migration
Solutio Path: C:\Solutio
Export Path: C:\solutio_export
[2025-04-27 11:07:18] [WARNING] No backup info file found at: C:\ProgramData\CharlyServer\pg_backup_info.json
# Das Skript bricht hier ab, da keine Backup-Informationen gefunden wurden.

WICHTIG: Ein Rollback sollte nur durchgeführt werden, wenn keine neuen Daten in der migrierten Datenbank erstellt oder geändert wurden. Kontaktieren Sie im Zweifelsfall den Support.

Beispiel (Erfolgreicher Rollback)

PS C:\WINDOWS\system32> charly-server rollback-db-migration
Charly Server Version: 2.2.7
Charly Server Environment: release
Native Installation

Aktuelle Konfiguration:
====================
Befehl: rollback-db-migration
Solutio Path: C:\Solutio
Export Path: C:\solutio_export
PostgreSQL Backup: C:\Solutio\Server\PostgreSQL_backup_20250427_093806 # Pfad zum Backup der alten Version

PostgreSQL Konfiguration: # Konfiguration der *aktuell* laufenden (neuen) Version
Path: C:\Solutio\Server\PostgreSQL
Host: 192.168.2.40
Port: 5432
Username: postgres
Service Name: Solutio_PostgreSQL
Version: 16.8.0 # Die neue Version, die zurückgerollt wird

Ist die Konfiguration korrekt? (Ja/Nein) [Ja]: # Benutzerbestätigung
[2025-04-27 10:56:01] [INFO] Starting manual restoration of old PostgreSQL installation... # Start des Rollbacks
[2025-04-27 10:56:01] [INFO] Found backup from: 20250427_093806
[2025-04-27 10:56:01] [INFO] Original path: C:\Solutio\Server\PostgreSQL # Der Zielpfad für die alte Version
[2025-04-27 10:56:01] [INFO] Backup path: C:\Solutio\Server\PostgreSQL_backup_20250427_093806 # Quelle für die alte Version
[2025-04-27 10:56:01] [INFO] Stopped current PostgreSQL service # Stoppt den Dienst der neuen Version
[2025-04-27 10:56:01] [INFO] Attempting to stop PostgreSQL using pg_ctl...
pg_ctl: PID-Datei »C:/Solutio/Server/PostgreSQL/data/postmaster.pid« existiert nicht
Läuft der Server? # Meldung von pg_ctl, da der Dienst bereits gestoppt wurde
# Hier wird die neue Installation gelöscht und das Backup zurückverschoben
[2025-04-27 10:56:08] [INFO] Previous PostgreSQL installation restored successfully # Alte Dateien wiederhergestellt
[2025-04-27 10:56:08] [INFO] Successfully restored old PostgreSQL installation
# Startet den Dienst der alten Version und prüft die Verbindung
[2025-04-27 10:56:08] [INFO] PostgreSQL connection test successful
[2025-04-27 10:56:08] [INFO] Starte Solutio-Dienste und aktiviere Client-Verbindungen... # Startet Charly-Dienste
[2025-04-27 10:56:08] [INFO] Verbinde PostgreSQL Datenbank neu...
[2025-04-27 10:56:10] [INFO] Datenbank-Wiederverbindung abgeschlossen.
....
[2025-04-27 10:56:56] [INFO] Dienst ehkp ist bereits registriert
WARNUNG: Warten auf Start des Diensts "ehkp (ehkp)"...
....
[2025-04-27 10:56:59] [INFO] Wiederherstellung der Solutio-Freigabefaehigkeit...
[2025-04-27 10:56:59] [INFO] Wiederherstellung der Solutio-Freigabefaehigkeit abgeschlossen.
[2025-04-27 10:56:59] [INFO] Alle aktivierten Solutio-Dienste gestartet und Client-Verbindungen erfolgreich aktiviert. # Abschlussmeldung

### Nicht-interaktive Sitzung / Remote Desktop
Wie in der Beispielausgabe und der Übersicht erwähnt, schlägt die Migration fehl, wenn sie nicht in einer lokalen, interaktiven PowerShell-Sitzung mit GUI-Zugriff ausgeführt wird.

```powershell
[2025-04-27 09:20:37] [WARNING] Non-interactive or remote session detected. UI-based installers may not work.
[2025-04-27 09:20:37] [ERROR] WARNUNG: Sie fuehren diese Migration in einer nicht-interaktiven oder Remote-Session aus.
Die PostgreSQL-Installation benoetigt eine grafische Oberflaeche.
Bitte fuehren Sie die Migration in einer lokalen PowerShell-Session mit GUI-Zugriff aus.

Stellen Sie sicher, dass Sie direkt am Server angemeldet sind oder eine Remote-Desktop-Verbindung verwenden, die GUI-Interaktionen zulässt (keine reine PowerShell-Remoting-Sitzung).

Probleme beim Stoppen des PostgreSQL-Prozesses

Während der Migration kann es vorkommen, dass der PostgreSQL-Prozess nicht ordnungsgemäß gestoppt werden kann oder der PostgreSQL-Ordner nicht verschoben werden kann, weil Prozesse noch darauf zugreifen:

Explorer oder Anwendungen blockieren den Ordner

Falls Sie folgende Meldung sehen:

Der PostgreSQL-Ordner kann nicht verschoben werden, da er von folgenden Prozessen verwendet wird:
Process: postgres (PID: 6328)

Befolgen Sie diese Schritte:

Schließen Sie alle Explorer-Fenster, die den Ordner D:\Solutio\Server\PostgreSQL anzeigen
Schließen Sie alle Programme, die auf den Ordner zugreifen
Bestätigen Sie mit "Ja", um es erneut zu versuchen

PostgreSQL-Dienst lässt sich nicht stoppen

Falls der Prozess Stop-DatabaseService lange läuft (>1 Minute) oder fehlschlägt, können Sie versuchen, PostgreSQL manuell zu stoppen:

Öffnen Sie eine PowerShell als Administrator
Navigieren Sie zum PostgreSQL bin-Verzeichnis:
```
cd D:\Solutio\Server\PostgreSQL\bin
```
Versuchen Sie folgende Befehle nacheinander, bis einer funktioniert:
```
.\pg_ctl.exe stop -D D:\Solutio\Server\PostgreSQL\data\
.\pg_ctl.exe stop -D D:\Solutio\Server\PostgreSQL\data\ -m fast
.\pg_ctl.exe stop -D D:\Solutio\Server\PostgreSQL\data\ -m immediate
```
Hinweis: Der -m immediate Modus beendet PostgreSQL sofort und kann zu Datenverlusten führen. Verwenden Sie diesen nur als letzten Ausweg.
Nach erfolgreichem Stoppen, setzen Sie die Migration fort mit:
```
charly-server db-migration
```

TOAST-Fehler

Wenn bei der TOAST-Prüfung Fehler gefunden werden, wird empfohlen, die Migration abzubrechen und die Fehler zu beheben. Das Fortsetzen mit TOAST-Fehlern kann zu Datenverlust führen.

5. Sonstiges

PostgreSQL Migrationsablauf

flowchart TD
    A[Start: charly-server db-migration] --> B{Konfiguration bestätigen?}
    B -->|Ja| C{Vorherige Ergebnisse verwenden?}
    C -->|Ja/Nein| D[Prüfungen Disk, Bloat, TOAST]
    D --> E[Datenexport]
    E --> F[Alte PG-Installation sichern]
    F --> G[Neue PG-Version installieren]
    G --> H[Datenimport]
    H --> I[Verifizierung]
    I --> J{Alte PG-Konfiguration übernehmen?}
    J -->|Ja| K[Übernahme alter Einstellungen]
    J -->|Nein| L{pgTune-Empfehlungen?}
    K --> M{pgAdmin installieren?}
    L -->|Ja| N[pgTune Wizard]
    L -->|Nein| M
    N --> M
    M -->|Ja| O[pgAdmin Installation]
    M -->|Nein| P[Abschluss]
    O --> P

    classDef interactive fill:#9370db,stroke:#333,stroke-width:2px
    class B,C,J,L,M,O interactive

Version: 2.5.0

Datum der letzten Aktualisierung: 03.06.2025