Durchsuchbare Dokumentation aufrufen

Zurück zur Dokumentationsübersicht

Nicht-UTF-8 MySQL-Datenbank auf UTF-8 Datenbank migrieren

Diese Dokumentation bezieht sich auf die Migration eines existierenden Systems in ein anderes bereits vorhandenes System.

Die Konvertierung kann, je nach Datenmenge, einige Zeit dauern. Während dieser Zeit steht agorum core nicht zur Verfügung. Um genau abschätzen zu können, wie lange das System nicht zur Verfügung steht, führen Sie die Konvertierung der Datenbank auf einem Testsystem durch, das leistungstechnisch dem Produktivsystem ähnelt.

Grundsätzlich wird der Dump mit dem derzeit verwendeten JDBC-Treiber durchgeführt, der Restore mit dem aktuellen MariaDB JDBC-Treiber, den Sie separat herunterladen müssen. Der neue Treiber wird auch für den Betrieb von agorum core verwendet.

Eine Migration können Sie auf zwei Wegen durchführen:

Voraussetzungen

Folgende Voraussetzungen müssen erfüllt sein, damit Sie eine Migration durchführen können:

Verwenden Sie unter Linux screen, sodass im Falle eines Verbindungsverlustes zur SSH-/Shell-Konsole das Programm / die Shell jederzeit wieder aufgerufen werden kann.

Allgemeine Vorbereitungen

Der folgende Schritt gilt unabhängig davon, auf welchem Weg Sie die Migration durchführen.

Die ZIP-Datei entpacken und anpassen

Im Folgenden entpacken Sie die ZIP-Datei convert-utf8.zip, die Sie von Ihrem agorum-Ansprechpartner erhalten haben.

  1. Entpacken Sie die ZIP-Datei convert-utf8.zip auf den Rechner, auf dem agorum core läuft.
  2. Kopieren Sie den aktuell verwendeten Datenbanktreiber in den Ordner lib des Convert-utf8-Ordners. Sie finden den Ordner lib in folgendem Pfad, wobei <InstallDir> Ihren Installationspfad beschreibt. 
    <InstDir>/agorumcore/jboss/server/default/lib

    Tipp: Welchen Datenbanktreiber Sie aktuell verwenden, finden Sie in der Datei mysql-ds.xml unter:

    <InstDir>/agorumcore/jboss/server/default/deploy/mysql-ds.xml
  3. Legen Sie den Ordner java an und fügen Sie eine kompatible JVM>=1.8 ein. Empfohlen wird die von agorum core mitgelieferte JVM, die Sie in folgendem Pfad finden: 
    <InstDir>/agorumcore/java
  4. Überprüfen Sie unter #config die Datenbank-Zugangsdaten in dump.sh und restore.sh oder convert.sh und passen Sie sie ggf. an.

Die Migration durchführen (Datenbank zu Datenbank, direkt per convert)

Vorbereitungen

Ist eine direkte Verbindung zwischen Quell- und Zieldatenbank möglich, kann direkt von der Quelldatenbank gelesen und in die Zieldatenbank geschrieben werden. Die Quelldatenbank muss dazu vom Quellsystem aus erreichbar sein. Sie erreichen dies folgendermaßen:

  1. Ändern Sie in der Quelldatenbank die bind-adress in der Datei my.cnf/my.ini auf 0.0.0.0.
  2. Loggen Sie sich auf der Quelldatenbank ein und führen Sie folgenden Befehl aus: 
    connect mysql;
update user set Host='%' where Host='localhost';
flush privileges;

Die Datenbank ohne Indexe migrieren

Im 1. Schritt migrieren Sie die Datenbank ohne Indexe. Eine direkte Berücksichtigung der Indexe ist problematisch und fehleranfällig, daher werden diese separat im 2. Schritt migriert.

  1. Beenden Sie agorum core.
  2. Öffnen Sie als Benutzer root folgenden Pfad zum Konvertierungsskript convert.sh: 
    <Pfad des Convert-utf8 Ordners>/convert.sh
  3. Öffnen Sie das Skript mit einem Editor und tragen Sie im Config-Teil die Verbindungsdaten zu Quelle und Ziel ein.
  4. Führen Sie das Konvertierungsskript aus unter: 
    <Pfad des Convert-utf8 Ordners>/bin/bash convert.sh

Indexe der Datenbank migrieren

Im 2. Schritt migrieren Sie die Indexe der Datenbank. Wird dieser Schritt vergessen, entsteht beim Start von agorum core kein Fehler, jedoch dauert der Start sehr lange und agorum core ist auch nach vielen Stunden noch nicht vollständig hochgefahren.

  1. Öffnen Sie als Benutzer root folgenden Pfad zum Konvertierungsskript indexes.sh: 
    <Pfad des Convert-utf8 Ordners>/convert.sh
  2. Öffnen Sie das Skript mit einem Editor und tragen Sie im Config-Teil die Verbindungsdaten zu Quelle und Ziel ein.
  3. Führen Sie das Konvertierungsskript aus unter: 
    <Pfad des Convert-utf8 Ordners>/bin/bash indexes.sh

Abschließende Arbeiten

Nach erfolgreicher Migration machen Sie die Änderungen, die Sie unter Vorbereitungen getroffen haben, wieder rückgängig, sofern die Datenbank noch anderweitig verwendet wird.

  1. Ändern Sie in der Quelldatenbank die bind-adress in der Datei my.cnf/my.ini auf localhost.
  2. Loggen Sie sich auf der Quelldatenbank ein und führen Sie folgenden Befehl aus: 
    connect mysql;
update user set Host='localhost' where Host='%';
flush privileges;

Die Migration durchführen (Datenbank zu Dump, Dump zu Datenbank, per dump und restore)

Den Datenbank-Dump erstellen

  1. Beenden Sie agorum core.
  2. Führen Sie das Dump-Skript dump.sh als Benutzer root in folgendem Pfad aus: 
    <Pfad des Convert-utf8 Ordners>/bin/bash dump.sh
  3. Überprüfen Sie, ob im Dump-Pfad alle Tabellen des roi-Schemas vorhanden sind (bis auf 3 jms_* Tabellen). Gehen Sie dazu folgendermaßen vor:

    • Ermitteln Sie in der MySQL-Konsole mit dem Befehl show tables die Liste der vorhandenen Tabellen.
    • Gleichen Sie die Liste mit der Pfadliste des Dump-Pfades ab.

Die Datenbank wiederherstellen

  1. Laden Sie den aktuellen JDBC-Treiber für MySQL herunter.
  2. Kopieren Sie den heruntergeladenen JDBC-Treiber in folgenden Pfad: 
    <InstDir>/agorumcore/jboss/server/default/lib
  3. Löschen Sie den alten Treiber. Falls Sie bislang den Drizzle-Treiber verwendet haben, wechseln Sie auf den MariaDB JDBC Treiber und passen Sie die Datei mysql-ds.xml analog an.
  4. Prüfen Sie die Datenbank nochmals auf UTF-8. Dies ist der Fall, wenn der Parameter <connection-url> in der Datei mysql-ds.xml und useUnicode=true&characterEncoding=UTF-8 enthalten sind.
  5. Löschen Sie die alte Datenbank über die MySQL-Konsole mit folgendem Befehl: 
    drop database roi;
  6. Führen Sie das Wiederherstellen-Skript restore.sh als Benutzer root in folgendem Pfad aus: 
    <Pfad des Convert-utf8 Ordners>/bin/bash restore.sh

Abschließende Arbeiten

Der folgende Schritt gilt unabhängig davon, auf welchem Weg Sie die Migration durchgeführt haben.

Daten konvertieren

  1. Ändern Sie den Eintrag agorum.system.charset in der Datei InstallDir//jboss/server/default/system.properties manuell auf den gleichen Wert wie auf dem Quellsystem.
  2. Starten Sie den agorum core-Server neu.
  3. Öffnen Sie auf der Startseite von agorum core desk4web.
  4. Klicken Sie im Abschnitt Tools/helper auf Convert to Unicode.
  5. Bestätigen Sie die Konvertierung.
  6. Starten Sie agorum core über die Dienste neu.
  7. Warten Sie, bis die Konvertierung beendet ist.
  8. Starten Sie agorum core über die Dienste neu.

System nach erfolgreicher Umstellung / Konvertierung überprüfen

Um sicherzustellen, dass die Umstellung / Konvertierung wirklich erfolgreich war und die generelle Funktion gegeben ist, überprüfen Sie das System abschließend:

Wenn Sie Probleme mit der Migration haben

convert to unicode not possible system is already unicode

Sollten Sie die Migration in ein neues agorum core-System durchführen, ist dieses System bereits auf UTF-8 eingestellt. Beim Ausführen von Handlungsanweisung 4 (Bestätigen Sie die Konvertierung) tritt die genannte Fehlermeldung auf, da die system.properties des neuen Systems die Information UTF-8 vorhanden bereits enthält. Bei einer Konvertierung auf einem bestehenden System würde sich hier noch der alte ISO-Eintrag befinden, denn typischerweise erfolgt die Konvertierung auf dem gleichen System.

Um das Tool verwenden zu können, müssen Sie auf dem neuen System, in das die Daten migriert wurden, den Eintrag in der system.properties manuell auf ISO stellen.

So vermeiden Sie die Fehlermeldung:

  1. Beenden Sie agorum core.
  2. Ändern Sie den Eintrag agorum.system.charset in der Datei InstallDir//jboss/server/default/system.properties manuell auf den gleichen Wert wie auf dem Quellsystem (bei Linuxsystemen: agorum.system.charset=ISO-8859-15).
  3. Starten Sie agorum core neu und führen Sie die obigen Schritte wie unter Daten konvertieren beschrieben durch.

Error connecting to the source database java.lang.ClassNotFoundException: org.drizzle.jdbc.DrizzleDriver

Wenn beim Ausführen von /bin/bash convert.sh die genannte Fehlermeldung erscheint, ist eventuell der Fallback-Driver nicht in den CLASSPATH im convert.sh eingetragen.

So vermeiden Sie die Fehlermeldung:

  1. Erweitern Sie im convert.sh in Linie 29 die Variable CLASSPATH um:

    :${LIBS}/drizzle_jdbc.jar