Passer de PostgreSQL à MariaDB

En bref. Jusqu'à la version 0.2.0, Agora rangeait les données de son Hub (membres, forum, candidatures, réglages, licence) dans une base PostgreSQL. Les versions suivantes utilisent MariaDB. Si tu as une installation existante, la reprise des données se fait pendant la première mise à jour vers la version MariaDB : Agora lit l'ancienne base sans la modifier, recopie tout dans la nouvelle, vérifie la copie, puis démarre. Ton ancienne base reste intacte et, si la nouvelle version ne démarre pas, Agora remet tout seul la version d'avant dessus. Sur Docker, il y a une seule chose à faire avant : relancer la commande d'installation. Sur un panel (œuf) ou un serveur Node.js, tu mets à jour comme d'habitude.

Avant de commencer #

• Tu es concerné si ton installation date d'une version qui utilisait PostgreSQL. Une installation neuve démarre directement sur MariaDB : cette page ne te concerne pas, passe à Les deux bases d'Agora.
• Fais une sauvegarde Agora avant, par habitude : Administration → Agora → Sauvegardes → Télécharger un dump maintenant, puis garde le fichier hors du serveur. Ce .sql pris sur l'ancienne version ne pourra pas être restauré sur MariaDB (le format n'est pas le même) : il sert de trace, pas de plan B. Le vrai plan B est l'ancienne base, que la conversion ne touche pas (voir plus bas).
• Prévois une courte coupure du site : il redémarre pendant la mise à jour. Choisis un moment calme.
• Garde un peu de place sur le disque : l'ancienne base reste en place et la nouvelle s'ajoute à côté.
• Les mots (base de données, migration, dump) sont dans le glossaire.

Étapes #

Docker avec install.sh #

1. Relance la commande d'installation, en root (elle garde ta clé, ton .env et tes volumes) :

   Copier

   curl -fsSL https://agorapanel.com/install.sh | sh

   Le script prépare le passage et le dit : Passage à MariaDB préparé : /opt/agora/.env réécrit (l'ancien est gardé dans /opt/agora/.env.avant-mariadb). Ton site reste sur PostgreSQL jusqu'à la mise à jour vers la version MariaDB…. Concrètement, il ajoute un conteneur agora-mariadb (volume neuf agora_mariadb), garde ton ancien conteneur agora-db et son volume agora_db, et note l'adresse de l'ancienne base dans AGORA_CONVERT_FROM. Si l'amorçage (boot.mjs) change, il redémarre Agora (Amorçage mis à jour : redémarrage d'Agora…). Ton site continue de tourner sur l'ancienne version et l'ancienne base.

2. Mets à jour Agora depuis Administration → Agora (voir Mettre à jour Agora) : c'est là que les données sont copiées.

3. Regarde la console (docker logs -f agora) pendant la mise à jour : voir « Tu sais que c'est réussi quand… ».

4. Ne coupe pas le serveur pendant la copie. Si ça arrive quand même, rien n'est perdu : voir « Si ça ne marche pas ».

Panel (œuf) ou serveur Node.js #

1. Lance la mise à jour depuis Administration → Agora (voir Mettre à jour Agora). Le panel ou le serveur garde sa base PostgreSQL intégrée (dossier .agora/pg), Agora en fait la copie dans sa nouvelle base MariaDB intégrée.
2. Premier passage avec un ancien amorçage. Si ton boot.mjs (ou agora.mjs sur un serveur Node.js) date d'avant MariaDB, la mise à jour s'arrête une première fois en le remplaçant elle-même (signature vérifiée) : la console dit cette version d'Agora tourne sur MariaDB : ton amorçage (boot.mjs) était trop ancien pour copier les données, il vient d'être mis à jour… Redémarre le serveur, puis relance la mise à jour. Fais-le : redémarre, puis relance la mise à jour. Rien n'a été modifié entre-temps.
3. Regarde la console pendant la copie : voir « Tu sais que c'est réussi quand… ».

Docker avec un compose écrit à la main #

Le nouveau compose lance MariaDB dans un volume neuf (mariadb_data). L'ancien volume PostgreSQL (db_data) n'est ni lu ni effacé, sauf pour la reprise des données, grâce à un service temporaire du profil legacy.

1. Remplace ton compose par le nouveau, et dans .env remplace POSTGRES_PASSWORD par un mot de passe MariaDB : MARIADB_ROOT_PASSWORD (long, lettres et chiffres seulement).

2. Ajoute dans .env l'ancien mot de passe PostgreSQL et l'adresse de l'ancienne base :

   Copier

   POSTGRES_PASSWORD=<ancien mot de passe PostgreSQL>
   AGORA_CONVERT_FROM=postgresql://agora:<ancien mot de passe PostgreSQL>@db-pg:5432/agora

3. Lance l'ancienne base en plus de la nouvelle, puis Agora :

   Copier

   cd /opt/agora && docker compose --profile legacy up -d

4. Suis le journal : docker compose logs -f agora. La conversion s'exécute une fois, au premier démarrage.

Base externe (option avancée) #

Si tu avais apporté ta propre base PostgreSQL via DATABASE_URL :

1. Crée une base MariaDB ou MySQL 8 vide, réservée à Agora, en utf8mb4, et son utilisateur.
2. Remplace DATABASE_URL par son adresse : mysql://utilisateur:motdepasse@hote:3306/base.
3. Ajoute AGORA_CONVERT_FROM avec l'ancienne adresse PostgreSQL (postgresql://…), puis redémarre ou lance la mise à jour : la reprise se fait comme ci-dessus. L'ancienne base n'est lue qu'en lecture.

Tu sais que c'est réussi quand… #

• La console montre, dans l'ordre : ✓ schéma à jour, reprise des données de l'ancienne base PostgreSQL (elle n'est pas modifiée)…, la liste des tables copiées, vérification…, reprise terminée : 59 tables, … lignes, … membre(s) — l'ancienne base est intacte., puis ✓ données reprises … et enfin ✓ Agora … répond : mise à jour confirmée.
• L'adresse /api/health de ton Hub répond "ok": true et "db": "ok".
• Dans Administration → Membres, tu retrouves tous tes membres, avec le même nombre d'administrateurs qu'avant ; le forum, les candidatures et tes réglages sont là.
• Ta licence est active sans rien refaire : l'installation garde la même identité pour le serveur de licences, aucun siège n'est repris (voir Libérer un siège de licence seulement si le message « sièges pris » apparaît quand même).

Si ça ne marche pas #

Dans tous les cas ci-dessous, ton ancienne base n'a pas été modifiée, la nouvelle est vidée avant de recommencer, et la version d'avant reste (ou redevient) en service : la console dit mise à jour impossible : … puis la version … reste en place.

Pour aller plus loin #

Retrouver les valeurs en double #

Le message de refus nomme la table et la colonne (par exemple User(email)) et ne montre que le début des valeurs. Pour retrouver la paire dans l'ancienne base (remplace User et email par ce que dit le message) :

docker exec agora-db psql -U agora -d agora -c 'SELECT lower(email), count(*) FROM "User" GROUP BY 1 HAVING count(*) > 1;'

Sans Docker, la même requête se lance dans ton PostgreSQL. Corrige une des deux valeurs, puis relance la mise à jour : tant que ce n'est pas fait, rien n'est copié.

Ce qui se passe pendant la conversion #

1. Agora vérifie d'abord, avant de copier quoi que ce soit, qu'aucune valeur n'en cache une autre pour MariaDB (les doublons de casse, d'accents ou d'espaces de fin décrits plus haut).
2. Il ouvre l'ancienne base en lecture seule et la fige à un instant donné : même si quelqu'un écrivait encore, il copie un état cohérent.
3. Il copie les tables dans le bon ordre (les liens entre tables sont respectés).
4. Il vérifie la copie : nombre de lignes de chaque table, empreinte de chaque ligne, absence de ligne orpheline, nombre de membres identique. Il reporte aussi l'identité de la base (db_instance_id), ce qui garde l'empreinte de licence.
5. Il pose une marque dans la nouvelle base pour ne jamais refaire la conversion au démarrage suivant, puis lance Agora.

Si une étape échoue, Agora vide la nouvelle base, remet la version d'avant sur l'ancienne base et le dit ; l'ancienne base n'a jamais été écrite.

Combien de temps ça prend #

Mesuré sur le banc : quelques secondes pour une installation de taille ordinaire (59 tables, quelques centaines de lignes). La durée suit le nombre de messages et de lignes ; nous n'avons pas mesuré un très gros forum, compte donc plus longtemps et laisse la console ouverte. Le site est indisponible pendant la mise à jour. Ne coupe pas le serveur : si tu le fais, la copie repart de zéro, sans rien perdre.

Revenir en arrière #

• Pendant la mise à jour : c'est automatique. Si la copie échoue, ou si la nouvelle version ne démarre pas, Agora remet tout seul la version d'avant sur son ancienne base (message repli vers … : la version … n'a pas démarré). Les écritures faites avant la mise à jour y sont intactes, et si tu relances ensuite la mise à jour, la copie est refaite à neuf.
• Une fois la nouvelle version confirmée (mise à jour confirmée), il n'y a plus de retour automatique : ce que tu écris ensuite n'existe que dans MariaDB, il n'est pas recopié dans l'ancienne base. Si tu dois vraiment revenir, ouvre un billet (Ouvrir un billet de support) : l'ancienne base et ton ancien .env sont gardés pour ça.

Ce qui est gardé, et jusqu'à quand #

Agora n'efface jamais l'ancienne base tout seul : elle reste jusqu'à ce que tu la supprimes.

• Docker avec install.sh : le conteneur agora-db et son volume agora_db (l'ancienne base), et le fichier /opt/agora/.env.avant-mariadb (ton ancien .env, avec l'ancien mot de passe : lisible par root seulement).
• Docker avec un compose à la main : le volume db_data, et les lignes POSTGRES_PASSWORD et AGORA_CONVERT_FROM de ton .env.
• Panel ou Node.js : le dossier .agora/pg (l'ancienne base) et .agora/pg-portable (le programme PostgreSQL). Ne supprime pas .agora/pg-converted.json : c'est la marque « déjà converti ».
• Les sauvegardes d'avant mise à jour (pre-update-…) : Agora garde les cinq dernières.

Quand supprimer l'ancienne base #

Quand tu as vécu quelques jours sur MariaDB sans souci et fait une sauvegarde Agora de la nouvelle base (Administration → Agora → Sauvegardes, téléchargée hors du serveur). Alors :

• Docker avec install.sh : retire de /opt/agora/.env les lignes AGORA_CONVERT_FROM et POSTGRES_PASSWORD, relance la commande d'installation (elle réécrit le compose sans l'ancienne base), puis cd /opt/agora && docker compose up -d --remove-orphans. Quand tu es sûr, supprime le volume : docker volume ls donne son nom complet (il finit par agora_db), puis docker volume rm <nom>. Supprime aussi .env.avant-mariadb.
• Docker avec un compose à la main : docker compose --profile legacy down, retire de .env les lignes AGORA_CONVERT_FROM et POSTGRES_PASSWORD, puis supprime le volume db_data (docker volume ls te donne son nom complet).
• Panel ou Node.js : supprime les dossiers .agora/pg et .agora/pg-portable pour libérer la place.

Ce qui change pour toi après la conversion #

• La recherche du forum trouve des mots entiers ou des débuts de mot (« concess » trouve « concession »), sans tenir compte des accents ni des majuscules. Elle ne ramène plus les mots à leur racine : « voitures » ne trouve pas « voiture » si tu tapes le pluriel entier.
• Les pseudos se comparent sans accents ni majuscules : « Élise » et « Elise » sont le même nom. Ça évite les pseudos sosies.
• Les sauvegardes d'Agora se font sans programme externe et sont d'un autre format : tes anciens .sql PostgreSQL ne se restaurent plus. Voir Sauvegardes et restauration.
• La licence ne bouge pas : même identité, même siège.
• Rien d'autre : le Hub, le MDT, la carte live, la concession et le reste fonctionnent comme avant. La base de ton serveur de jeu n'est jamais touchée par cette conversion.