2. Installation

2.1 Requirements#

MIRAJ is distributed as ready-to-use binaries, with no external dependency to install. Choose the package that matches your system and the edition you want (see 1.3):

Each package comes with its SHA-256 fingerprint (.sha256 file).

The Enterprise and Cluster editions come with a license file miraj.lic. After installation, store it with miraj-server --root <folder> --install-license miraj.lic (or paste the license into a terminal with --install-license -): see chapter 30. Without a license, the server runs with the features and limits of the Express edition.

The Developer edition is the one for the development workstation: it offers all the features of the Cluster edition (replication, partitioning, MCP endpoint) to write and test an application, but on a single core, with at most 20 GB of data (error 9011) and 24 hours of operation between two restarts (error 9012 afterwards, data intact). It is installed by simple copy (see Manual installation); the installation wizard of 2.2 exists only for Express and Enterprise.

For Miraj Express and Miraj Enterprise on Windows, the installation wizard puts the programs in place, creates the root account, sets the port, the SQL language and automatic startup, and allows uninstalling from the Windows programs list. Without it, no installation is needed: copy the executables wherever you like and run them. The folder from which miraj-server or miraj-cli is launched does not matter: it is the data folder (--root) that determines where your databases live.

macOS package#

The package MIRAJ-<version>-Express-macos-<arch>.pkg (macOS 11 or later) installs:

The package does not create the root account itself. On first launch, Miraj Manager shows a first-configuration page: password of root (required, entered twice; the Generate and copy button picks one at random and copies it to the clipboard), port, listening (loopback interface or all interfaces) and SQL language of the instance (MIRAJ language, the default, or PostgreSQL). The server then starts through its LaunchDaemon. During an update, the server is stopped and restarted; data, keys and configuration are kept.

Uninstalling. Miraj Uninstaller offers Uninstall (data and keys are kept) or Uninstall and delete data (confirmation required, irreversible), then macOS asks for the administrator password. From the command line: sudo /usr/local/miraj-express/bin/miraj-uninstall.sh (--yes for no questions, --purge to also delete data and keys). Uninstalling removes the server, the LaunchDaemons (server, scheduled backups, remote access), the applications, the links in /usr/local/bin and the ODBC driver; a kept configuration joins the data folder. If the data was kept, reinstalling opens the Miraj Manager configuration page, which offers to keep the existing accounts (current password of root) or to define a new root password (the other accounts are then deleted, the databases remain). Details: 21.14.

Linux#

The Linux archive is unpacked wherever you like; run miraj-server as in 2.3 (Linux-style paths: ./miraj-server --root /var/lib/miraj --log). The ODBC driver is registered with the supplied script (chapter 28).

2.2 Installing Miraj Express with the installation wizard#

On Windows, Miraj Express and Miraj Enterprise are each installed by a single-file installer (MIRAJ-<version>-Express-setup.exe or MIRAJ-<version>-Entreprise-setup.exe — the same wizard for both editions): it contains miraj-server.exe, miraj.dll, miraj-cli.exe, the configuration editor (miraj-config-editor.exe) and the Miraj Server Manager (miraj-manager.exe, see 15.9), and puts them on the machine while setting the port, the root password and automatic startup. It requests administrator rights at launch (User Account Control prompt) and opens at the center of the screen, in the language of Windows; the list at the bottom left selects another one among the ten languages of the error messages (Arabic is displayed right to left). The scheduled tasks, the uninstall key and the folders created carry the name of the installed edition ("Miraj Express" or "Miraj Enterprise"): the two editions therefore install side by side without interfering.

The wizard moves forward page by page with the buttons < Back, Next > and Cancel (a confirmation is requested before quitting):

1. Welcome. If Miraj Express is already installed, the wizard detects it and offers to update or change the settings, or to uninstall; in both cases, the databases are kept. The folders, port and options of the existing installation are reused.
2. Destination folders. Program folder (default C:\Program Files\Miraj Express) and Data folder (default C:\ProgramData\Miraj Express\data), with Browse… to choose others. A data folder that already contains databases is kept as is.
3. Server settings.
   • TCP port: 7007 by default; a port already used by another program is flagged.
   • SQL language of the instance: MIRAJ language (first choice, the default) or PostgreSQL. PostgreSQL adds the POSTGRESQL element to the sql_mode of the configuration file: the port then speaks the PostgreSQL protocol (psql, PostgreSQL drivers) and no longer the legacy protocol; Gestium and the legacy-protocol tools require a MIRAJ-language instance, whereas miraj-cli, the MIRAJ tools, the MIRAJ ODBC driver and the miraj Python library adapt to both. The configuration editor lets you change this choice later, taken into account when the server restarts (see 15.10).
   • Accept connections from: this computer only (listens on 127.0.0.1) or the whole network (listens on 0.0.0.0). In the second case, the port is opened in the Windows firewall ("Miraj Express" rule); without a TLS certificate, exchanges travel in clear text (see 15. Server administration).
   • Start the server with Windows: scheduled task "Miraj Express", run at machine startup under the SYSTEM account, with no time limit and restarted if it stops (miraj-server.exe --root <data> --log).
   • Create Start menu shortcuts: "Miraj Express" folder with the manager and the configuration editor (the latter runs as administrator, the configuration file being in the program folder).
   • Start MIRAJ Manager with Windows (checked by default): the manager starts when an administrator logs on, as an icon only in the notification area (miraj-manager.exe --tray, task "Miraj Express - manager", with administrator rights and no prompt).
   • Launch MIRAJ Manager at the end of the installation (checked by default): the manager opens as soon as the server responds.
4. Administrator account. Password of the root account, entered twice (a password shorter than 8 characters is discouraged). It is passed to the server through the MIRAJ_INITIAL_ROOT_PASSWORD variable, never on a command line. On an existing data folder, the accounts are kept, including the root password; the Recreate accounts box replaces them with the local root alone, with the password entered (like --reset-accounts, see 15.5.3).
5. Ready to install. Summary of the choices; Install starts the installation.
6. Installation. A progress bar follows the steps: stopping the Miraj programs launched from the program folder (never another server on the machine; the remote access agent, if running, is first stopped cleanly), extracting the files, creating the root account, configuration, firewall, shortcuts, scheduled tasks, registration in the Windows programs list, restarting the remote access agent through its task if enabled, starting the server. Show details unfolds the log of the steps; an optional step that fails (firewall, shortcuts, manager startup) appears there as a warning without stopping the installation.
7. Finish. The wizard shows the listening address and port and the login account. On failure, the error message is displayed (with, if the server does not respond, the path of server.log) and < Back returns to the summary to fix and restart.

Installed files#

C:\Program Files\Miraj Express\
├── miraj-server.exe
├── miraj.dll
├── miraj_odbc.dll           (ODBC driver "MIRAJ ODBC Driver", declared to Windows: see chapter 28)
├── miraj-cli.exe
├── miraj-config-editor.exe
├── miraj-manager.exe
├── miraj_config.xml         (your settings, read first by the server)
├── miraj_default.xml        (reference, regenerated at each startup)
└── uninstall.exe            (uninstall from the Windows programs list)

C:\ProgramData\Miraj Express\data\
└── (databases, account vault, server.log: see 2.6)

C:\ProgramData\Miraj Express\manager\
└── (manager files, created as it is used: see 21.11)

miraj_config.xml is placed next to miraj-server.exe (see 2.5): at first installation, the server creates in it the commented template of all variables, then the wizard writes port and bind in it; the other settings are changed with the configuration editor or the manager, and apply when the server restarts. During an update, only the port and bind lines are rewritten; a configuration left in the data folder by an earlier installation is moved next to the server, with all its settings.

The ODBC driver is declared in the registry (64-bit view: HKLM\SOFTWARE\ODBC\ODBCINST.INI\MIRAJ ODBC Driver and the Installed value of ODBC Drivers); see chapter 28.

Uninstalling#

Miraj Express appears in Settings → Apps (or Control Panel → Programs and Features) under the name "Miraj Express". Uninstall opens the wizard directly on the confirmation page, which requires the root password: it is verified by a connection to the installed server, started if needed; a wrong password refuses the uninstall. The same page, and the same verification, are obtained by running miraj-express-installer.exe again and choosing Uninstall.

Uninstalling stops the server and the manager, then removes the scheduled tasks (server, manager, scheduled backups), the firewall rule, the shortcuts, the programs list entry and the program files; the ODBC driver declaration is removed. The data folder is kept, and miraj_config.xml is stored in it: a reinstall on the same folder finds the databases, accounts and settings again. Delete the data folder yourself if you no longer need it. The manager folder (C:\ProgramData\Miraj Express\manager) is likewise kept; delete it if you no longer need it.

Manual installation#

Without the wizard (other edition, workstation without administrator rights, script), copy the executables wherever you like and run miraj-server as described in 2.3.

2.3 Starting miraj-server#

miraj-server.exe --root D:\donnees --log

This command opens (or creates if it does not exist) the data folder D:\donnees, then listens on 127.0.0.1:7007. When the folder is first opened, the local root account is created with a randomly generated 24-character password, displayed only once on the console:

================================================================================
Compte root@localhost créé avec le mot de passe provisoire : Xq7mPt3hKc9WbZ2rNf8sLd4v
Il n'est affiché qu'une fois et n'est écrit nulle part : notez-le, puis changez-le :
  ALTER USER root@localhost IDENTIFIED BY 'nouveau mot de passe';
================================================================================

The startup line (version, edition, listening address, folder, thread count, license) and the configuration file in use follow:

MIRAJ 1.0.0 Entreprise - serveur console sur 127.0.0.1:7007, dossier "D:\donnees", 12 fils, licence MRJ-2026-000123 (Société Exemple SA), valide jusqu'au 2027-10-11.
Configuration : D:\donnees\miraj_config.xml.

This password is written neither to server.log nor anywhere else: note it down before closing the console. For an installation script, choose it yourself with --initial-root-password <password> or the environment variable MIRAJ_INITIAL_ROOT_PASSWORD (preferable: a command line is visible to the other users of the machine); it is then not displayed, a line only states its origin (Compte root@localhost créé avec le mot de passe initial donné par --initial-root-password (à retirer ensuite).). These settings are only used to create the account vault: afterwards, they are ignored (a note says so at startup) and root is changed with ALTER USER. A lost password is replaced with --reset-accounts (see 15. Server administration, § 15.5.3).

Command-line options#

All options accept a case-insensitive name (--Root and --root are equivalent). miraj-server --help displays the full list.

Each command-line option can also be set permanently in miraj_config.xml (see 2.5); in case of conflict, the command line wins.

2.4 Installing and using miraj-cli#

miraj-cli needs no particular installation: it is a standalone executable that works in two ways.

Connected to a server. With a connection option (--host, --port, --user, --password…), the console connects to miraj-server and recognizes the language of the instance (MIRAJ or PostgreSQL):

miraj-cli.exe --host 127.0.0.1 --port 7007 --user root --password

MIRAJ 1.0.0 - connecté (langage MIRAJ) - tapez \help pour l'aide, \q pour quitter.
miraj>

--password without a value asks for the password at the keyboard, without echo; without --password, it is read from the environment variable MIRAJ_PASSWORD if it exists. --password=<password> also works, with a warning: the command line is visible in the process list.

Embedded, on a data folder. Without a connection option, the console opens the folder directly, with no network or account (MIRAJ language):

miraj-cli.exe --root D:\donnees

MIRAJ 1.0.0 Entreprise - tapez \help pour l'aide, \q pour quitter.
miraj>

A data folder is opened by only one process at a time: as long as miraj-server serves it, this mode fails with Dossier de données « D:\donnees » déjà ouvert par un autre processus MIRAJ; go through the network instead.

Command-line options#

See 25. miraj-cli for the full reference of interactive mode commands (\d, \l, \history, source, etc.).

2.5 Configuration file#

Like a classic SQL server configuration file, MIRAJ reads an XML file at startup:

• miraj_config.xml — your settings, read at startup: the one in the folder of miraj-server.exe if it exists there, otherwise the one in the data folder (where MIRAJ creates a commented skeleton if it does not exist yet). --config forces another path; the file in use is written at startup (Configuration : …).
• miraj_default.xml, next to the previous file — regenerated at each startup, lists all recognized variables with their default value. It is a reference document only: the server never reads it back.

Order of precedence, from weakest to strongest: engine default value, then miraj_config.xml, then command-line argument.

2.6 Layout of the data folder#

The data folder (--root) is the administration unit of a MIRAJ server or console: everything that belongs to an installation lives in it.

D:\donnees\
├── miraj_config.xml         (your settings, if there are none next to miraj-server.exe)
├── miraj_default.xml        (reference, regenerated at each startup next to the previous one)
├── miraj.lck                (lock: only one process opens the folder at a time)
├── journal.reserve          (4 MiB reserved to free up space on a full disk)
├── miraj\
│   ├── accounts.mra         (encrypted account vault)
│   ├── miraj.lic            (license installed by --install-license, Enterprise and Cluster editions)
│   ├── keyring.mrk          (keyring of a folder encrypted at rest, chapter 24)
│   ├── server.log           (with --log: errors, bugs, incidents)
│   └── slow.log             (with --slow-query-log)
└── ma_base\                 (one database = one subfolder)
    ├── journal.mrl          (write-ahead log of the database)
    ├── sequences.mrq        (sequences of the database, if it has any)
    ├── clients.mrj          (one table = one .mrj file)
    ├── clients.bmrj         (externalized BLOBs of the table, if present)
    ├── archives.dmrj        (a disk table, ENGINE = Aria / MyISAM / DISK)
    └── archives.dbmrj       (large values of the disk table, if present)

• One database = one subfolder of the data folder.
• One table = one .mrj file in the subfolder of its database, in the internal MIRA v2 format.
• The BLOB values of a table whose size exceeds --lob-threshold are kept in a separate store, <table>.bmrj, next to the .mrj file.
• A disk table (see Storage engines) is a <table>.dmrj file instead of the .mrj; its values larger than a quarter page (about 4 KiB) go into <table>.dbmrj.
• Each database has its own write-ahead log, journal.mrl, replayed on opening if the last shutdown was not clean.
• journal.reserve contains no data: on a full volume, only operations that free up space (TRUNCATE, partition maintenance) consume it; it is recreated afterwards. Other writes stop well before, at the --min-free-disk-space threshold (error 1021).
• The account vault (accounts.mra) is common to the data folder; it is encrypted, and its key is stored by default outside the data folder (see below and 15. Server administration).

2.7 Default security#

• Local listening only. Without --bind, miraj-server listens only on 127.0.0.1: no remote machine can connect to it until you explicitly choose another listening address.

• Administrator account created at first launch, protected by a password. When the data folder is created, miraj-server creates the local root account with a randomly generated password, displayed only once on the console (or the one from --initial-root-password). Replace it with your own at the first connection:

  ALTER USER root@localhost IDENTIFIED BY 'un-mot-de-passe-solide';

  The embedded engine (miraj-cli on a local folder, library) does not create a vault on opening: its local root stays without a password until the folder has been used by miraj-server.

• Protected remote accounts. An account with no password reachable from another machine is refused (require_password), and the initial root account holds SYSTEM_USER: an account that only has CREATE USER can neither modify nor drop it.
• Repeated attempts slowed down. Each authentication failure delays the next response to the same address (100 ms, then double, 5 s at most); after --max-connect-errors consecutive failures (100), the address is blocked for 15 minutes. At most --max-connections clients (151) are served at once, and a handshake must complete within --connect-timeout seconds.
• TLS required as soon as a certificate is provided (--allow-plain-with-tls to also accept unencrypted clients).
• Account vault keys stored outside the data folder, by default in the profile of the account that runs the server (--key-dir to choose another location).

The details of account management, privileges, encryption in transit (TLS) and monitoring are covered in 15. Server administration and 14. Accounts and privileges.