Migration de MariaDB vers PostgreSQL

Ce guide décrit le processus de migration de base de données pour une instance Relution au sein d’un environnement Docker.

Prérequis #

Avant de commencer la migration, s’assurer que les conditions suivantes sont remplies :

• Espace disque : Au moins autant d’espace disque libre que la taille actuelle de la base de données MariaDB (rapport 1:1).
• Stockage S3 : Un stockage compatible S3 doit déjà être configuré.
  Documentation sur S3/SeaweedFS →
• Version : L’instance Relution doit être au minimum en version 5.31.0. La section Mettre à jour Relution → la met à jour vers la version actuelle. Pour une mise à jour de Relution 5.x vers 26.1 ou une version ultérieure, les versions intermédiaires décrites sous Mise à jour → doivent être respectées. L’initialisation du schéma et la migration des données doivent être effectuées avec la même version de Relution, car pgloader ne transfère que les données.
• PostgreSQL : Ce guide utilise l’image postgres:18. Si un serveur PostgreSQL propre est utilisé à la place, PostgreSQL 14 au minimum est requis ; sinon, Relution interrompt le démarrage.

Sauvegarde des données (optionnel) #

Si aucun snapshot de la machine virtuelle ni de sauvegarde externe n’est disponible, effectuer un export manuel ainsi qu’une sauvegarde des fichiers.

1. Export de MariaDB dans un fichier SQL

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

2. Sauvegarde des fichiers de configuration

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

Mettre à jour Relution #

S’assurer d’être à jour :

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

Arrêter les services #

Arrêter le conteneur Relution afin de garantir la cohérence des données pendant la préparation :

docker compose down relution

Adapter la configuration Docker #

Compléter le fichier Compose (compose.yaml, ou docker-compose.yml pour les installations plus anciennes). Ajouter les services pgloader et la nouvelle database (PostgreSQL), et adapter le bloc relution.

Ajouter les nouveaux services #

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

Adapter le bloc Relution existant #

Modifier les dépendances et ajouter l’argument de migration :

  relution:
    image: relution/relution:latest
    restart: on-failure # Modifié : always remplacé par on-failure
    container_name: docker_relution
    networks:
      relution-network:
        aliases:
          - relution-docker
    depends_on:
      - database # Auparavant : mariadb
    environment: # remplacer l'ancienne notation en liste (ex. "- TZ=Europe/Berlin") si présente, ne pas la mélanger avec la notation par mapping
      TZ: "Europe/Berlin"
      RELUTION_ARGUMENTS: "--database-migration-only" # Ajouté

volumes:
  mariadb:
  postgresql: # Ajouté

Configuration de pgloader #

1. Télécharger le fichier pgloader.load → dans le répertoire /opt/relution/.
2. Adapter la configuration à l’environnement concerné.

     FROM mysql://relution:dbpassword@mariadb-docker:3306/relution
     INTO postgresql://relution:dbpassword@database:5432/relution

Si le nom de la base de données MariaDB diffère de relution, la ligne ALTER SCHEMA 'relution' RENAME TO 'public' du fichier pgloader.load est également adaptée à ce nom.

Initialiser le schéma de la base de données #

Adapter d’abord l’application.yml afin que Relution sache qu’il doit désormais utiliser PostgreSQL :

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

Si la base de données n’est pas configurée dans l’application.yml, mais via les variables d’environnement DATABASE_TYPE, DATABASE_URL, DATABASE_USER et DATABASE_PWD dans le bloc relution du fichier Compose, ce sont ces variables qui sont adaptées en conséquence.

Démarrer maintenant PostgreSQL et Relution. En raison du flag --database-migration-only, Relution va uniquement créer le schéma dans PostgreSQL, puis s’arrêter.

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

Le processus est terminé lorsque le conteneur s’est arrêté avec le code 0 : docker_relution exited with code 0

Effectuer la migration des données #

Démarrer le conteneur pgloader et exécuter la migration des données de MariaDB vers PostgreSQL :

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

À l’intérieur du conteneur, exécuter la commande de migration :

pgloader pgloader.load

Nettoyage et finalisation #

Après une migration réussie, les configurations temporaires et l’ancien conteneur MariaDB doivent être supprimés.

1. Supprimer dans le fichier Compose :

   • L’ensemble du bloc mariadb: sous services.
   • Le bloc pgloader: sous services.
   • Le volume mariadb: sous volumes.

2. Adapter le bloc relution :

   • Remettre restart: on-failure sur restart: always.
   • Supprimer la ligne RELUTION_ARGUMENTS: "--database-migration-only".

3. Nettoyer :

   rm pgloader.load
   

Redémarrer les services : Arrêter tout pour supprimer les conteneurs orphelins, puis redémarrer le système :

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

La migration est ainsi terminée et Relution fonctionne désormais nativement sur PostgreSQL.