Documentation/HowTo/MigrateFromHSQLDB

    From The Document Foundation Wiki
    This page is a translated version of the page Documentation/HowTo/MigrateFromHSQLDB and the translation is 100% complete.

    Das LibreOffice 6.1 Release wird schrittweise die interne HSQLDB-Datenbank durch die interne Firebird-Datenbank ersetzen. Dies zeigt sich zunächst daran, dass bestehende Firebird-Datenbanken keine Aktivierung des Experimentalmodus mehr erfordern.

    Wenn der Experimentalmodus in LibreOffice aktiviert ist, erscheint beim Zugriff auf die Tabellen einer internen HSQLDB-Datenbank folgender Dialog:

    Migration Dialog.png

    Hier sollte Später gewählt werden, bis alle folgenden Vorsichtsmaßnahmen schon getroffen wurden.

    1. Sichern Sie die HSQLDB-Datenbankdatei.
    2. Kopieren Sie die Ansichten aus dem SQL-Code und speichern Sie diese als Abfragen. Später passen Sie diese an und speichern sie wieder als Ansichten. Ansichten können zur Zeit in Firebird nicht bearbeitet werden!
    3. Tabellennamen und Spaltennamen in Firebird können nur bis zu 31 Zeichen lang sein. Bei Bedarf anpassen.
    4. Aufgrund eines Fehlers müssen in allen Tabellen Datumsfelder, Zeitfelder und Datums-/Zeitfelder durch ein Feld ergänzt werden, das den Inhalt als Text speichert.
    5. Aufgrund eines Fehlers werden in einer HSQLDB gelesene Bilder nach der Migration nicht mehr in der Firebird-Datenbank angezeigt.
    6. Reine Texttabellen (integrierte *.csv-Tabelle etc.) sind unter Firebird nicht möglich.

    Migrieren Sie Datumsfelder, Zeitfelder und Datums-/Uhrzeitfelder

    Dem Migrationsassistenten gelingt es nicht, Datumsfelder, Zeitfelder und Datums-/Uhrzeitfelder korrekt zu migrieren. Dies liegt daran, dass die HSQLDB mit lokalen Zeitzonen arbeitet. Bei der Datum-Uhrzeit-Migration wird daraus plötzlich ein Sommerzeitwert, der 2 Stunden früher liegt, im Winter aber nur eine Stunde. Die Termine werden immer um einen Tag verschoben, usw. Die folgende Methode hilft, die entsprechenden Werte aus der HSQLDB korrekt in die Firebird-Datenbank zu bekommen und dann wieder Zeit- und Datumswerte zu erstellen:

    1. Tabellen, die Datumsfelder, Zeitfelder und Datums-/Uhrzeitfelder in der HSQLDB enthalten, um jeweils ein VARCHAR-Feld hinzufügen:

           "Datum_T" VARCHAR (10),
           "Zeit_T" VARCHAR (8),
           "DatumZeit_T" VARCHAR (19)
    

    2. Führen Sie den folgenden Befehl über Tools → SQL aus:

           UPDATE "Tabelle" SET "Datum_T" = CAST ("Datum" AS VARCHAR (10));
           UPDATE "Tabelle" SET "Zeit_T" = CAST ("Zeit" AS VARCHAR (8));
           UPDATE "Tabelle" SET "DatumZeit_T" = LEFT (CAST ("DatumZeit" AS VARCHAR (30)), 19);
    

    3. Nachdem alle Felder auch als Textfelder in den Tabellen zur Verfügung stehen, kann die Migration fortgesetzt werden. Anschließend muss die migrierte Firebird-Datenbankdatei wieder aktualisiert werden:

           UPDATE "Tabelle" SET "Datum" = "Datum_T";
           UPDATE "Tabelle" SET "Zeit" = "Zeit_T";
           UPDATE "Tabelle" SET "DatumZeit" = "DatumZeit_T";
    

    Nach dieser Aktion sind die entsprechenden Werte aus der HSQLDB auch in der neuen Firebird-Datenbankdatei verfügbar. Die Felder "Datum_T", "Zeit_T" und "DatumZeit_T" können dann gelöscht werden.

    Bilder aus Tabellen in Formularen sichtbar und veränderbar machen

    Der Migrationsassistent erstellt Felder mit dem Typ image [BLOB] in Feldern, die für Bilder in der HSQLDB verantwortlich waren (image [Longvarbinary]). Dieser Typ ist in der GUI vorhanden, aber wahrscheinlich nicht mit dem richtigen Datentyp verknüpft. Um diese Bilder wieder sichtbar zu machen, müssen sie in ein Feld vom Typ BLOB [BLOB] kopiert werden, so dass eine Darstellung und Modifikation des Bildinhalts im Formular möglich ist. Berichte können derzeit keine Bilder aus Firebird-Datenbankdateien anzeigen.

    Firebird table image change error.png

    Auch wenn vom Benutzer keine Änderungen an einem Bildfeld vorgenommen wurden, erscheint die Meldung, dass eine Änderung nicht möglich ist und stattdessen die Spalte gelöscht und neu erstellt werden kann. Am besten wählen Sie Nein, da sonst die im Feld gespeicherten Daten verloren gehen.

    1. Tabellen, die Bilder enthalten, sollte ein BLOB-Feld ergänzt werden: "Bild_N" BLOB [BLOB]

    2. Beim Speichern kann der Datentyp des Bildfeldes, das beim Import erstellt wird, nicht geändert werden.

    3. Führen Sie den folgenden Befehl über Tools → SQL aus:

           UPDATE "Tabelle" SET "Bild_N" = "Image";
    

    4. Öffnen Sie den Tabelleneditor, löschen Sie die alte Spalte "Bild" und lassen Sie den Datentyp des neuen Bildfeldes nicht durch Löschen des Feldes ändern.

    5. Öffnen Sie den Tabelleneditor, fügen Sie eine neue Spalte "Bild" hinzu und lassen Sie den Datentyp eines Bildfeldes nicht durch Löschen des Feldes ändern.

    6. Führen Sie den folgenden Befehl über Extras → SQL aus:

           UPDATE "Tabelle" SET "Bild" = "Bild_N";
    

    7. Öffnen Sie den Tabelleneditor, löschen Sie die Spalte "Bild_N" und lassen Sie den Datentyp des neuen Bildfeldes nicht durch Löschen des Feldes ändern.

    Migrationsfehler bei Unterformularen und Parameterabfragen

    Aufgrund eines Fehlers in der Migration funktionieren Parameterabfragen und Unterformulare noch nicht richtig. Dazu muss leider die Datenbankdatei entpackt und die enthaltene content.xml-Datei verarbeitet werden. Diese Datei enthält fälschlicherweise folgende Angaben

       db: parameter-name-substitution = "false"
    

    Diese muss geändert werden in

       db: parameter-name-substitution = "true"
    

    oder es kann sofort vollständig entfernt werden. Anschließend kann die content.xml in die Datenbankdatei zurückgelesen werden.

    Inhalt der *.odb-Datei nach der Migration

    Der Inhalt der HSQLDB wird bei der Migration nicht aus der *.odb-Datei entfernt:

    Firebird migrated odb content.png

    Nach der Migration befindet sich neben der HSQLDB auch die Datei "firebird.fbk" in der Datenbankdatei im Unterverzeichnis "database". Diese Datei enthält die migrierten Daten und wird beim Starten der Datenbankdatei in das temporäre Verzeichnis des Betriebssystems entpackt.

    Auch die bisherigen Einstellungen der content.xml bleiben erhalten. Die entsprechende Datei wurde gerade in "content_before_migration.xml" umbenannt. Um wieder auf die Daten der HSQLDB zugreifen zu können, müsste nur die neue "content.xml" in "content_new.xml" und die Datei "content_before_migration.xml" in "content.xml" umbenannt werden.

    Nach erfolgreicher Migration können die Datei "content_before_migration.xml" und die Dateien "backup", "data", "properties" und "script" im Verzeichnis "database" gelöscht werden. Dies wird natürlich empfohlen, wenn die Datenbank bereits zuvor recht umfangreich war. Schließlich wurden die Daten während der Migration verdoppelt.

    Anpassungsfunktionen in Abfragen

    Viele Funktionen in Abfragen haben in HSQLDB und Firebird die gleichen Namen und funktionieren gleich. Beim Öffnen einer Abfrage, die zuvor in der HSQLDB funktioniert hat, kann es jedoch vorkommen, dass eine Meldung wie die folgende erscheint:

    Firebird IFNULL Fehler.png

    Die IFNULL-Funktion ist in Firebird unbekannt. Ein Blick auf die folgende Liste zeigt, dass die COALESCE-Funktion stattdessen sowohl in Firebird als auch in der internen HSQLDB verwendet werden kann. Diese Funktion ist noch universeller, da sie beliebig viele Werte abfragen kann und der erste Treffer, der nicht NULL ist, den entsprechenden Wert zurückgibt. Leider bietet der SQL-Basiseditor nicht die Möglichkeit, einen Begriff mit Suchen und Ersetzen zu teilen. Andernfalls könnte IFNULL einfach durch COALESCE ersetzt werden, wenn der Begriff in einer Abfrage häufiger vorkommt. Für solche Transformationen ist es daher ratsam, die Abfrage in einen einfachen Texteditor mit Such- und Ersetzungsfunktion zu kopieren, dann die Ersetzung vorzunehmen und den alten Inhalt damit zu überschreiben.

    Komplizierter wird es, wenn die folgende Meldung erscheint:

    Firebird Sternchen Fehler.png

    Die Fehlermeldung ist vorerst bedeutungslos. Keine nützlichen Details. Sie erschien hier zum ersten Mal, als die Funktion SUBSTRING in einer Abfrage auftauchte. Diese Funktion ist auch in Firebird bekannt, aber Firebird erlaubt nicht die kommagetrennte Kurznotation, die mit HSQLDB möglich ist. Stattdessen müssen Sie in SUBSTRING (s FROM start[FOR len]) umschreiben.

    Die folgende Tabelle gibt einen Überblick darüber, welche Merkmale möglicherweise angepasst werden müssen, da sie in Firebird nicht den gleichen Namen haben oder im schlimmsten Fall gar nicht existieren. Die Liste sagt nichts darüber aus, dass Firebird weniger Funktionen hat als die interne HSQLDB. Nur gibt es keinen Ersatz für bestimmte Funktionen.

    Eine Funktion, die in der HSQLDB- und Firebird-Spalte erscheint, kann bereits vor der Migration geändert werden. Ein Beispiel dafür ist die Kombination von mehreren Strings: CONCAT sowie die Kombination mit '+' können bereits durch '||' ersetzt werden. Diese Verbindung funktioniert in beiden internen Datenbanken. Die weitere Funktionsweise von HSQLDB ist von dieser Änderung nicht betroffen.

    Eine Funktion, die nur unter HSQLDB oder Firebird, aber nicht in der mittleren Spalte erscheint, kann noch nicht ersetzt werden. Dazu müsste zunächst die Datenbank migriert werden. Der Code von Ansichten mit einer dieser Funktionen muss an anderer Stelle gespeichert werden - z.B. als Abfrage. Eine Änderung des Codes ist erst nach der Migration möglich.

    Einige Funktionen können nicht migriert werden. Dies wird durch den roten Hinweis angezeigt.

    Datenbankfunktionen in HSQLDB und Firebird

    Die erste Spalte zeigt Funktionen der HSQLDB, die in Firebird nicht verfügbar sind. Die zweite Spalte zeigt Funktionen, die in HSQLDB und Firebird mit dem gleichen Ergebnis funktionieren. Die dritte Spalte zeigt die Funktionen von Firebird, die anstelle von Funktionen in der HSQLDB ausgewählt werden müssen. Diese Funktionen liefern das gleiche Ergebnis wie die Funktionen in der gleichen Zeile für HSQLDB, sind aber mit diesem Namen der Funktion in HSQLDB nicht verfügbar.

    Numerisch
    HSQLDB HSQLDB und Firebird Firebird
    BITAND(a,b) BIN_AND(a,b)
    BITOR(a,b) BIN_OR(a,b)
    BITXOR(a,b) BIN_XOR(a,b)
    DEGREES(d) <value for radians>*360/(2*PI())
    LOG(d) LN(d)
    RADIANS(d) <value for degrees>*2*PI()/360
    ROUNDMAGIC(d) keine Funktion vorhanden
    TRUNCATE(a,b) TRUNC(a,b)
    TEXT
    HSQLDB HSQLDB und Firebird Firebird
    ASCII(s) ASCII_VAL(s)
    BIT_LENGTH(s) Gibt die Texlänge wieder.

    HSQLDB: 16bit pro Zeichen Firebird: 8bit, Sonderzeichen 16bit. Gleiche Funktion, aber unterschiedliche Zählweise

    BIT_LENGTH(s)
    CHAR(c) ASCII_CHAR(c)
    CONCAT(str1,str2)

    'str1'+'str2'+'str3'

    'str1'‖'str2'‖'str3'
    DIFFERENCE(s1,s2) keine Funktion vorhanden
    HEXTORAW(s) keine Funktion vorhanden
    INSERT(s1,start,len,s2) OVERLAY(s1 PLACING s2 FROM start [FOR len])

    nur über "SQL-Kommando direkt ausführen"

    LCASE(s) LOWER(s)
    LENGTH(s) CHAR_LENGTH(s)

    CHARACTER_LENGTH()

    LOCATE(search,s[,start]) POSITION(search IN s) POSITION(search,s[,start])
    LTRIM(s) TRIM(LEADING FROM s)
    OCTET_LENGTH(s) Gleiche Funktion, aber unterschiedliche Zählweise
    RAWTOHEX(s) keine Funktion vorhanden
    REPEAT(s,count) keine Funktion vorhanden
    RTRIM(s) TRIM(TRAILING FROM s)
    SOUNDEX(s) keine Funktion vorhanden
    SPACE(count) keine Funktion vorhanden
    SUBSTR(s,start[,len])

    SUBSTRING(s,start[,len])

    SUBSTRING(s FROM start [ FOR len])
    UCASE(s) UPPER(s)
    DATUM/ZEIT
    HSQLDB HSQLDB und Firebird Firebird
    CURDATE() CURRENT_DATE
    CURTIME() CURRENT_TIME
    DATEDIFF(string, datetime1, datetime2)'ms'='millisecond', 'ss'='second', 'mi'='minute', 'hh'='hour', 'dd'='day', 'mm'='month', 'yy' = 'year' DATEDIFF(string, datetime1, datetime2) millisecond, second, minute, hour, day, week, month, year

    Only long version without

    DAY(date)DAYOFMONTH(date) EXTRACT(DAY FROM datetime)
    DAYNAME(date) keine Funktion vorhanden
    DAYOFWEEK(date) EXTRACT(WEEKDAY FROM datetime)

    nur über "SQL-Kommando direkt ausführen"

    DAYOFYEAR(date) EXTRACT(YEARDAY FROM datetime)

    nur über "SQL-Kommando direkt ausführen"

    HOUR(time) EXTRACT(HOUR FROM datetime)
    MINUTE(time) EXTRACT(MINUTE FROM datetime)
    MONTH(date) EXTRACT(MONTH FROM datetime)
    MONTHNAME(date) keine Funktion vorhanden
    NOW() CURRENT_TIMESTAMP
    QUARTER(date) CEILING(EXTRACT(MONTH FROM date)/3.00)
    SECOND(time) EXTRACT(SECOND FROM datetime)
    WEEK(date) EXTRACT(WEEK FROM datetime)

    nur über "SQL-Kommando direkt ausführen"

    YEAR(date) EXTRACT(YEAR FROM datetime)
    TO_CHAR(datetime, string) keine Funktion vorhanden
    Datenbankverbindung
    HSQLDB HSQLDB und Firebird Firebird
    DATABASE() RDB$GET_CONTEXT('SYSTEM', 'DB_NAME')

    nur über "SQL-Kommando direkt ausführen"

    USER()

    nur über "SQL-Kommando direkt ausführen"

    CURRENT_USER
    IDENTITY() keine Funktion vorhanden
    System
    HSQLDB HSQLDB und Firebird Firebird
    IFNULL(exp,value) COALESCE(expr1,expr2,expr3,...)
    CASEWHEN(exp,v1,v2) CASE WHEN expr1 THEN v1[WHEN expr2 THEN v2] [ELSE v4] END IIF(exp,v1,v2)(only if CASE WHEN is to complicated)
    CONVERT(term,type) CAST(term AS type)

    Weitere Informationen wie Feldtypen in HSQLDB und Firebird finden Sie unter Documentation/FirebirdMigration (engl.).