Mirajv1.0
FR
EnglishFrançais

28. Pilote ODBC

MIRAJ ODBC Driver est le pilote ODBC natif de MIRAJ. Il parle le protocole MySQL à miraj-server (port 7007 par défaut) et n'a besoin d'aucun autre composant : ni MariaDB Connector/ODBC, ni bibliothèque cliente MySQL. Il vise le niveau Core et le niveau 1 de l'API ODBC 3.8, en 64 bits, pour les applications qui lisent MIRAJ par ODBC : Excel, Power BI, Access (tables liées), LibreOffice Base, pyodbc, FireDAC (Delphi), DBeaver.

SystèmeBibliothèqueInstallée par
Windows 64 bitsmiraj_odbc.dlll'assistant d'installation (dossier du programme) ou le zip
macOS (Apple silicon)/usr/local/miraj-express/lib/libmiraj_odbc.dylible paquet .pkg
Linux 64 bitslibmiraj_odbc.sole zip Linux

Le nom du pilote, à écrire tel quel dans les chaînes de connexion, est MIRAJ ODBC Driver. Le serveur n'a rien à régler pour lui : un compte MIRAJ ordinaire suffit (chapitre 14).

28.1 Installation#

Windows#

L'assistant d'installation (2.2) copie miraj_odbc.dll à côté de miraj-server.exe et déclare le pilote à Windows, dans la vue 64 bits du registre :

  • la clé HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\MIRAJ ODBC Driver, avec les valeurs Driver et Setup (chemin de la DLL), APILevel = 1, ConnectFunctions = YYY, DriverODBCVer = 03.80, SQLLevel = 1 et FileUsage = 0 ;
  • la valeur MIRAJ ODBC Driver = Installed dans la clé ...\ODBCINST.INI\ODBC Drivers.

Le pilote apparaît alors dans l'onglet Pilotes de l'administrateur de sources de données ODBC 64 bits (odbcad32.exe du dossier System32). Il n'existe pas en 32 bits : une application 32 bits (Access ou Excel 32 bits, ancien Delphi 32) ne le voit pas, et il faut une édition 64 bits de l'application. Les éditions Express et Entreprise déclarent le même nom ; si les deux sont installées, c'est la dernière installée qui l'emporte.

Sans l'assistant (zip) : décompresser le dossier où l'on veut, puis lancer, dans un PowerShell 64 bits ouvert en administrateur :

.\Declarer-ODBC.ps1                              # miraj_odbc.dll à côté du script
.\Declarer-ODBC.ps1 -Dll C:\MIRAJ\miraj_odbc.dll

Le dossier de la DLL ne doit plus être déplacé après la déclaration (le registre en garde le chemin) ; pour le déplacer, relancer le script.

macOS#

Le paquet MIRAJ-<version>-Express-macos-<arch>.pkg (2.2, 21.13) dépose /usr/local/miraj-express/lib/libmiraj_odbc.dylib, et son script de fin d'installation ajoute la section [MIRAJ ODBC Driver] à /Library/ODBC/odbcinst.ini (fichier créé au besoin), ainsi qu'à /usr/local/etc/odbcinst.ini et /opt/homebrew/etc/odbcinst.ini s'ils existent (unixODBC installé par Homebrew). Les autres pilotes de ces fichiers ne sont pas modifiés ; une réinstallation remplace seulement la section de MIRAJ.

[MIRAJ ODBC Driver]
Description=MIRAJ ODBC Driver (protocole MySQL vers miraj-server)
Driver=/usr/local/miraj-express/lib/libmiraj_odbc.dylib
Setup=/usr/local/miraj-express/lib/libmiraj_odbc.dylib

macOS ne fournit pas de Driver Manager : installer unixODBC (brew install unixodbc) ou utiliser celui d'une application (Excel pour Mac embarque iODBC, qui lit le même odbcinst.ini). Vérification :

odbcinst -q -d                  # liste les pilotes : « MIRAJ ODBC Driver » doit y figurer

Linux#

Le zip MIRAJ-<version>-Express-linux-x64.zip contient libmiraj_odbc.so et, dans odbc/, deux scripts. Il faut unixODBC (unixodbc sous Debian et Ubuntu, unixODBC sous Fedora et RHEL). Après décompression, par exemple dans /opt/miraj :

sudo /opt/miraj/odbc/register.sh                 # déclare le pilote dans odbcinst.ini
sudo /opt/miraj/odbc/register.sh --lib /opt/miraj/libmiraj_odbc.so   # chemin explicite

Le script cherche le fichier indiqué par odbcinst -j (ligne DRIVERS, en général /etc/odbcinst.ini), retire une ancienne section [MIRAJ ODBC Driver] puis écrit la nouvelle, en laissant le reste intact. Il est répétable. --ini <fichier> vise un autre fichier (plusieurs fois possible), par exemple un odbcinst.ini d'essai ou celui d'un ODBCSYSINI particulier. La même section peut aussi s'écrire à la main, ou se déclarer par odbcinst -i -d -f modèle.ini avec un fichier contenant la section ci-dessus.

28.2 Chaîne de connexion#

Une chaîne ODBC est une suite de MOT=valeur;MOT=valeur. Les mots sont insensibles à la casse, un mot répété garde sa première valeur, et un mot inconnu est ignoré (les outils en ajoutent). Une valeur qui contient ; s'écrit entre accolades : PWD={a;b}.

DRIVER={MIRAJ ODBC Driver};SERVER=127.0.0.1;PORT=7007;UID=root;PWD=mot de passe;DATABASE=ventes
MotRôleDéfaut
DRIVERnom du pilote ({MIRAJ ODBC Driver}) ; choisit le pilote auprès du Driver Manager
DSNnom d'une source de données (28.3) ; les mots de la chaîne l'emportent sur ceux de la source
SERVER (ou HOST)nom ou adresse du serveur127.0.0.1
PORTport TCP7007
UID (ou USER)compte MIRAJ
PWD (ou PASSWORD)mot de passe ; jamais écrit dans un message d'erreur ni dans la chaîne rendue à l'application
DATABASE (ou DB)base courante à la connexionaucune
SSLMODETLS : disabled, preferred, required, verify-ca, verify-fullpreferred
SSLCAfichier d'autorités de certification (PEM ou DER) pour verify-ca et verify-fullautorités publiques
SSLCERT, SSLKEYcertificat et clé privée du client, ensemble, clé non chiffréeaucun
COMPRESSprotocole compressé (1, yes, true, on)0
PREPONCLIENT1 : les paramètres ? sont substitués dans le texte SQL par le pilote ; 0 : requêtes préparées par le serveur0
CONNECTTIMEOUT, READTIMEOUT, WRITETIMEOUTdélais, en secondesaucun
INITSTMTinstruction exécutée après la connexionaucune
LOGchemin d'un journal du pilote (ou variable d'environnement MIRAJ_ODBC_LOG) ; sans mot de passe ni valeurs, fichier en 0600, limité à 64 Miodésactivé

TLS. disabled n'utilise jamais TLS. preferred chiffre si le serveur le propose et retombe sinon en clair, sans vérifier le certificat : il ne protège pas d'un attaquant actif. required exige TLS (la connexion échoue avant l'envoi du mot de passe si le serveur ne le propose pas) sans vérifier le certificat. verify-ca et verify-full vérifient la chaîne avec SSLCA et que le nom du serveur figure dans le certificat (limite de la bibliothèque cliente : verify-ca ne peut pas ignorer le nom, il est donc aussi strict que verify-full). Sans SSLCA, seules les autorités publiques sont crues : un certificat auto-signé exige SSLCA. Pour un réseau qui n'est pas de confiance, utiliser verify-full avec le certificat de l'autorité du serveur :

DRIVER={MIRAJ ODBC Driver};SERVER=miraj.exemple.fr;UID=app;PWD=...;SSLMODE=verify-full;SSLCA=C:\certs\ca.pem

Un serveur lancé avec --require-tls refuse SSLMODE=disabled (erreur 3159).

PREPONCLIENT. Par défaut, SQLPrepare utilise les requêtes préparées du serveur (protocole binaire : types exacts, BLOB envoyés par morceaux). Mettre PREPONCLIENT=1 si un outil prépare des requêtes que le serveur n'accepte pas sous cette forme : le pilote échappe alors lui-même les valeurs et envoie le texte complet.

COMPRESS. Utile sur un lien lent (résultats volumineux) ; sur le réseau local, le gain est nul et le processeur travaille plus.

28.3 Sources de données (DSN)#

Une source de données (DSN) range les mots de la chaîne de connexion sous un nom ; l'application n'écrit plus que DSN=nom (et, au besoin, UID et PWD).

Windows#

Une source se range dans le registre : HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\<nom> pour une source Système (visible de tous les comptes), HKEY_CURRENT_USER\SOFTWARE\ODBC\ODBC.INI\<nom> pour une source Utilisateur, avec une valeur Driver (chemin de miraj_odbc.dll) et un mot du tableau 26.2 par valeur, et le nom dans la clé ...\ODBC.INI\ODBC Data Sources (valeur MIRAJ ODBC Driver). Exemple pour une source Utilisateur, dans PowerShell :

$k = "HKCU:\SOFTWARE\ODBC\ODBC.INI\MIRAJ ventes"
New-Item $k -Force | Out-Null
Set-ItemProperty $k Driver   "C:\Program Files\Miraj Express\miraj_odbc.dll"
Set-ItemProperty $k SERVER   "127.0.0.1"
Set-ItemProperty $k PORT     "7007"
Set-ItemProperty $k DATABASE "ventes"
New-Item "HKCU:\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources" -Force | Out-Null
Set-ItemProperty "HKCU:\SOFTWARE\ODBC\ODBC.INI\ODBC Data Sources" "MIRAJ ventes" "MIRAJ ODBC Driver"

La source se voit ensuite dans odbcad32.exe (64 bits), onglet DSN utilisateur ou DSN système. Le mot de passe n'est pas à ranger dans la source : l'application le demande et le transmet à la connexion. Le pilote ne fournit pas de fenêtre de saisie propre à MIRAJ dans odbcad32.exe (bouton Configurer) : les sources se créent par le registre comme ci-dessus.

macOS et Linux : odbc.ini#

unixODBC lit les sources dans ~/.odbc.ini (utilisateur) et dans odbc.ini du dossier de configuration (/etc/odbc.ini sous Linux, /Library/ODBC/odbc.ini sous macOS ; odbcinst -j en donne les chemins). Le pilote lit ces fichiers lui-même quand la chaîne contient DSN= :

[MIRAJ ventes]
Driver     = MIRAJ ODBC Driver
Description = Base des ventes
SERVER     = 127.0.0.1
PORT       = 7007
UID        = lecteur
DATABASE   = ventes
SSLMODE    = verify-full
SSLCA      = /etc/ssl/miraj-ca.pem

Vérification, sans écrire de programme (isql est livré avec unixODBC) :

isql -v "MIRAJ ventes" lecteur 'mot de passe'

Un mot de passe écrit dans odbc.ini (PWD = ...) y est en clair : réserver cet usage aux postes de confiance et protéger le fichier (chmod 600 ~/.odbc.ini).

28.4 Exemples#

Python (pyodbc)#

import pyodbc

cn = pyodbc.connect(
    "DRIVER={MIRAJ ODBC Driver};SERVER=127.0.0.1;PORT=7007;"
    "UID=root;PWD=mot de passe;DATABASE=ventes")
cur = cn.cursor()
cur.execute("SELECT id, nom FROM client WHERE ville = ?", "Alger")
for ligne in cur.fetchall():
    print(ligne.id, ligne.nom)
cn.close()

Le script tools/validation/odbc.py (40 vérifications) s'exécute avec ce pilote : python3 tools/validation/odbc.py --port 7007 --password '...' --driver "MIRAJ ODBC Driver".

Excel#

Données → Obtenir des données → À partir d'autres sources → À partir d'ODBC, puis choisir une source de données (DSN) ou Chaîne de connexion et saisir la chaîne (DRIVER={MIRAJ ODBC Driver};SERVER=...), puis les identifiants, la table et Charger. Excel doit être en 64 bits (Fichier → Compte → À propos d'Excel). Sous macOS, Excel passe par iODBC : le pilote doit être dans /Library/ODBC/odbcinst.ini (fait par le paquet), la source dans ~/Library/ODBC/odbc.ini ou /Library/ODBC/odbc.ini.

Power BI Desktop#

Obtenir les données → ODBC, choisir le DSN ou coller la chaîne de connexion dans Options avancées, puis les identifiants (Base de données). Le mode Import est celui qui convient (le pilote n'a pas de mode DirectQuery propre). Une passerelle de données locale (actualisation dans le service en ligne) doit avoir le pilote installé sur la machine de la passerelle, et la source en DSN système.

Access (tables liées)#

Access 64 bits seulement. Données externes → Source de données ODBC → Lier à la source de données, onglet Source de données machine (DSN système ou utilisateur), choisir les tables. Pour une table sans clé primaire déclarée, Access demande les colonnes qui identifient une ligne : les choisir pour pouvoir modifier la table liée.

LibreOffice Base#

Fichier → Nouveau → Base de données → Se connecter à une base de données existante → ODBC, saisir le nom du DSN (LibreOffice s'appuie sur unixODBC sous Linux et macOS, sur le Driver Manager sous Windows) ; le nom d'utilisateur se demande à l'étape suivante.

FireDAC, DBeaver, autres#

FireDAC : DriverID=ODBC, ODBCDriver=MIRAJ ODBC Driver (ou DataSource=<DSN>). DBeaver (pilote générique ODBC) et tout outil qui accepte un DSN ou une chaîne ODBC fonctionnent de même.

28.5 Limites#

  • Pas de 32 bits : le pilote est livré en 64 bits seulement (Windows x64, macOS Apple silicon, Linux 64 bits). Les applications 32 bits ne le voient pas (28.1).
  • Curseur en avant seul : pas de défilement ni de curseur modifiable. SQLFetchScroll n'accepte que SQL_FETCH_NEXT. Un autre type de curseur demandé par l'application est remplacé par le curseur en avant, avec l'avertissement 01S02 (option modifiée).
  • Niveaux : fonctions ODBC Core et niveau 1 ; pas de niveau 2 (pas de SQLSetPos, de SQLBulkOperations, de SQLBrowseConnect). Les mises à jour se font en SQL (INSERT, UPDATE, DELETE).
  • Un seul flux réseau par connexion : une seconde instruction exécutée alors qu'un SELECT est à moitié lu fait tamponner en mémoire le reste du premier résultat ; les curseurs entrelacés et le COMMIT avec curseur ouvert fonctionnent, mais un très gros résultat laissé à moitié lu occupe de la mémoire.
  • Non pris en charge : paramètres de sortie (SQL_PARAM_OUTPUT, {? = call}), données envoyées au vol avec PARAMSET_SIZE > 1, signets, descripteurs d'application explicites liés à une instruction.
  • Heures : une valeur TIME négative ou supérieure à 24 h lue en SQL_C_TYPE_TIME est rendue sans signe ; la lire en SQL_C_CHAR donne la valeur exacte.
  • Annulation : les fonctions de catalogue (SQLTables, SQLColumns…) ne sont pas annulables.
  • Catalogue : le schéma ODBC est toujours vide ; les index du serveur sont tous de type hachage ; les colonnes AUTO_INCREMENT ne sont pas signalées par SQLColumns.
  • Authentification : mysql_native_password et caching_sha2_password ; pas client_ed25519.
  • TLS : pas de clé privée du client protégée par mot de passe .
  • Fenêtre de configuration : pas de boîte de dialogue MIRAJ dans odbcad32.exe (28.3).
  • Dépendances : l'annulation d'une requête (SQLCancel) ouvre une seconde connexion et envoie KILL QUERY : le compte doit avoir le droit de tuer ses propres requêtes.
  • Transactions : AUTOCOMMIT et les niveaux d'isolation sont ceux de MIRAJ (chapitre 13).

28.6 Désinstallation#

Windows#

Désinstaller MIRAJ depuis Paramètres → Applications (2.2) : l'assistant retire miraj_odbc.dll et la déclaration du pilote (la clé MIRAJ ODBC Driver et la valeur de ODBC Drivers). Les sources de données créées par l'utilisateur restent dans le registre (elles ne fonctionnent plus) ; les supprimer dans odbcad32.exe. Après une installation par zip, retirer la déclaration avant de supprimer le dossier :

.\Retirer-ODBC.ps1

macOS#

La désinstallation d'un .pkg n'est pas gérée par macOS : retirer le pilote à la main, dans un terminal.

sudo /usr/local/miraj-express/bin/miraj-odbc-unregister.sh    # retire la section des odbcinst.ini
sudo rm /usr/local/miraj-express/lib/libmiraj_odbc.dylib

Le script ne touche qu'à la section [MIRAJ ODBC Driver] ; les autres pilotes et les sources de données (odbc.ini) restent. Le reste de MIRAJ se désinstalle comme décrit en 21.13.

Linux#

sudo /opt/miraj/odbc/unregister.sh               # retire la section de odbcinst.ini

puis supprimer le dossier décompressé.