26. La console miraj-cli

miraj-cli est la console SQL interactive de MIRAJ : elle ouvre un dossier de données (ou se connecte à un serveur démarré, voir 26.7), 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).

26.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>]
miraj-cli --host <hôte> [--port <port>] [--user <compte>] [--password]
          [--protocol auto|miraj|postgresql] [options TLS] [-d <base>] [-e "<SQL>"]
          [--json] [--timing] [--no-history] [<fichier.sql>]

Les noms des options de la console embarquée sont insensibles à la casse (--ROOT équivaut à --root) ; les options de connexion (26.7) s'écrivent en minuscules.

Codes de sortie :

26.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. Sur un dossier de données ouvert par la console, il est exécuté comme un seul lot d'instructions séparées par ;, jusqu'à la première erreur (code de sortie 1) ; la commande DELIMITER n'y est pas reconnue (erreur 1064) : un script qui en contient, comme ceux de miraj-dump, se recharge par miraj-dump restore ou par la console connectée à un serveur (26.7).
• 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 les options de connexion (26.7).

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

Exemple d'interruption d'une requête trop longue :

miraj> SET cte_max_recursion_depth = 4294967295;
OK, 0 ligne(s) affectée(s)
miraj> WITH RECURSIVE s(n) AS (SELECT 1 UNION ALL SELECT n+1 FROM s WHERE n < 1000000000) SELECT COUNT(*) FROM s;
ERREUR 1317 (70100) : Query execution was interrupted
miraj> SELECT 2;
+---+
| 2 |
+---+
| 2 |
+---+
1 ligne(s)

26.4 Utilisation interactive typique#

> miraj-cli --root C:\donnees\miraj --timing
MIRAJ 1.0.0 Entreprise - tapez \help pour l'aide, \q pour quitter.
miraj> \l
+--------------------+
| Database           |
+--------------------+
| information_schema |
| miraj              |
| performance_schema |
| shop               |
| sys                |
+--------------------+
5 ligne(s) (60.08 ms)
miraj> USE shop;
OK, 0 ligne(s) affectée(s) (56.24 ms)
shop> \d
+----------------+
| Tables_in_shop |
+----------------+
| articles       |
+----------------+
1 ligne(s) (60.12 ms)
shop> \d articles
+-------+---------------+------+-----+---------+----------------+
| Field | Type          | Null | Key | Default | Extra          |
+-------+---------------+------+-----+---------+----------------+
| id    | int(11)       | NO   | PRI | NULL    | auto_increment |
| nom   | varchar(50)   | NO   |     | NULL    |                |
| prix  | decimal(10,2) | YES  |     | NULL    |                |
| stock | int(11)       | YES  |     | 0       |                |
+-------+---------------+------+-----+---------+----------------+
4 ligne(s) (52.23 ms)
shop> SELECT nom, prix
    -> FROM articles
    -> WHERE prix > 10;
+--------+-------+
| nom    | prix  |
+--------+-------+
| Cahier | 12.90 |
+--------+-------+
1 ligne(s) (53.49 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) (58.58 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.

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

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

26.7 Console sur un serveur démarré#

Avec une option de connexion (--host, --port, --user, --password, --protocol, --ssl, --ssl-ca, --ssl-insecure, --no-ssl), la console se connecte au serveur au lieu d'ouvrir un dossier de données (--root, --config et --lang sont alors sans objet ; la langue des messages est celle du serveur).

miraj-cli --port 7007 -d shop
miraj-cli --host 10.0.0.5 --user admin --password --ssl-ca ca.pem migration.sql

> miraj-cli --port 7007 -d essai
MIRAJ 1.0.0 - connecté (langage MIRAJ) - tapez \help pour l'aide, \q pour quitter.
essai> SELECT 1 = 1 AS vrai;
+------+
| vrai |
+------+
|    1 |
+------+
1 ligne(s)
essai> SELECT * FROM absente;
ERREUR 1146 (42S02) : Table 'essai.absente' doesn't exist
essai> SELECT CAST('abc' AS SIGNED) AS n;
+---+
| n |
+---+
| 0 |
+---+
1 ligne(s)
Avertissement : Truncated incorrect INTEGER value: 'abc'
essai> \q

La même session sur une instance en langage PostgreSQL :

MIRAJ 1.0.0 - connecté (langage PostgreSQL) - tapez \help pour l'aide, \q pour quitter.
miraj=> SELECT 1 = 1 AS vrai;
+------+
| vrai |
+------+
| t    |
+------+
1 ligne(s)
miraj=> SELECT * FROM absente;
ERREUR 42P01 : relation "absente" does not exist
miraj=> \q

• Langage de l'instance : reconnu à la connexion (--protocol auto, défaut ; miraj ou postgresql l'imposent, voir 30.12). Les instructions s'écrivent dans ce langage ; l'invite le montre : base> en langage MIRAJ, base=> en langage PostgreSQL (miraj> / miraj=> sans base courante).
• Erreurs : ERREUR 1146 (42S02) : … en langage MIRAJ, ERREUR 42P01 : … (SQLSTATE) en langage PostgreSQL ; les avertissements et avis suivent le résultat. Seuls ceux que l'instruction a levés elle-même s'affichent, une seule fois : une erreur n'est pas répétée en avertissement, ni après les instructions suivantes.
• -d <base> : la base est choisie sans rien afficher (la bannière vient en premier) ; une base inconnue affiche l'erreur, et la console rendra le code de sortie 1 en quittant.
• Fichier .sql : découpé en instructions dans le langage de l'instance (chaînes, commentaires, DELIMITER en langage MIRAJ ; chaînes standard, E'…', $$…$$ en langage PostgreSQL), lu au fil de l'eau et exécuté jusqu'à la première erreur (code de sortie 1), comme miraj-dump restore, en indiquant la ligne de l'instruction fautive. Un export de miraj-dump se recharge ainsi.

  > miraj-cli --port 7007 e.sql
  OK, 0 ligne(s) affectée(s)
  ERREUR 1146 (42S02) : Table 'shop.absente' doesn't exist
    e.sql, ligne 2

• Les commandes \d, \l, \json, \timing, l'historique et source fonctionnent de même ; un résultat booléen s'affiche t / f en langage PostgreSQL.
• Code de sortie 2 : connexion impossible.