Für Systembetreuer: Anleitung für die Migration auf PostgreSQL 13 (macOS)

Hinweis: Diese Anleitung beschreibt die Migration der solutio-Datenbanken von PostgreSQL 9 auf PostgreSQL 13. Sie richtet sich an erfahrene Systembetreuer.
Hinweis: Bitte beachten Sie, dass wir trotz sorgfältiger Erstellung der hier verwendeten Skripte keine Verantwortung für die Funktionalität übernehmen können. Die Nutzung der Skripte erfolgt auf eigenes Risiko.
Hinweis: Wenn Sie einen Serverumzug planen, müssen Sie zuvor keine separate Datenbank-Migration durchführen, da PostgreSQL 13 bereits in den charly-Installationsdateien enthalten ist.
Hinweis: Die aktuelle Migration für PostgreSQL 13 ist nicht für die Verwendung auf macOS-Geräten mit ARM-Architektur (M1/2/3 Prozessoren) ausgelegt, da es kein PostgreSQL13 Installationsprogramm für diese Architektur gibt.

Allgemeine Voraussetzungen

Vorbereitung

Log-File des PostgreSQL-Servers auf Fehler überprüfen

Vorgehensweise

  1. Öffnen Sie das Terminal.

  2. Navigieren Sie in das Verzeichnis des PostgreSQL-Servers.

    cd /Applications/Solutio/Server
    sudo su SolutioSQL
    cd data
    cd pg_log

  3. Öffnen Sie die beiden neuesten Log-Files in diesem Verzeichnis mit einem Kommandozeilen-Editor (z.B. nano, vim...).

    ls
    nano <logfile>
  4. Überprüfen Sie die Log-Files auf Fehlermeldungen. Suchen Sie insbesondere nach dem Begriff „Block“.
  5. Wenn der Begriff „Block“ gefunden wird, überprüfen Sie, ob im Kontext des Begriffs von einem „Blockfehler“ oder „Fehler in Block xy“ die Rede ist.
    Hinweis: Es dürfen keine Block-Fehler vorhanden sein! Siehe Fehlerbehebung.

Status der Microservices überprüfen

Vorgehensweise

  1. Öffnen Sie charly auf dem Server.

  2. Gehen Sie in der Menüleiste auf Hilfe > Statusanzeige Services.

    • Alle Services haben den Status „200“ und die Bemerkung „OK“.

      Hinweis: Der Soldicom-Service ist nicht registriert und daher nicht relevant.

Konnektorstatus überprüfen

Vorgehensweise

  1. Öffnen Sie charly auf dem Server.

  2. Gehen Sie in der Menüleiste auf Hilfe > Konnektor.

    • Wenn die Status-Ampel grün ist, ist der E-Health-Service erreichbar und es können Konnektor-Operationen durchgeführt werden.

  3. Klicken Sie auf den Button Konnektorstatus testen.

    • Der TI-Status muss „Online“ sein.

Vorbereitung abschließen

Wenn alle Vorbereitungen erfolgreich durchgeführt sind und keine Fehler gefunden wurden, können Sie mit der Datenbank-Migration fortfahren.

Hinweis: Wenn Sie in den Vorbereitungsschritten einen oder mehrere Fehler finden, erstellen Sie über das Support-Portal der solutio GmbH & Co. KG ein Ticket. Der Support wird Sie dabei unterstützen, den bzw. die Fehler zu beheben. Warten Sie bis zur erfolgreichen Fehlerbehebung mit den weiteren Schritten in dieser Anleitung.

Führen Sie in diesem Fall keine Datenbank-Migration durch!

Datenbank-Migration

Mit dem Skript „migrate_solutio.sh“ werden ausschließlich solutio-Daten migriert, auch wenn der Datenbank-Server zusätzlich Daten einer Dritt-Software enthält.

Tipp: solutio-Datenbanken sind …

  • Datenbanken, die in ihrer Benennung enthalten:

    • „solutio“ (z.B. „solutiodb“)
    • „ncjs“ (z.B. „ncjs-ehealth-eau“, „ncjs-ehkp“)
    • „charly“ (z.B. „charly-olap“)
  • Datenbanken „cdoc-olap“, „olap-conf“ und „cde-import“

Die bisherige installierte PostgreSQL-Installation läuft weiter, sodass die Dritt-Software diese weiterhin verwenden kann.

Ablauf

Die Migration besteht aus den folgenden Schritten:

  1. Das Skript „migrate_solutio.sh“ ausführen.
  2. Den neuen Datenbank-Port in die „Solutio.flg“ eintragen.
  3. Den aktuellen Updater ausführen, auch wenn dieser bereits im Vorhinein ausgeführt wurde.
Hinweis: Die alte PostgreSQL-Instanz enthält weiterhin die charly-Daten, diese werden jedoch bei der täglichen Arbeit nicht weiter aktualisiert. Entfernen Sie diese Kopie nach einer angemessenen Übergangszeit.

Voraussetzungen

Schritt 1: Skript „migrate_solutio.sh“ ausführen

Vorgehensweise

  1. Überprüfen Sie im Skript „migrate_solutio.sh“ in den ersten Zeilen, ob die dort hinterlegten Einstellungen und Pfade Ihrer Systemkonfiguration entsprechen.
  2. Öffnen Sie ein Terminal und navigieren Sie zu dem Verzeichnis, in dem Sie die „migrate_solutio.sh“-Datei gespeichert haben.

  3. Starten Sie die Daten-Migration mit folgendem Befehl:

    sudo ./migrate_solutio.sh

    • Das Skript führt die folgenden Schritte aus:

      • Der PostgreSQL-Installer 13 wird heruntergeladen.

      • Die Installation von PostgreSQL 13 wird durchgeführt.

        • Der Installer startet automatisch.

      • Ein PostgreSQL-Dump wird erstellt und die solutio-Datenbanken werden in die PostgreSQL-13-Installation eingespielt.

        • Es erscheint eine Fehlermeldung, dass die Rolle „Postgres“ bereits existiert. Diese Meldung kann ignoriert werden.
      • Nach der Migration öffnet sich die „Solutio.flg“.

Schritt 2: Neuen Datenbank-Port in die „Solutio.flg“ eintragen

Vorgehensweise

  1. Ändern Sie in der „Solutio.flg“ den SQL-Port:

    -SQLPORT 5433

  2. Speichern Sie die „Solutio.flg“.

    Hinweis: Wenn die Datei „DBBackup.flg“ unter den folgenden Pfaden vorhanden ist, muss dort ebenfalls der SQL-Port angepasst werden.
    • <charly-Installationspfad>/Solutio/Client/Charly/Solutio.app
    • <charly-Installationspfad>/Solutio/Client/Charly/Solutio.app/Contents/Utils
    • <charly-Installationspfad>/Solutio/Client/Charly/Solutio.app/Contents/MacOS

Schritt 3: charly-Updater ausführen

Vorgehensweise

  1. Navigieren Sie zu dem Verzeichnis, in dem Sie den charly-Updater gespeichert haben.

    Falls Sie den charly-Updater nicht vorliegen haben, können Sie ihn im Downloadsbereich unserer Homepage herunterladen.

  2. Starten Sie den charly-Updater.

    • Eine Meldung erscheint, dass charly bereits aktuell ist. Diese Meldung können Sie ebenfalls ignorieren und schließen.
  3. Nachdem der charly-Updater beendet ist, starten Sie einen charly-Client.

  4. Überprüfen Sie die Datenbankversion in der Menüleiste unter Hilfe > SQL-Datenbank.

    • Die Datenbankversion zeigt PostgreSQL 13.

  5. Prüfen Sie mit ein paar Stichproben, ob in charly alles wie gewohnt funktioniert.

    Beispiel: Öffnen Sie in KIM4charly eine KIM-Nachricht, die einen Anhang enthält. Öffnen Sie diesen Anhang in der Vorschau oder speichern Sie ihn alternativ.

    Wenn Sie dabei eine Fehlermeldung erhalten „Unable to access lob stream“, wenden Sie sich bitte an unseren Support.

    Die Fehlermeldung kann ebenfalls in den Signaturaufträgen und im E-Rezept auftreten.

    Weitere Tests finden Sie hier: Checkliste: Tests in charly durch die Praxis

  6. Führen Sie eine Datensicherung in charly durch.

  7. Starten Sie alle weiteren charly-Clients.

    • Die Migration auf PostgreSQL 13 ist abgeschlossen.
  8. Falls Sie mehrere charly-Server-Installationen haben, führen Sie pro charly-Installation die Migration durch und passen Sie im Skript den PostgreSQL-Port an.
  9. Passen Sie die „Solutio.flg“ bei allen Clients an.

Nachbereitung

In „pg_hba.conf“ einen Eintrag für das Praxis-Subnetz hinterlegen

In der Datei „pg_hba.conf“ wird die Netzwerkkonfiguration der Datenbank definiert. Es wird die „pg_hba.conf“ der bestehenden Postgres 9 Installation für die neue PostgreSQL 13 verwendet. Falls Sie mit einem Client nicht auf die Datenbank zugreifen können, müssen Sie einen Eintrag für das Praxis-Subnetz hinzufügen.

Beispielhafter Ausschnitt aus einer „pg_hba.conf“:

# TYPE  DATABASE    USER      CIDR-ADDRESS       METHOD

# IPv4 local connections:
#host    all         all       127.0.0.1/24       trust
# IPv6 local connections:
#host    all         all       ::1/128            trust

host    all         all       ::1/128            trust
host    all         all       127.0.0.1/24       trust
host    all         all       0.0.0.0/0          md5

Vorgehensweise

  1. Ermitteln Sie die Subnet-Adresse Ihrer Praxis.

  2. Navigieren Sie zu der Datei „pg_hba.conf“. Sie liegt standardmäßig unter dem Pfad: /Applications/Solutio/Server/PostgreSQL13/data/.

    cd /Applications/Solutio/Server
    sudo su SolutioSQL
    cd data

  3. Öffnen Sie die Datei „pg_hba.conf“ mit einem Kommandozeilen-Editor (z.B. nano, vim...)

    nano pg_hba.conf

  4. Fügen Sie dort im Bereich „# IPv4 local connections:“ einen Eintrag für Ihre Praxis-Subnet-Adresse ein. Ersetzen Sie <Subnet-Adresse> durch Ihre Praxis-Subnet-Adresse. Die letzte Zahl vor dem „/“ muss dabei eine 0 sein („x.y.z.0/24“).

    # IPv4 local connections:
    #host    all        all     127.0.0.1/24           trust
    host    all        all     <Subnet-Adresse>/24    md5
  5. Speichern Sie die Datei „pg_hba.conf“.

  6. Starten Sie den PostgreSQL-Dienst oder -Server neu, indem Sie folgendes in die Kommandozeile eingeben:

    sudo -u SOLUTIOSQL "/Library/solutio_postgres/13/bin/pg_ctl" restart -D "/Library/solutio_postgres/13/data"

[Optional] Datenbank optimieren mit PGTune

PGTune ist ein Open-Source-Tool, das entwickelt wurde, um bei der Optimierung der Leistung von PostgreSQL-Datenbanken zu helfen. Es analysiert die Konfigurationseinstellungen Ihrer PostgreSQL-Installation und schlägt basierend auf den Hardware-Spezifikationen und den Anforderungen Ihrer Datenbank optimale Einstellungen vor.

Hinweis: Die PostgreSQL-Konfiguration ist in der Datei „postgresql.conf“ gespeichert. Die Datei liegt standardmäßig unter dem Pfad: /Applications/Solutio/Server/PostgreSQL13/data/ .

Um eventuelle Probleme zu vermeiden, erstellen Sie vor der Verwendung von PGTune eine Sicherung Ihrer aktuellen PostgreSQL-Konfiguration!

Vorgehensweise

  1. Sammeln Sie Informationen über die Hardware-Spezifikation Ihres Servers und die erwartete Arbeitslast Ihrer PostgreSQL-Datenbank. Dazu gehören CPU-Anzahl und -Typ, verfügbarer Arbeitsspeicher, Festplattengeschwindigkeit und geplante Datenbankaktivitäten (Lesen, Schreiben, Anzahl der gleichzeitigen Verbindungen usw.).
  2. Öffnen Sie in Ihrem Webbrowser die URL https://pgtune.leopard.in.ua/.

  3. Geben Sie die gesammelten Informationen ein:

    1. Wählen Sie bei DB Version die Option „13“.
    2. Wählen Sie bei OS Type das Betriebssystem Ihres Servers.
    3. Wählen Sie bei DB Type die Option „Desktop application“.

    4. Geben Sie in den Feldern Total Memory (RAM) und Number of CPUs an, wieviel die PostgreSQL-Datenbank von dem verfügbaren RAM und den verfügbaren CPUs Ihres Servers verwenden darf.

      Hinweis: Bitte beachten Sie, dass andere Dienste, wie z.B. die Microservices, ebenfalls Ressourcen benötigen. Daher sollten Sie der PostgreSQL-Datenbank nicht sämtliche Ressourcen zuweisen.
    5. Geben Sie in das Feld Number of Connections den Wert „400“ ein.
    6. Wählen Sie bei Data Storage die Festplattenart Ihres Servers.
  4. Um die optimierten Konfigurationseinstellungen zu erhalten, klicken Sie auf Generate.
  5. Kopieren Sie die ermittelten Konfigurationseinstellungen.

  6. Navigieren Sie zu der Datei „postgresql.conf“. Sie liegt standardmäßig unter dem Pfad: /Applications/Solutio/Server/PostgreSQL13/data/.

    cd /Applications/Solutio/Server
    sudo su SolutioSQL
    cd data

  7. Öffnen Sie die Datei „postgresql.conf“ mit einem Kommandozeilen-Editor (z.B. nano, vim...).

    nano postgresql.conf
  8. Fügen Sie dort im Bereich „# CUSTOMIZED OPTIONS“ die ermittelten Konfigurationseinstellungen ein bzw. ersetzen Sie die dort vorhandenen Konfigurationseinstellungen.
  9. Speichern Sie die Datei „postgresql.conf“.

  10. Starten Sie den PostgreSQL-Dienst oder -Server neu, indem Sie folgendes in die Kommandozeile eingeben:

    sudo -u SOLUTIOSQL "/Library/solutio_postgres/13/bin/pg_ctl" restart -D "/Library/solutio_postgres/13/data"

charly prüfen (SQL-Datenbank, Microservices, Konnektorstatus)

Vorgehensweise

  1. Öffnen Sie charly auf dem Server.

  2. Gehen Sie in der Menüleiste auf Hilfe > SQL-Datenbank.

    • Die neue PostgreSQL-Version 13 muss angezeigt werden.

  3. Gehen Sie in der Menüleiste auf Hilfe > Statusanzeige Services.

    • Alle Services haben den Status „200“ und die Bemerkung „OK“.

      Hinweis: Der Soldicom-Service ist nicht registriert und daher nicht relevant.

  4. Gehen Sie in der Menüleiste auf Hilfe > Konnektor.

    • Wenn die Status-Ampel grün ist, ist der E-Health-Service erreichbar und es können Konnektor-Operationen durchgeführt werden.

  5. Klicken Sie auf den Button Konnektorstatus testen.

    • Der TI-Status muss „Online“ sein.

Interne Datensicherung mit DBBackup auf dem Server durchführen

Voraussetzungen

Vorgehensweise

  1. Öffnen Sie das Terminal.

  2. Navigieren Sie zum Tool DBBackup.

    cd /Applications/Solutio/Client/Charly/Solutio.app/Contents/Utils

  3. Geben Sie folgenden Befehl ein:

    ./DBBackup -v -V
    • Die Datenbanksicherung wird für alle Mandanten durchgeführt.

  4. Prüfen Sie im Kommandozeilentool, ob dort Fehler aufgeführt sind. Siehe Fehlerbehebung.

Checkliste: Tests in charly durch die Praxis

Nach Abschluss des technischen Migrationsprozesses können Systembetreuer lediglich bestätigen, dass die Migration ohne Fehlermeldung durchgeführt wurde. Es liegt jedoch in der Verantwortung des Anwenders zu überprüfen, ob sämtliche Daten an den richtigen Stellen abgelegt wurden.

Um sicherzustellen, dass die Datenbank-Migration erfolgreich war, empfehlen wir dem Anwender daher, unmittelbar nach der Migration die folgenden Programmtests (in dieser Reihenfolge) durchzuführen:

  1. Versand einer KIM-Nachricht an sich selbst
  2. Versand einer KIM-Nachricht mit Anhang (Röntgenbild) an sich selbst
  3. Versand einer mit HBA signierten KIM-Nachricht (Röntgenbild) an sich selbst
  4. Einlesen einer eGK
  5. Erstellen eines EBZ-Behandlungsplans (ZE, PAR. KGL) und anschließendem Start des Signierungsprozesses
  6. Erstellen eines E-Rezepts (Abbruch beim Schritt" „Signierung“)
  7. Erstellen einer eAU (Abbruch beim Schritt" „Signierung“)
  8. Abrechnungs-Probelauf ZE: Überprüfen (perTransparenzmodul), ob die EBZ-Felder und das ZANR-Feld ordnungsgemäß belegt sind
  9. Abrechnungs-Probelauf PAR: Überprüfen (perTransparenzmodul), ob die EBZ-Felder und das ZANR-Feld ordnungsgemäß belegt sind
  10. Abrechnungs-Probelauf KGL/KB: Überprüfen (per Transparenzmodul), ob die EBZ-Felder und das ZANR-Feld ordnungsgemäß belegt sind
  11. Abrechnungs-Probelauf KCH: Überprüfen (per Transparenzmodul), ob das ZANR-Feld ordnungsgemäß belegt ist

Wenn bei diesen Tests keine Fehler auftreten, kann der Anwender die ordnungsgemäße Durchführung bestätigen.

Hinweis: Wenn bei diesen Tests ein oder mehrere Fehler auftreten, kontaktieren Sie sofort Ihren Systembetreuer und/oder den Support der solutio GmbH & Co. KG. Arbeiten Sie unter keinen Umständen mit einer beschädigten Datenbank, da dies potenzielle Folgeprobleme verursachen kann!

Fehlerbehebung

Wenn sich Ihr Terminal standardmäßig als „Z Shell“ (zsh) öffnet, müssen Sie den Befehl zum Ausführen des Skripts wie folgt ändern:

sudo sh ./migrate_solutio.sh

Das zusätzliche „sh“ erzwingt das Nutzen der Bash-Shell und erlaubt das Ausführen des Skripts.

Sollten beim Ausführen des Skripts Fehler auftreten, können Sie das Skript ab einem bestimmten Schritt erneut starten. In dem Skript erkennen Sie die einzelnen Schritte anhand der Bezeichnung, z.B. :step4.

Der folgende Aufruf startet z.B. das Skript „migrate_solutio.sh“ ab Schritt 4:

sudo ./migrate_solutio.sh -s 4

Es kann vorkommen, dass beim Ausführen des Skripts, die Services nicht sauber gestartet bzw. gestoppt werden. Das Skript bricht ab und es erscheint eine Fehlermeldung, welcher Service betroffen ist und bei welchem Schritt im Skript wieder gestartet werden kann.

Vorgehensweise

  1. Starten Sie das Skript an dem in der Fehlermeldung beschriebenen Schritt.

    Der folgende Aufruf startet z.B. das Skript „migrate_solutio.sh“ ab Schritt 4:

    sudo ./migrate_solutio.sh -s 4

  • Problem:

    Wenn die Festplatte voll ist, kann DBBackup keine Backups erstellen oder vorhandene Backups erweitern.

  • Lösung:

    Überprüfen Sie den Speicherplatz auf der Festplatte. Löschen Sie nicht benötigte Dateien oder verschieben Sie einige Daten auf eine andere Festplatte, um Platz zu schaffen. Anschließend versuchen Sie erneut, das Backup durchzuführen.

  • Problem:

    Fehlende Dateisystemrechte für den Ordner „solutioData“ können die Ausführung von DBBackup behindern.

  • Lösung:

    Stellen Sie sicher, dass der Benutzer, unter dem DBBackup ausgeführt wird, die notwendigen Rechte besitzt, um auf den Ordner „solutioData“ zuzugreifen und darin zu schreiben. Dies kann mit dem Befehl „chmod“ (unter Linux/Unix) oder über die Eigenschaften des Ordners (unter Windows) eingestellt werden.

  • Problem:

    Probleme mit dem PostgreSQL-Password oder der Authentifizierung können auftreten. Dies weist möglicherweise auf eine inkorrekte Konfiguration in „pg_hba.conf“ oder „postgresql.conf“ hin.

  • Lösung:

    Überprüfen Sie die Konfigurationsdateien „pg_hba.conf“ und „postgresql.conf“ auf korrekte Einstellungen für Authentifizierung und Zugriffsrechte. Stellen Sie sicher, dass die Zugangsdaten korrekt sind und der Zugriff von dem entsprechenden Client aus zugelassen ist.

  • Problem:

    Instabilität im Netzwerk kann zu Unterbrechungen in der Kommunikation zwischen dem Client und dem Server führen, was DBBackup beeinträchtigt.

  • Lösung:

    Überprüfen Sie die Netzwerkverbindung zwischen dem Client und dem Server. Dies kann durch Ping-Tests oder Netzwerkdiagnosetools erfolgen. Stellen Sie sicher, dass das Netzwerk stabil ist, bevor Sie den Backup-Prozess erneut starten.

  • Lösung:

    Prüfen Sie, ob in der Datei DBBackup.flg korrekte Werte eingetragen sind, vor allem den Port der neuen Datenbank. Falls die Datei DBBackup.flg nicht existiert, prüfen Sie die Werte in der Solutio.flg

  • Problem:

    Wenn Blockfehler auftreten, könnte dies auf eine potenziell korrupte Datenbank oder Festplatte hindeuten und sollte schnellstmöglich untersucht und behoben werden.

  • Lösung:

    • Wenden Sie sich an Ihren Systembetreuer. Dieser sollte ein Reindex und Vacuum auf der betroffenen Datenbank oder Festplatte durchführen.

      SET zero_damaged_pages = on;
      VACUUM FULL VERBOSE ANALYZE tabelle;
      REINDEX TABLE tabelle;