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.
Export der MariaDB in eine SQL-Datei
docker exec docker_mariadb mariadb-dump -u relution -p --max_allowed_packet=5G relution > relution.sqlBackup 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
- Die Datei pgloader.load → in das Verzeichnis
/opt/relution/herunterladen. - 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

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.
In der Compose-Datei entfernen:
- Den gesamten Block
mariadb:unterservices. - Den Block
pgloader:unterservices. - Das Volume
mariadb:untervolumes.
- Den gesamten Block
Im
relutionBlock anpassen:restart: on-failurewieder aufrestart: alwayszurückstellen.- Die Zeile
RELUTION_ARGUMENTS: "--database-migration-only"entfernen.
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.