1. Introduction

1.1 Qu'est-ce que MIRAJ#

MIRAJ est un moteur de base de données SQL relationnel en colonnes, en mémoire et durable, développé par CIRTASOFT (https://cirtasoft.com/mirajdb). Il stocke les données de chaque table colonne par colonne, garde ces colonnes en mémoire pour l'exécution des requêtes, et assure la durabilité des écritures par un journal d'écriture rejoué au redémarrage.

MIRAJ est aussi optimisé pour l'intelligence artificielle. Parce que les données résident en mémoire vive (RAM) plutôt que sur disque dur, les lectures ne subissent pas la latence des accès disque : les charges typiques de l'IA (préparation et exploration de grands jeux de données, extraction de caractéristiques, requêtes répétées et concurrentes d'agents ou de services d'inférence, recherche par similarité avec la recherche vectorielle) s'exécutent à la vitesse de la mémoire, sans renoncer à la durabilité assurée par le journal d'écriture.

Enfin, MIRAJ propose une option MCP : le serveur peut ouvrir un point d'accès pour les assistants d'intelligence artificielle (Claude Code, ou tout client du protocole Model Context Protocol). L'assistant explore la structure des bases, lit ou modifie les données, voire administre le serveur, sans pilote ni mot de passe : il reçoit un jeton créé en SQL, lié à un compte et plafonné à un niveau d'accès (STRUCTURE, READ, WRITE, ADMIN). L'option est désactivée par défaut et n'est pas disponible dans l'édition Express ; voir le chapitre 20.

MIRAJ s'adresse :

• aux développeurs qui veulent embarquer un moteur SQL rapide dans une application (bureau, service, outil de traitement de données) sans dépendre d'un serveur externe ;
• aux développeurs qui construisent des applications client/serveur classiques et veulent un serveur SQL accessible par le réseau, compatible avec les outils et connecteurs existants ;
• aux administrateurs de bases de données (DBA) qui exploitent un ou plusieurs serveurs MIRAJ : création de comptes, gestion des privilèges, surveillance, sauvegardes, réplication.

Cas d'usage typiques : applications métier avec une base locale embarquée, serveur de données pour une application client/serveur ou web, calculs analytiques sur des volumes tenant en mémoire (les grosses tables d'historique pouvant rester sur disque), applications d'intelligence artificielle (données d'entraînement, contexte pour agents, recherche vectorielle), assistants IA branchés sur les bases par l'option MCP, consolidation de plusieurs bases derrière un même serveur, déploiement en grappe pour la disponibilité en lecture.

Ce manuel s'adresse aux utilisateurs finaux de MIRAJ (développeurs et DBA) : il décrit le langage SQL, les outils fournis (miraj-cli, miraj-server) et leur administration. Il ne décrit pas l'implémentation interne du moteur.

1.2 Les trois façons d'utiliser MIRAJ#

Ces trois modes partagent le même moteur et le même format de fichier de données : une base ouverte en embarqué peut être servie plus tard par miraj-server, et inversement. Un dossier de données n'est ouvert que par un processus à la fois : pendant que miraj-server tourne, la console et les applications passent par le réseau.

Deux langages SQL : MIRAJ ou PostgreSQL#

Une instance de miraj-server parle l'un des deux langages, choisi au démarrage pour toute l'instance :

• le langage MIRAJ (par défaut), décrit par les chapitres 6 à 10, 14 et 15 de ce manuel et par les chapitres thématiques qui suivent ;
• le langage PostgreSQL (élément POSTGRESQL de sql_mode, voir 16.10) : le port parle alors le protocole et la grammaire de PostgreSQL, pour psql, psycopg2, pgjdbc, Npgsql et les autres clients PostgreSQL. Il a son propre manuel, en syntaxe PostgreSQL : chapitres 32 à 41.

Le moteur, les fichiers de données, l'administration, le cluster et les sauvegardes sont les mêmes dans les deux cas. Les outils de MIRAJ (miraj-cli, miraj-dump, miraj-backup, miraj-migrate, les gestionnaires), le pilote ODBC et la bibliothèque Python miraj reconnaissent le langage de l'instance à la connexion. La prise en main montre le même exemple dans les deux langages.

1.3 Les éditions du produit#

MIRAJ est distribué en quatre éditions, produites à partir du même code :

L'option MCP (assistants IA, chapitre 20) est disponible dans les éditions Entreprise, Cluster et Developer, pas dans Express. Il en va de même de la réplication par journal binaire au format de la référence (MIRAJ source ou réplica d'un serveur de la référence, chapitre 17, §17.13), distincte de la réplication de cluster. Le chiffrement des données au repos (chapitre 25) appartient aux seules éditions Entreprise et Cluster.

Les quatre éditions parlent le même SQL et lisent les mêmes fichiers de données ; seules la répartition du travail entre cœurs, le plafond de données des éditions Express et Developer, la durée de fonctionnement de l'édition Developer et la réplication changent.

Les éditions Entreprise et Cluster demandent une licence, un fichier miraj.lic vérifié sur la machine sans aucune connexion (chapitre 31). Sans licence valide, le serveur démarre quand même, avec les fonctions et les limites de l'édition Express.

Savoir quelle édition on utilise#

SELECT @@miraj_edition, @@version_comment, VERSION();

+-----------------+------------------------------------+--------------------+
| @@miraj_edition | @@version_comment                  | VERSION()          |
+-----------------+------------------------------------+--------------------+
| Entreprise      | MIRAJ columnar engine (Entreprise) | 8.0.40-miraj-1.0.0 |
+-----------------+------------------------------------+--------------------+
1 ligne(s)

@@miraj_edition vaut Entreprise, Express, Cluster ou Developer. SHOW ENGINES rappelle aussi l'édition dans le commentaire du moteur par défaut :

SHOW ENGINES;

+--------+---------+-------------------------------------------------+--------------+-----+------------+
| Engine | Support | Comment                                         | Transactions | XA  | Savepoints |
+--------+---------+-------------------------------------------------+--------------+-----+------------+
| MIRAJ  | DEFAULT | In-memory columnar storage (Entreprise edition) | YES          | YES | YES        |
| DISK   | YES     | Row storage on disk, indexes in memory          | YES          | YES | YES        |
| Aria   | YES     | Alias of DISK                                   | YES          | YES | YES        |
| MyISAM | YES     | Alias of DISK                                   | YES          | YES | YES        |
+--------+---------+-------------------------------------------------+--------------+-----+------------+
4 ligne(s)

VERSION() rend le même numéro de version quelle que soit l'édition (8.0.40-miraj-1.0.0 : numéro de compatibilité puis version de MIRAJ, voir VERSION) ; c'est @@miraj_edition, @@version_comment et SHOW ENGINES qui distinguent Entreprise, Express, Cluster et Developer.

1.4 Aperçu de l'architecture#

Vu depuis l'extérieur, un moteur MIRAJ repose sur quatre principes :

• Stockage en colonnes, en mémoire. Chaque colonne d'une table est rangée séparément, avec un indicateur de valeur absente (NULL) par colonne et une compression par dictionnaire ; les données travaillées par les requêtes résident en mémoire, le disque servant de support de durabilité. Pour les grosses tables peu consultées (historiques, archives), une table peut aussi être déclarée sur disque (ENGINE = Aria, MyISAM ou DISK) : ses lignes restent dans son fichier et seuls ses index occupent la mémoire (voir Moteurs de stockage).
• Journal d'écriture pour la durabilité. Toute écriture passe par un journal avant d'être considérée acquise ; des points de sauvegarde périodiques limitent le travail à rejouer après un arrêt brutal, qu'il s'agisse d'un arrêt du processus, d'une coupure de courant ou d'un arrêt du système.
• Exécution vectorisée. Les requêtes ne traitent pas les lignes une par une : elles opèrent par lots de plusieurs milliers de lignes à la fois, ce qui réduit le travail répété par ligne et tire parti du matériel moderne.
• Transactions. Chaque session peut travailler en transaction (START TRANSACTION, COMMIT, ROLLBACK), avec un isolement sérialisable qui ne bloque jamais un lecteur en attente d'un écrivain.

Ce manuel reste à ce niveau : il ne détaille pas l'organisation interne du moteur (les couches internes, les formats binaires) au-delà de ce qui est utile pour l'exploiter, le configurer et l'administrer.

1.5 Sommaire du manuel#

1. Introduction — ce document : modes d'utilisation, langages SQL, éditions, architecture, sommaire
2. Installation — paquets Windows, macOS et Linux, assistant d'installation, options de miraj-server et miraj-cli, fichier de configuration, dossier de données, sécurité par défaut
3. Prise en main — premier pas à pas dans les deux langages : serveur, connexion, base, tables, données, requêtes, jointures, transaction, index, schéma
4. Comparatif des éditions — Express, Developer, Enterprise et Cluster côte à côte
5. Notes de version — changements de chaque version, de la plus récente à la plus ancienne
6. Types de données — entiers, décimaux exacts, flottants, chaînes, binaires et BLOB, dates, ENUM/SET, JSON, UUID, colonnes dynamiques, VECTOR, conversions, DEFAULT, AUTO_INCREMENT, colonnes générées, CHECK
7. Langage DDL — bases, tables, ALTER TABLE, index (dont FULLTEXT et trigrammes), vues, moteurs de stockage (tables en mémoire ou sur disque), partitionnement, clés étrangères, séquences, routines, maintenance des tables (CHECK, REPAIR, OPTIMIZE)
8. Langage DML — INSERT, REPLACE, ON DUPLICATE KEY UPDATE, UPDATE, DELETE, requêtes paramétrées, PREPARE/EXECUTE, LOAD DATA et LOAD XML
9. Requêtes SELECT — jointures, agrégation, tri, sous-requêtes, UNION/INTERSECT/EXCEPT, WITH, fenêtres, verrous de lecture, EXPLAIN, recherche plein texte MATCH … AGAINST
10. Fonctions SQL — chaînes, nombres, dates, contrôle, agrégats, expressions régulières, hachage et chiffrement, réseau, système, JSON, vecteurs, fenêtres, séquences, fonctions spatiales
11. Recherche vectorielle — VECTOR INDEX (HNSW), k plus proches voisins, mhnsw_ef_search, USING hnsw
12. Tables temporelles — WITH SYSTEM VERSIONING, FOR SYSTEM_TIME AS OF | FROM … TO | BETWEEN | ALL, DELETE HISTORY, périodes applicatives (PERIOD FOR, FOR PORTION OF, WITHOUT OVERLAPS), PARTITION BY SYSTEM_TIME
13. Interclassements — utf8mb4_general_ci, utf8mb4_unicode_ci, utf8mb4_bin : par colonne, table ou expression (COLLATE), coercibilité, erreurs 1253 / 1273
14. Transactions et concurrence — autocommit, modèle de concurrence multiversion, mise à jour différée, LOCK TABLES, SAVEPOINT, transactions XA
15. Comptes et privilèges — authentification, CREATE/ALTER/DROP USER, GRANT/REVOKE, rôles, audit des droits
16. Administration du serveur — démarrage et arrêt, options, configuration, durabilité, sécurité (comptes, TLS), supervision, journaux, instance en langage PostgreSQL (16.10)
17. Cluster et réplication — édition Cluster : primaire et secondaires, certificats, bascule, tables réparties entre nœuds ; réplication par journal binaire
18. miraj-migrate — migration d'une base SQL existante vers MIRAJ
19. Sauvegarde et restauration — BACKUP / RESTORE à chaud, archivage continu du journal, miraj-backup, export SQL miraj-dump
20. Serveur MCP — assistants IA sur MIRAJ : --mcp ON, jetons CREATE MCP TOKEN, niveaux STRUCTURE/READ/WRITE/ADMIN, outils
21. Événements de changement — LISTEN / NOTIFY / WAIT FOR CHANGES : être prévenu des écritures sans interroger la base, reprise après coupure, abonnés sur un nœud du cluster
22. Miraj Server Manager — gestionnaire graphique Windows et macOS : démarrage et arrêt, état, ressources, requêtes lentes, sauvegardes
23. miraj-proxy — répartition de charge d'un cluster : port d'écriture vers le primaire, port de lecture vers le nœud le moins chargé, bascule, en-tête PROXY
24. API REST — MIRAJ sur HTTP/HTTPS : --rest ON, API écrites en SQL (CREATE ENDPOINT), tables, SQL libre, jetons CREATE API TOKEN … ACCESS
25. Chiffrement au repos — éditions Entreprise et Cluster : dossier chiffré à l'initialisation, phrase secrète, ENCRYPTION par base et par table, miraj-keyring, rotation de la clé
26. miraj-cli — référence de la console SQL : options, connexion à un serveur, commandes du mode interactif
27. Bibliothèques clientes — API embarquée miraj.dll et ses enveloppes (C#, Python, Java, PHP, Node.js, Go, C/C++, Delphi), bibliothèque Python miraj pour le serveur
28. Codes d'erreur — référence des codes et messages
29. Pilote ODBC — MIRAJ ODBC Driver natif : installation (Windows, macOS, Linux), chaîne de connexion, DSN, Excel, Power BI, Access, LibreOffice, pyodbc, instance en langage PostgreSQL
30. Langage PostgreSQL — référence condensée de la grammaire d'une instance en langage PostgreSQL : lexique ("x", E'…', $$…$$, $1), conversions ::, ILIKE, FETCH FIRST, SET search_path, curseurs, extensions MIRAJ gardées, outils MIRAJ, pilote ODBC et bibliothèque Python sur une instance PostgreSQL
31. Licence des éditions Entreprise et Cluster — fichier miraj.lic vérifié sans connexion : installation (--install-license), titulaire (@@miraj_license_owner, SHOW LICENSE), FLUSH LICENSE, comportement sans licence ou à l'expiration, licence liée à une machine, une licence par cluster
32. PostgreSQL : Prise en main — démarrer l'instance, se connecter avec psql, miraj-cli ou un pilote, premier schéma
33. PostgreSQL : Types de données — integer, numeric, text, bytea, timestamptz, interval, json/jsonb, uuid, vector, conversions ::, serial et identité
34. PostgreSQL : Langage DDL — schémas et search_path, tables, contraintes, ALTER TABLE, index, vues, séquences, commentaires
35. PostgreSQL : Langage DML — INSERT, UPDATE … FROM, DELETE … USING, RETURNING, ON CONFLICT, TRUNCATE, COPY, paramètres
36. PostgreSQL : Requêtes SELECT — jointures, agrégats, FETCH FIRST, opérations ensemblistes, WITH, fenêtres, FOR UPDATE, EXPLAIN
37. PostgreSQL : Fonctions SQL — opérateurs, chaînes, motifs, nombres, dates et intervalles, to_char, agrégats, fenêtres, JSON, conversions, octets et hachage
38. PostgreSQL : Transactions et session — BEGIN, points de sauvegarde, isolement, SET/SHOW/RESET, search_path, fuseau horaire, curseurs, transactions en deux phases
39. PostgreSQL : Comptes et privilèges — rôles, GRANT/REVOKE, authentification SCRAM
40. PostgreSQL : Routines et déclencheurs (PL/pgSQL) — fonctions, procédures et CALL, langage PL/pgSQL, messages et erreurs, déclencheurs
41. PostgreSQL : Catalogue et outils — pg_catalog, information_schema, psql, pilotes, outils MIRAJ, sauvegarde