13. 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).

13.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 :

Code	Signification
`0`	Succès (toutes les instructions ont réussi)
`1`	Au moins une instruction a échoué, ou un fichier `.sql` donné en argument est introuvable
`2`	Erreur à l'ouverture du serveur embarqué (dossier racine, fichier de configuration)

13.2 Options de la ligne de commande#

Option	Description	Exemple
`--root <dossier>`	Dossier racine des données à ouvrir (défaut : `data`, créé si absent). Toutes les bases qu'il contient sont chargées au démarrage.	`miraj-cli --root C:\donnees\miraj`
`--config <fichier.xml>`	Fichier de configuration XML du moteur à utiliser, à la place de `<dossier racine>\miraj.xml`. Un fichier de référence commenté est régénéré à chaque démarrage à côté de ce fichier.	`miraj-cli --config C:\conf\miraj-prod.xml`
`-d <base>`	Base de données à sélectionner après l'ouverture (équivaut à taper `USE <base>;` en première instruction).	`miraj-cli -d shop`
`-e "<SQL>"`	Exécute l'instruction (ou le script) SQL donné puis quitte, sans entrer dans le REPL. Désactive l'historique.	`miraj-cli -d shop -e "SELECT COUNT(*) FROM articles"`
`--lang <code>`	Langue des messages d'erreur et d'avertissement : `en` (défaut), `fr`, `zh`, `hi`, `es`, `ar`, `pt`, `ru`, `de`, `ja`.	`miraj-cli --lang fr`
`--json`	Affiche les résultats au format JSON plutôt qu'en tableau texte. Peut aussi être activé en cours de session avec `\json`.	`miraj-cli --json -e "SELECT * FROM articles"`
`--timing`	Affiche le temps d'exécution de chaque instruction. Peut aussi être activé en cours de session avec `\timing`.	`miraj-cli --timing`
`--no-history`	Désactive la lecture et l'écriture de l'historique persistant des instructions.	`miraj-cli --no-history`
`<fichier.sql>`	Exécute ce fichier en mode batch puis quitte (repérable à son extension `.sql`, sans être la valeur de `-e`). Le dernier argument `.sql` de la ligne de commande est retenu.	`miraj-cli migration.sql`
`--help`, `-h`, `/?`	Affiche le résumé de la syntaxe et quitte.	`miraj-cli --help`

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.

13.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 :

Commande	Rôle	Exemple
`\help`, `\h`, `help`	Affiche la liste des commandes.	`\help`
`\timing`	Bascule l'affichage du temps d'exécution (activé/désactivé).	`\timing`
`\json`	Bascule le format d'affichage des résultats entre tableau et JSON.	`\json`
`\d`	Liste les tables de la base courante (`SHOW TABLES`).	`\d`
`\d <table>`	Décrit les colonnes de la table donnée (`DESCRIBE <table>`).	`\d articles`
`\l`	Liste les bases de données du serveur (`SHOW DATABASES`).	`\l`
`\history [n]`	Affiche les `n` dernières instructions de l'historique (20 par défaut). Un nombre négatif n'affiche rien.	`\history 50`
`\!n`	Réexécute l'instruction numéro `n` de l'historique (numéro affiché par `\history`).	`\!12`
`source <fichier.sql>`, `\. <fichier.sql>`	Exécute un fichier `.sql` sans quitter le REPL.	`source migration.sql`
`\q`, `exit`, `quit`	Quitte la console.	`\q`
flèches haut / bas	Rappel des lignes précédemment saisies (console Windows).	—

13.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.

13.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" }

13.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 sur un dossier racine, miraj-cli écrit un fichier de configuration XML commenté (modèle des variables du moteur) à côté du dossier ; le personnaliser puis relancer la console applique les réglages via --config.
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.