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 sollte auf die die Version 26.0.0 aktualisiert werden, mindestens jedoch auf Version 5.31.0 aktualisiert sein.

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 ./*
   

Vorbereitung der Umgebung #

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 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

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?useServerPrepStmts=true
    username: relution
    password: $PASSWORD

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

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

Bereinigung und Abschluss #

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

1. In der docker-compose.yml entfernen:

   • Den gesamten Block mariadb: unter services.
   • Den Block pgloader: unter services.
   • Das Volume mariadb: unter volumes.

2. Im relution Block anpassen:

   • restart: unless-stopped (wieder zurückstellen auf always).
   • Entfernen der Zeile: - RELUTION_ARGUMENTS=--database-migration-only.

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.