Migration MariaDB zu PostgreSQL

Dieser Leitfaden beschreibt den Prozess der Datenbankmigration für eine Relution-Instanz innerhalb einer Docker-Umgebung.


Voraussetzungen

Vor Beginn der Migration sicherstellen, dass folgende Bedingungen erfüllt sind:

  • Speicherplatz: Mindestens so viel freier Speicherplatz wie die aktuelle MariaDB-Datenbank groß ist (1:1 Verhältnis).
  • S3 Speicher: Ein kompatibler S3-Speicher muss bereits eingerichtet sein.
    Dokumentation zu S3/SeaweedFS →
  • Version: Die Relution-Instanz muss mindestens Version 5.31.0 haben. Im Abschnitt Relution aktualisieren → wird sie auf die aktuelle Version gebracht. Bei einem Update von Relution 5.x auf 26.1 oder neuer sind dabei die Zwischenversionen unter Update → einzuhalten. Schema-Initialisierung und Datenmigration müssen mit derselben Relution-Version erfolgen, da pgloader nur die Daten überträgt.
  • PostgreSQL: Die Anleitung verwendet das Image postgres:18. Wird stattdessen ein eigener PostgreSQL-Server verwendet, ist mindestens PostgreSQL 14 erforderlich, sonst bricht Relution den Start ab.

Datensicherung (Optional)

Falls keine Snapshots der virtuellen Maschine oder externe Backups vorhanden sind, einen manuellen Export und eine Dateisicherung durchführen.

  1. Export der MariaDB in eine SQL-Datei

    docker exec docker_mariadb mariadb-dump -u relution -p --max_allowed_packet=5G relution > relution.sql
    
  2. Backup der Konfigurationsdateien

    cd /opt/relution/ && zip -r backup.zip ./*
    

Relution aktualisieren

Sicherstellen, dass die Installation auf dem neuesten Stand ist:

cd /opt/relution/ && docker compose pull && docker compose up -d

Dienste stoppen

Den Relution-Container stoppen, um Datenkonsistenz während der Vorbereitung zu gewährleisten:

docker compose down relution

Docker-Konfiguration anpassen

Die eigene Compose-Datei (compose.yaml, bei älteren Installationen docker-compose.yml) ergänzen. Die Services für pgloader und die neue database (PostgreSQL) hinzufügen und den relution-Block anpassen.

Neue Services hinzufügen

services:
  pgloader:
    image: ghcr.io/dimitri/pgloader:latest
    networks:
      - relution-network
    volumes:
      - "./pgloader.load:/pgloader.load"
    tty: true

  database:
    image: postgres:18
    restart: unless-stopped
    container_name: database
    environment:
      TZ: "Europe/Berlin"
      POSTGRES_DB: "relution"
      POSTGRES_USER: "relution"
      POSTGRES_PASSWORD: "$PASSWORD"
    expose:
      - "5432"
    volumes:
      - "postgresql:/var/lib/postgresql"
    networks:
      - relution-network

Bestehenden Relution-Block anpassen

Die Abhängigkeiten ändern und das Migrations-Argument hinzufügen:

  relution:
    image: relution/relution:latest
    restart: on-failure # Geändert von always auf on-failure
    container_name: docker_relution
    networks:
      relution-network:
        aliases:
          - relution-docker
    depends_on:
      - database # Geändert von mariadb
    environment: # ggf. alte Listen-Schreibweise (z. B. "- TZ=Europe/Berlin") ersetzen, nicht mit der Mapping-Schreibweise mischen
      TZ: "Europe/Berlin"
      RELUTION_ARGUMENTS: "--database-migration-only" # Neu hinzugefügt

volumes:
  mariadb:
  postgresql: # Neu hinzugefügt

pgloader Konfiguration

  1. Die Datei pgloader.load → in das Verzeichnis /opt/relution/ herunterladen.
  2. Die Konfiguration an die eigene Umgebung anpassen.
     FROM mysql://relution:dbpassword@mariadb-docker:3306/relution
     INTO postgresql://relution:dbpassword@database:5432/relution

Weicht der Name der MariaDB-Datenbank von relution ab, wird zusätzlich die Zeile ALTER SCHEMA 'relution' RENAME TO 'public' in der pgloader.load an diesen Namen angepasst.

Die Vorlage ist auf große Datenbanken ausgelegt: pgloader hält nur wenige Zeilen gleichzeitig im Arbeitsspeicher, und MariaDB bricht die Verbindung bei längeren Pausen nicht ab. Mit disable triggers schaltet pgloader die Fremdschlüsselprüfung während des Imports ab. Dafür braucht der Benutzer in der INTO-Zeile Superuser-Rechte. Im Docker-Setup dieser Anleitung ist das gegeben, bei einem eigenen PostgreSQL-Server muss es geprüft werden.


Datenbank-Schema initialisieren

Zuerst die application.yml anpassen, damit Relution weiß, dass nun PostgreSQL genutzt wird:

relution:
  database:
    type: postgresql
    url: jdbc:postgresql://database/relution?currentSchema=public
    username: relution
    password: $PASSWORD

Wird die Datenbank nicht in der application.yml, sondern über die Umgebungsvariablen DATABASE_TYPE, DATABASE_URL, DATABASE_USER und DATABASE_PWD im relution-Block der Compose-Datei konfiguriert, werden stattdessen diese Variablen entsprechend angepasst.

Nun PostgreSQL und Relution starten. Relution wird aufgrund des Flags --database-migration-only nur das Schema in PostgreSQL erstellen und sich dann beenden.

docker compose up -d database && docker compose up relution

Der Prozess ist abgeschlossen, wenn der Container mit Code 0 beendet wurde: docker_relution exited with code 0

Docker-Container beendet sich mit Code 0 nach erfolgreicher Schema-Initialisierung


Datenmigration durchführen

Den pgloader-Container starten und die Migration der Daten von MariaDB zu PostgreSQL durchführen:

docker compose up -d pgloader && docker compose exec pgloader bash

Innerhalb des Containers den Migrationsbefehl ausführen:

pgloader pgloader.load

pgloader Datenmigration von MariaDB zu PostgreSQL erfolgreich abgeschlossen


Bereinigung und Abschluss

Nach erfolgreicher Migration müssen die temporären Konfigurationen und der alte MariaDB-Container entfernt werden.

  1. In der Compose-Datei entfernen:

    • Den gesamten Block mariadb: unter services.
    • Den Block pgloader: unter services.
    • Das Volume mariadb: unter volumes.
  2. Im relution Block anpassen:

    • restart: on-failure wieder auf restart: always zurückstellen.
    • Die Zeile RELUTION_ARGUMENTS: "--database-migration-only" entfernen.
  3. Aufräumen:

    rm pgloader.load
    

Dienste neu starten: Alles herunterfahren, um verwaiste Container zu löschen, und das System neu starten:

docker compose down --remove-orphans && docker compose up -d

Die Migration ist damit abgeschlossen und Relution läuft nun nativ auf PostgreSQL.

Wie hilfreich war dieser Artikel?