Codepage utf8 auf utf8mb4 umstellen

Voraussetzung

Das Zielverzeichnis für den Datenbank-Dump muss ausreichend Platz haben.

Hinweise:

Diese Dokumentation gilt nur für bestehende agorum core-Installationen. Bei Neuinstallationen ab agorum core 9.0 ist utf8mb4 bereits integriert.
Die Umstellung ist optional.
Die eingesetzte MySQL Version muss mindestens 5.7.9 sein.
Sie benötigen eine vollständige Datensicherung zum Wiederherstellen, idealerweise einen Snapshot des Systems.

Durch die Umstellung kann die Datenbank weitere Sonderzeichen in agorum core ablegen. Die Migration ist für ein fehlerfreies Betreiben von agorum core nicht zwingend notwendig, sondern lediglich dann, wenn Sie Sonderzeichen in Datei- oder Ordnernamen verwenden. Das Anpassen der Codepage ist auch nur bei MySQL-Datenbanken relevant.

Beenden Sie agorum core.
Erstellen Sie einen Datenbank-Dump (Dump der Tabellenstruktur und Dump der Daten).
Starten Sie die Datenbank mit folgenden Befehlen:

Windows
```
net start agorumcore.mysql
```
Linux
```
InstDir/scripts/roi_mysql start
```

Führen Sie einen Dump der Tabellenstruktur von agorum core durch.

Hinweis: Ersetzen Sie USERNAME, PASSWORT und Backup- bzw. InstDir durch die jeweils gültigen Credentials und Pfade.

Windows

InstDir/mysql/bin/mysqldump.exe -uUSERNAME -pPASSWORT -hroihost --port=3306 --no-data -B roi > BackupDir/structure.sql

Linux

InstDir/mysql/bin/mysqldump -uUSERNAME -hlocalhost --socket=/tmp/mysql.agorumcore.sock01 -pPASSWORT --no-data -B roi > BackupDir/structure.sql

Führen Sie einen Dump der Daten von agorum core durch.

Hinweis: Ersetzen Sie USERNAME, PASSWORT und Backup- bzw. InstDir durch die jeweils gültigen Credentials und Pfade.

Windows

InstDir/mysql/bin/mysqldump.exe -uUSERNAME -pPASSWORT -hroihost --port=3306 --no-create-info -B roi > BackupDir/data.sql

Linux

InstDir/mysql/bin/mysqldump -uUSERNAME -hlocalhost --socket=/tmp/mysql.agorumcore.sock01 -pPASSWORT --no-create-info -B roi > BackupDir/data.sql

Öffnen Sie die Datei structure.sql mit einem geeigneten Editor.
Suchen Sie in der Datei nach utf8 und ersetzen Sie die Einträge durch utf8mb4.
Suchen Sie in der Datei nach utf8_bin und ersetzen Sie die Einträge durch utf8mb4_bin.

Hinweis: Notepad ++ findet bei der Suche nach utf8 auch die utf8_bin-Collations und ersetzt diese korrekt. Dementsprechend ergibt die zweite Suche keinen Treffer. Im Editor muss Suchen und Ersetzen zweimal durchgeführt werden.
Passen Sie die Länge des Feldes DESTINATION im Index der Tabelle jms_messages an.

a) Suchen Sie nach PRIMARY KEY (`MESSAGEID`,`DESTINATION`).
b) Tragen Sie hinter das Wort DESTINATION den Wert (240) ein.
c) Ergebnis: PRIMARY KEY (`MESSAGEID`,`DESTINATION`(240))
Passen Sie die Engine der jms_Tabellen an.

a) Suchen Sie nach jms_.
b) Je jms-Tabelle existiert der Block -- Table structure for table `jms_...` (insgesamt 5) und in den Folgezeilen die entsprechenden Parameter für diese Tabelle.
Hinweise:
• Außer bei der jms_messages und bei der jms_transactions müssen Sie bei allen die Engine von MyISAM auf InnoDB umstellen.

Beispiel anhand der jms_roles
```
--
-- Table structure for table `jms_roles`
--
....
  PRIMARY KEY (`USERID`,`ROLEID`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin;
/*!40101 SET character_set_client = @saved_cs_client */;
```
• Bei den Tabellen jms_messages und jms_transactions muss die Engine MyISAM bleiben.
Fahren Sie die MySQL-Datenbank mit folgendem Befehl herunter:

Windows
```
net stop agorumcore.mysql
```
Linux
```
InstDir/scripts/roi_mysql stop
```
Passen Sie folgende Dateien an:

Windows
```
my.ini
```
Linux
```
my.cnf
```
a) Tragen Sie unterhalb der Überschrift [mysqld] folgende Werte ein:
```
collation_server=utf8mb4_bin
character_set_server=utf8mb4
```
Starten Sie die MySQL-Datenbank.
Entfernen (droppen) Sie die bestehende Datenbank roi.

a) Melden Sie sich an der Datenbank-Konsole an:

Windows
```
InstDir\mysql.exe -uroot -p -hlocalhost --port=3306
```
Linux
```
InstDir/mysql -uroot -p -hlocalhost --port=3306 --socket=/tmp/mysql.agorumcore.sock01
```
b) Verwenden Sie zum Entfernen folgenden Befehl:
```
drop database roi;
```
Hinweis: Bei älteren Windows-Installationen findet die Verbindung über roihost statt localhost statt. Ersetzen Sie dies in den Befehlen entsprechend.
Melden Sie sich mit folgendem Befehl von der Datenbank ab:
```
quit;
```

Spielen Sie die modifizierte structure.sql mit folgendem Befehl ein (dadurch wird automatisch ein create database roi mit den richtigen Parametern durchgeführt):

Windows

InstDir/mysql/bin/mysql.exe -uUSERNAME -pPASSWORT -hlocalhost --port=3306 < structure.sql

Linux

InstDir/mysql/bin/mysql -uUSERNAME -hlocalhost --socket=/tmp/mysql.agorumcore.sock01 -pPASSWORT < structure.sql

Spielen Sie die data.sql mit folgendem Befehl ein:

Windows

InstDir/mysql/bin/mysql.exe -uUSERNAME -pPASSWORT -hlocalhost --port=3306 roi < data.sql

Linux

InstDir/mysql/bin/mysql -uUSERNAME -hlocalhost --socket=/tmp/mysql.agorumcore.sock01 -pPASSWORT roi < data.sql

Starten Sie agorum core und prüfen Sie vorhandene Funktionen und ob Dokumente mit Symbolen im Namen abgelegt werden können.