25. La console miraj-cli

miraj-cli est la console SQL interactive de MIRAJ : elle ouvre un dossier de données, exécute des instructions SQL et affiche les résultats. Elle sert aussi bien à l'exploration interactive (REPL) qu'à l'exécution de scripts .sql en mode batch (tâches planifiées, migrations, déploiements).

25.1 Syntaxe générale#

miraj-cli [--root <dossier>] [--config <fichier.xml>] [-d <base>] [-e "<SQL>"]
          [--lang en|fr|zh|hi|es|ar|pt|ru|de|ja] [--json] [--timing] [--no-history]
          [<fichier.sql>]

Les noms d'options sont insensibles à la casse (--ROOT équivaut à --root).

Codes de sortie :

25.2 Options de la ligne de commande#

Remarques :

• -e et <fichier.sql> sont mutuellement prioritaires sur le REPL : si -e est présent, il est exécuté et la console quitte sans lire de fichier ni ouvrir de REPL ; sinon, s'il y a un argument .sql, ce fichier est exécuté ; sinon, le REPL démarre.
• -d <base> peut se combiner avec -e ou avec un fichier .sql : la base est sélectionnée avant l'exécution.
• Le fichier .sql exécuté peut contenir un BOM UTF-8 en tête, ignoré automatiquement.
• La console embarque le moteur : elle ouvre le dossier de données elle-même et en prend le verrou exclusif (miraj.lck). Tant qu'un miraj-server tient ce dossier, elle ne peut pas l'ouvrir (code de sortie 2) : se connecter alors au serveur avec un client réseau (mysql, voir chapitre 26).

25.3 Commandes internes du REPL#

Dans le REPL, une instruction SQL peut s'écrire sur plusieurs lignes ; elle est envoyée au moteur dès qu'une ligne se termine par ;. Les commandes suivantes, préfixées par \ pour la plupart, ne sont pas du SQL et s'exécutent immédiatement, sans point-virgule :

25.4 Utilisation interactive typique#

> miraj-cli --root C:\donnees\miraj --timing
MIRAJ 1.0 Entreprise - tapez \help pour l'aide, \q pour quitter.
miraj> \l
+----------+
| Database |
+----------+
| shop     |
+----------+
1 ligne(s) (0.42 ms)
miraj> USE shop;
OK, 0 ligne(s) affectée(s) (0.10 ms)
shop> \d
+-----------+
| Table     |
+-----------+
| articles  |
+-----------+
1 ligne(s) (0.08 ms)
shop> \d articles
+--------+---------------+------+-----+---------+----------------+
| Field  | Type          | Null | Key | Default | Extra          |
+--------+---------------+------+-----+---------+----------------+
| id     | int           | NO   | PRI | NULL    | auto_increment |
| nom    | varchar(50)   | NO   |     | NULL    |                |
| prix   | decimal(10,2) | YES  |     | NULL    |                |
+--------+---------------+------+-----+---------+----------------+
3 ligne(s) (0.15 ms)
shop> SELECT nom, prix
    -> FROM articles
    -> WHERE prix > 10;
+---------+-------+
| nom     | prix  |
+---------+-------+
| Cahier  | 12.90 |
+---------+-------+
1 ligne(s) (0.31 ms)
shop> \json
Résultats au format JSON
shop> SELECT nom, prix FROM articles WHERE prix > 10;
[
  {"nom": "Cahier", "prix": 12.90}
]
1 ligne(s) (0.12 ms)
shop> \q

Le prompt affiche la base courante (shop>) ou miraj> si aucune base n'est sélectionnée ; il devient -> pour la poursuite d'une instruction multi-lignes non terminée.

25.5 Exécution de scripts SQL en mode batch#

Trois façons d'exécuter un script sans passer par le REPL interactif :

# Fichier donné en argument : exécuté puis la console quitte
miraj-cli --root C:\donnees\miraj -d shop migration.sql

# Instruction ou script inline avec -e (plusieurs instructions séparées par ;)
miraj-cli --root C:\donnees\miraj -e "USE shop; DELETE FROM articles WHERE stock = 0;"

# Depuis le REPL, sans quitter la session en cours
miraj> source migration.sql

Un code de sortie différent de 0 signale un script en échec ; combiné avec --json, la sortie d'un script exécuté par -e est directement exploitable par un autre programme :

miraj-cli --root C:\donnees\miraj -d shop --json -e "SELECT id, nom FROM articles" > articles.json
if ($LASTEXITCODE -ne 0) { Write-Error "Échec du script" }

25.6 Astuces pratiques#

• Historique persistant : chaque instruction validée dans le REPL est ajoutée à %APPDATA%\MIRAJ\cli-history.sql (ou ~/.config/MIRAJ/cli-history.sql hors Windows), jusqu'à 1000 entrées conservées. Cet historique est relu au démarrage suivant et alimente \history et \!n. --no-history (ou -e, qui le désactive automatiquement) l'ignore, utile pour des scripts appelés en boucle depuis une tâche planifiée.
• Chronométrage : --timing (ou \timing en cours de session) est utile pour comparer rapidement deux formulations d'une même requête sans instrumenter un client.
• Format JSON : --json (ou \json) facilite le passage des résultats à un autre outil en ligne de commande (ConvertFrom-Json en PowerShell, jq, etc.) sans écrire de client dédié.
• Fichier de configuration : au premier démarrage, miraj-cli écrit un modèle commenté miraj_config.xml dans le dossier racine (ou au chemin donné par --config) et régénère miraj_default.xml, la référence de toutes les variables du moteur. Modifier miraj_config.xml puis relancer la console applique les réglages ; un fichier invalide ou illisible fait quitter la console avec le code 2. Contrairement à miraj-server, la console ne cherche pas de miraj_config.xml à côté de son exécutable.
• Mots de passe : une instruction qui contient un mot de passe ou une clé de chiffrement (CREATE USER … IDENTIFIED BY, SET PASSWORD, etc.) reste rejouable par \!n dans la session mais n'est jamais écrite dans le fichier d'historique.
• Erreurs : une instruction en échec affiche ERREUR <code> (<SQLSTATE>) : <message>, suivi de position : ligne L, colonne C quand l'analyseur la connaît.
• Avertissements : les avertissements de la session (troncatures, valeurs par défaut appliquées, etc.) s'affichent après le résultat de chaque instruction qui en a produit.