17. L'outil de migration miraj-migrate

miraj-migrate copie une base SQL existante (schéma, vues et lignes) vers un serveur MIRAJ en marche. Il lit la source en lecture seule, par le protocole réseau : la source n'est ni arrêtée ni modifiée, et l'outil peut donc être rejoué autant de fois que nécessaire avant la bascule.

17.1 Syntaxe générale#

miraj-migrate inspect --source-db <base> [options de la source]
miraj-migrate run     --source-db <base> [options de la source et de la cible]
                      [--drop-existing] [--skip-data] [--batch-rows <n>] [--only t1,t2]
miraj-migrate --help

Codes de sortie :

Code	Signification
`0`	Succès : tout est migré et vérifié
`1`	Erreur (option invalide, connexion impossible, base source inconnue) ou au moins un objet en échec

17.2 Commandes#

Commande	Effet
`inspect`	Liste les tables de la base source avec leur nombre de lignes, les vues, puis les objets qui ne seront pas migrés (déclencheurs, routines, événements). N'écrit rien. À lancer en premier pour évaluer le chantier.
`run`	Crée la base cible si elle n'existe pas, y recrée les tables puis les vues, copie les lignes et vérifie chaque table.

17.3 Options#

Source

Option	Description	Défaut
`--source-db <base>`	Base à migrer (obligatoire).	—
`--source-host <hôte>`	Hôte du serveur source.	`127.0.0.1`
`--source-port <port>`	Port du serveur source.	`3306`
`--source-user <compte>`	Compte de lecture.	`root`
`--source-password <mot de passe>`	Mot de passe du compte. Peut aussi venir de la variable d'environnement `MIRAJ_SOURCE_PASSWORD`.	aucun

Cible (serveur MIRAJ)

Option	Description	Défaut
`--host <hôte>`	Hôte du serveur MIRAJ.	`127.0.0.1`
`--port <port>`	Port du serveur MIRAJ.	`7007`
`--user <compte>`	Compte à utiliser (droits de création de base et de table).	`root`
`--password <mot de passe>`	Mot de passe. Peut aussi venir de `MIRAJ_PASSWORD`.	aucun
`--db <base>`	Base créée sur le serveur MIRAJ.	nom de la base source

Comportement de run

Option	Description
`--drop-existing`	Supprime d'abord les tables et vues de même nom sur la cible. Sans cette option, une table déjà présente est un échec (erreur 1050) et n'est pas touchée.
`--skip-data`	Ne recrée que le schéma, sans copier les lignes.
`--only t1,t2`	Ne migre que les tables et vues nommées (noms séparés par des virgules, casse ignorée).
`--batch-rows <n>`	Nombre maximal de lignes par `INSERT` (défaut 500 ; un `INSERT` est aussi coupé à 1 Mio de SQL).

Sur la ligne de commande, un mot de passe est visible dans la liste des processus : préférer les variables d'environnement pour un usage en production.

17.4 Déroulement d'une migration#

Connexion à la source et à la cible (les deux en UTF-8 complet, emoji compris) ; création de la base cible si nécessaire.
Pour chaque table : lecture de sa définition sur la source, création sur la cible (avec --drop-existing, suppression préalable), puis copie des lignes par INSERT multi-lignes.
Vérification : le nombre de lignes de la source, celui des lignes lues et celui de la cible doivent être identiques.
Pour chaque vue : création sur la cible, puis lecture de contrôle (SELECT … LIMIT 1). Le compte DEFINER de la source est retiré, car il n'existe généralement pas sur la cible.
Bilan : nombre de tables migrées, liste des échecs, liste des objets à reprendre à la main.

Les tables sont traitées l'une après l'autre ; un échec sur une table n'arrête pas les suivantes. Les contraintes de clé étrangère sont recréées avec la table ; la copie se fait sans vérification de l'ordre entre tables, la source ayant déjà garanti la cohérence.

Exemple :

> miraj-migrate inspect --source-db gestion --source-host 10.0.0.5 --source-user lecture
Base source « gestion » ([email protected]:3306) : 2 table(s), 1 vue(s)
  table clients          3001 ligne(s)
  table lignes          15005 ligne(s)
  vue   v_soldes
Total : 18006 ligne(s)

> miraj-migrate run --source-db gestion --source-host 10.0.0.5 --source-user lecture --drop-existing
Migration de « gestion » ([email protected]:3306) vers « gestion » ([email protected]:7007)
  table clients          3001 ligne(s) copiée(s), vérifiée(s)
  table lignes          15005 ligne(s) copiée(s), vérifiée(s)
  vue   v_soldes         créée
Bilan : 2 table(s) migrée(s), 0 échec(s)

17.5 Ce qui n'est pas migré#

Déclencheurs, routines stockées et événements : ils sont seulement listés (« À reprendre manuellement »). Leur corps dépend du dialecte de la source et doit être relu, puis recréé avec le SQL de MIRAJ (chapitres 5 et 6).
Comptes et privilèges : à recréer avec CREATE USER et GRANT (chapitre 10).
Écritures concurrentes : la copie n'est pas un instantané. Pour une base encore utilisée, suspendre les écritures pendant run, ou relancer run --drop-existing juste avant la bascule.
Contenu : la vérification compare des nombres de lignes, pas les valeurs. Pour un contrôle plus fort, comparer des agrégats ou une empreinte par table sur les deux serveurs.

Les définitions de tables sont rejouées telles que la source les fournit : une clause que MIRAJ refuse apparaît comme un échec de cette table, avec le message d'erreur du serveur MIRAJ (chapitre 15).

17.6 Messages d'erreur courants#

Message	Cause
`--source-db est obligatoire`	Base source non indiquée.
`connexion source (…) impossible` / `connexion cible (…) impossible`	Hôte, port ou compte incorrect, ou serveur arrêté.
`base source « x » : erreur SQL 1049`	La base source n'existe pas.
`création : erreur SQL 1050`	La table existe déjà sur la cible : ajouter `--drop-existing`.
`nombre de lignes : source …, lues …, cible …`	Écarts après copie : vérifier le journal du serveur (`--log`) et relancer.
`vue créée mais illisible`	La vue référence un objet absent de la cible (table en échec, fonction non portée).