Pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sur Linux

ODBC (Open Database Connectivity) est une norme largement adoptée qui permet aux applications clientes de se connecter et d’utiliser des données à partir de bases de données et de plateformes Big Data.

Le pilote Microsoft ODBC pour l’ingénierie des données Fabric vous permet de connecter, interroger et gérer des charges de travail Spark dans Fabric avec la fiabilité et la simplicité de la norme ODBC. Basé sur les API Livy de Fabric, le pilote offre une connectivité SQL Spark sécurisée et flexible à vos applications compatibles C/C++, .NET, Python et autres compatibles ODBC sous Linux.

Fonctionnalités clés

• Conforme à ODBC 3.x : Implémentation complète de la spécification ODBC 3.x.
• Authentification Microsoft Entra ID : Flux d’authentification multiples, incluant Azure CLI, identifiants clients, certificats et authentification par jeton d’accès.
• Prise en charge des requêtes SQL Spark : exécution directe des instructions SQL de Spark.
• Prise en charge complète des types de données : prise en charge de tous les types de données SQL Spark, y compris les types complexes (ARRAY, MAP, et STRUCT).
• Réutilisation des sessions : gestion de session intégrée pour améliorer les performances.
• Mode haute concurrence : Optez pour des sessions Livy partagées et chaudes côté serveur pour réduire la latence de démarrage de la connexion et l’étalement du cluster Spark.
• Prise en charge des grandes tables : Gestion optimisée pour de grands ensembles de résultats avec des tailles de pages configurables.
• Prélecture asynchrone : Chargement des données en arrière-plan pour améliorer les performances.
• Prise en charge des proxy : configuration HTTP des proxy pour les environnements d’entreprise.
• Prise en charge des maisons lacustres multi-schémas : Connectez-vous à un schéma spécifique au sein d’une maison lacustre.

Prerequisites

Avant d’utiliser le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sous Linux, assurez-vous de respecter les prérequis suivants :

• Système d’exploitation : Ubuntu 22.04 ou ultérieur, Debian 11 ou ultérieur, ou Red Hat Enterprise Linux (RHEL) 8 ou ultérieur en x86-64.
• unixODBC : Le gestionnaire de pilotes ODBC pour Linux. Installez les unixodbc packages et unixodbc-dev .
• libcurl : La dépendance HTTP à l’exécution, telle que libcurl4 ou le package équivalent pour votre distribution.
• OpenSSL : La dépendance d’exécution pour TLS et la cryptographie, comme openssl et libssl3 ou des paquets équivalents.
• Accès à Fabric : Accès à un espace de travail Fabric.
• Identifiants Microsoft Entra ID : Identifiants appropriés pour l’authentification.
• Identifiants de l’espace de travail et du lakehouse : Les identifiants GUID de votre espace de travail Fabric et de votre lakehouse.
• Azure CLI (optionnel) : Obligatoire lorsque vous utilisez l’authentification Azure CLI.

Téléchargez et installez sur Linux

• Téléchargez le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering sur Linux (tar)

Pour installer le pilote :

1. Extrayez ms-sparksql-odbc-linux-2.0.0.tar.

2. Ouvrez un terminal dans le répertoire extrait.

3. Installez le package Debian :

   sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb
   

Le paquet installe les fichiers suivants :

Installer un package RPM

Sur RHEL, Fedora ou CentOS, installez le package RPM à partir de l’archive des pilotes extraits :

sudo dnf install ./microsoft-fabric-odbc-driver-*.x86_64.rpm

Sinon, utilisez rpm:

sudo rpm -i microsoft-fabric-odbc-driver-*.x86_64.rpm

Vérifiez que le RPM a bien enregistré le pilote :

odbcinst -q -d | grep "Microsoft"

Pour désinstaller le package RPM, exécutez :

sudo dnf remove microsoft-fabric-odbc-driver

Installer une archive tar

Pour les distributions sans support Debian ou RPM package, ou pour un emplacement d’installation personnalisé, extraire le .tar.gz package et exécuter son script d’installation :

tar -xzf microsoft-fabric-odbc-driver-2.0.0-linux-x86_64.tar.gz
cd microsoft-fabric-odbc-driver-2.0.0

# Install to /opt/microsoft/fabricodbc.
sudo ./install.sh

# Or install to a custom writable location.
./install.sh --prefix=$HOME/fabricodbc

Le script d’installation prend en charge ces options :

Pour vérifier l’installation par défaut du tarball, exécutez :

odbcinst -q -d
ls -la /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so

Pour le désinstaller, exécutez sudo ./install.sh --uninstall depuis le répertoire du package extrait.

Enregistrer le pilote manuellement

Le package enregistre automatiquement le pilote auprès de unixODBC. Pour enregistrer manuellement le pilote, exécutez :

sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template

Vérifier l’installation

Vérifiez que le pilote est enregistré et que la bibliothèque est installée :

odbcinst -q -d
ls -la /usr/lib/libmicrosoftfabricodbc.so

La odbcinst commande devrait indiquer [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Désinstaller le pilote

Pour désinstaller le pilote, exécutez la commande suivante :

sudo dpkg -r microsoft-fabric-odbc-driver

Cette commande supprime les fichiers du pilote et désinscrit le pilote d’unixODBC.

Exemple de démarrage rapide

Les exemples suivants se connectent à Fabric et exécutent une requête SQL Spark. Remplissez les prérequis et installez le pilote avant d’exécuter un exemple.

exemple de Python

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
)

conn = pyodbc.connect(connection_string, timeout=30)
cursor = conn.cursor()

cursor.execute("SELECT 'Hello from Fabric!' AS message")
row = cursor.fetchone()
print(row.message)

conn.close()

Exemple C/C++

#include <sql.h>
#include <sqlext.h>
#include <iostream>

int main() {
    SQLHENV henv = SQL_NULL_HENV;
    SQLHDBC hdbc = SQL_NULL_HDBC;
    SQLHSTMT hstmt = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
    SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);

    const char* connectionString =
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;";

    SQLRETURN result = SQLDriverConnect(
        hdbc,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        std::cout << "Connected successfully!" << std::endl;

        SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
        result = SQLExecDirect(
            hstmt,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

        if (SQL_SUCCEEDED(result)) {
            char message[256];
            SQLLEN indicator;

            while (SQLFetch(hstmt) == SQL_SUCCESS) {
                SQLGetData(
                    hstmt,
                    1,
                    SQL_C_CHAR,
                    message,
                    sizeof(message),
                    &indicator);
                std::cout << message << std::endl;
            }
        }

        SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
        SQLDisconnect(hdbc);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    SQLFreeHandle(SQL_HANDLE_ENV, henv);
    return 0;
}

Construis et exécute l’exemple :

g++ -o fabric_test fabric_test.cpp -lodbc -std=c++17
./fabric_test

exemple de .NET

using System.Data.Odbc;

string connectionString =
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
    "WorkspaceId=<workspace-id>;" +
    "LakehouseId=<lakehouse-id>;" +
    "AuthFlow=AZURE_CLI;";

using var connection = new OdbcConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

using var command = new OdbcCommand(
    "SELECT 'Hello from Fabric!' AS message",
    connection);
using var reader = await command.ExecuteReaderAsync();

if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

Format de chaîne de connexion

Chaîne de connexion de base

Utilisez le format de chaîne de connexion suivant :

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};<parameter1>=<value1>;<parameter2>=<value2>;...

Composants de chaîne de connexion

Exemples de chaîne de connexion

Connexion de base

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI

Connexion avec les options de performance

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;ReuseSession=true;LargeTableSupport=true;PageSizeBytes=18874368

Lien avec la journalisation

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LogLevel=DEBUG;LogFile=/tmp/odbc_driver.log

Connexion avec le mode de haute concurrence

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

Pour des conseils complets de configuration, voir mode de haute concurrence (HC).

Authentication

Le pilote Microsoft ODBC pour Microsoft Fabric Data Engineering prend en charge plusieurs méthodes d’authentification via Microsoft Entra ID. Configurez l’authentification en utilisant le AuthFlow paramètre dans la chaîne de connexion ou le DSN.

Méthodes d’authentification

L'authentification de l'Azure CLI

Utilisez l’authentification Azure CLI pour le développement et les applications interactives.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

Avant de vous connecter, vérifiez que Azure CLI est installé et connectez-vous :

az --version
az login

Pour installer Azure CLI sur Debian ou Ubuntu, utilisez le gestionnaire de paquets :

sudo apt-get update
sudo apt-get install -y azure-cli

Authentification des identifiants clients

Utilisez l’authentification des identifiants clients pour les services automatisés et les tâches en arrière-plan.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CREDENTIAL;"
    f"TenantId={tenant_id};"
    f"ClientId={client_id};"
    f"ClientSecret={client_secret};"
)

Veuillez fournir les paramètres suivants :

• TenantId : Identifiant du locataire Microsoft Entra.
• ClientId: ID d’application (client).
• ClientSecret: Le secret du client.

Stockez les secrets dans un stockage secret sécurisé ou dans des variables d’environnement. Ne stockez pas de secrets dans des chaînes de connexion en texte clair ou dans des fichiers INI.

Authentification basée sur un certificat

Utilisez l’authentification basée sur des certificats pour les applications d’entreprise nécessitant des identifiants de certificat.

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CERTIFICATE;"
    "TenantId=<tenant-id>;"
    "ClientId=<client-id>;"
    "CertificatePath=/path/to/cert.pfx;"
    "CertificatePassword=<password>;"
)

Veuillez fournir les paramètres suivants :

• TenantId: Identifiant du locataire Microsoft Entra.
• ClientId: ID d’application (client).
• CertificatePath: Le chemin vers le fichier de certificat PFX ou PKCS12.
• CertificatePassword: Le mot de passe du certificat.

Authentification par jeton d’accès

Utilisez l’authentification du jeton d’accès lorsque votre application acquiert un jeton via un autre mécanisme.

access_token = acquire_token_from_custom_source()

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=ACCESS_TOKEN;"
    f"AccessToken={access_token};"
)

Authentification par jeton de fichier

Utilisez l’authentification par jeton de fichier dans les environnements conteneurisés et les pipelines automatisés où un autre processus écrit un jeton porteur dans le fichier de jeton bien connu du pilote :

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=FILE_TOKEN;"
)

Pour les alias de propriété cross-driver supportés, voir Aliases de propriété cross-driver.

Paramètres de configuration

Paramètres requis

Incluez ces paramètres dans chaque chaîne de connexion :

Paramètres facultatifs

Paramètres de connexion

Paramètres de performances

Paramètres de journalisation

Paramètres du proxy

Paramètres de concurrence élevée (HC)

Utilisez ces paramètres pour activer et configurer le mode haute concurrence (HC). Le mode HC doit être activé manuellement. Si vous ne spécifiez ni LivyMode ni UseHighConcurrency, le pilote utilise le mode classique à session unique. Pour des conseils et des exemples, voir Mode de haute concurrence (HC).

Priorité des modes et validation

• LivyMode a priorité sur UseHighConcurrency lorsque vous définissez les deux paramètres.
• Les valeurs des paramètres ne sont pas sensibles à la casse.
• UseHighConcurrency accepte true, 1, yes, ou on pour activer le mode HC. Il accepte false, 0, no ou off pour désactiver le mode HC.
• Pour d’autres valeurs non vides, SQLDriverConnect renvoie une erreur. En mode DSN uniquement, SQLConnect consigne l’échec de la validation et utilise le chemin classique.

Paramètres de compatibilité

Le pilote accepte TenantPrincipal et PoolMax, ainsi que leurs variables d’environnement de remplacement, afin d’assurer la compatibilité avec les anciennes configurations HC. Le pilote analyse et valide ces valeurs, mais elles n’affectent pas la correspondance des sessions HC ni la capacité du pool d’exécution. Ne comptez pas sur eux pour l’isolement des locataires ou les limites de connexion.

Mécanismes de repli pour les variables d’environnement

Le pilote utilise les variables d’environnement suivantes uniquement lorsque le DSN ou le paramètre de chaîne de connexion correspondant n’est pas défini :

Pour FABRIC_ODBC_USE_HC, l’activation via l’environnement uniquement accepte true, 1 ou yes (sans distinction entre majuscules et minuscules). D’autres valeurs laissent le mode HC désactivé. Les on alias et off ne s’appliquent qu’aux valeurs DSN et de la chaîne de connexion.

Mode haute concurrence (HC)

Le mode haute concurrence (HC) permet aux connexions ODBC au même espace de travail et au même lakehouse d’être rattachées à des sessions Livy Spark partagées et préchauffées côté serveur, au lieu de provisionner un cluster distinct pour chaque connexion. Utilisez-le pour des charges de travail telles que les tableaux de bord BI, les noyaux de notebooks et les extensions ETL qui ouvrent de nombreuses connexions de courte durée et peuvent partager la capacité Spark gérée par le serveur.

Le mode HC est sur inscription. Si vous ne configurez pas de réglage HC, le pilote utilise le chemin classique d’une seule session.

Choisir un mode de connexion

Utilisez le mode HC lorsque :

• Votre charge de travail ouvre de nombreuses connexions ODBC de courte durée, comme les tableaux de bord BI, les noyaux de notebooks ou l’expansion ETL.
• Les connexions ciblent le même espace de travail et le même lakehouse et peuvent partager une session Spark gérée par le serveur.
• Réduire la latence de démarrage à froid par connexion est important.

Utilisez le mode classique lorsque :

• Chaque connexion nécessite une session Spark isolée en raison de configurations Spark différentes ou d’une isolation stricte des ressources.
• Le point de terminaison Livy de Fabric pour l’espace de travail cible et le lakehouse ne prend pas en charge le mode HC.

Activer le mode de haute concurrence

Ajoutez un paramètre de mode haute concurrence au DSN ou à la chaîne de connexion.

Recommandé : Définir LivyMode

Utilisez LivyMode pour sélectionner explicitement le mode acquisition de session :

LivyMode=HighConcurrency

Les valeurs prises en charge sont Classic, HighConcurrencyet Auto. Les valeurs ne sont pas sensibles à la majuscule. Auto Il sélectionne actuellement le mode classique.

Alternative : Définir UseHighConcurrency

Utilisez le paramètre booléen pour la compatibilité avec les configurations existantes :

UseHighConcurrency=true

Pour désactiver le mode de haute concurrence, utilisez true, 1, yes, ou on. Pour le désactiver, utilisez false, 0, no, ou off. Les valeurs ne sont pas sensibles à la majuscule. SQLDriverConnect rejette les autres valeurs non vides avec SQLSTATE HY024. Le DSN uniquement SQLConnect enregistre l’échec de validation et utilise le mode classique.

Vous pouvez également activer le mode de haute concurrence pour la coque actuelle en utilisant des variables d’environnement :

export FABRIC_ODBC_USE_HC=true
export FABRIC_ODBC_WORKSPACE_ID=<workspace-id>
export FABRIC_ODBC_LAKEHOUSE_ID=<lakehouse-id>
export FABRIC_ODBC_SESSION_TAG=bi-dashboard

Paramètres requis en mode HC

L’activation HC nécessite les identifiants valides suivants :

Incluez-le SessionTag car cela influence l’appariement côté serveur pour les sessions chaudes.

Correspondance de session

Le mode HC ne garantit pas que chaque connexion réutilise une session existante. Pour chaque demande d’acquisition de session, le pilote envoie :

• La valeur SessionTag.
• La configuration effective de Spark, y compris les paramètres conf.* et EnvironmentId.

Le service Fabric Livy évalue ces valeurs et décide s’il faut associer la connexion à une session chaude ou en créer une nouvelle. Pour améliorer la réutilisation des sessions, utilisez des valeurs cohérentes entre les connexions destinées à partager la capacité Spark gérée par le serveur.

Exemples de chaîne de connexion

Configuration minimale d’une connexion HC avec authentification Azure CLI :

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

Connexion HC avec temps d’arrêt réglés :

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=etl-prod;AcquireTimeoutSeconds=180;HeartbeatTimeoutInSecond=600

Connexion HC avec un environnement et configurations Spark :

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;EnvironmentId=<environment-id>;SessionTag=ml-team;conf.spark.sql.shuffle.partitions=200;conf.spark.executor.memory=8g

Python avec pyodbc:

import pyodbc

conn = pyodbc.connect(
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LivyMode=HighConcurrency;"
    "SessionTag=notebook-kernel"
)

Configurez le mode HC dans un DSN Linux

Au lieu de répéter les paramètres HC dans chaque chaîne de connexion, stockez-les ~/.odbc.ini pour un DSN spécifique à l’utilisateur ou /etc/odbc.ini pour un DSN à l’échelle du système.

[FabricHCDSN]
Description               = Microsoft Fabric Data Engineering with HC mode
Driver                    = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId               = <workspace-id>
LakehouseId               = <lakehouse-id>
AuthFlow                  = AZURE_CLI
LivyMode                  = HighConcurrency
SessionTag                = bi-dashboard
AcquireTimeoutSeconds     = 300
HeartbeatTimeoutInSecond  = 600

Après avoir enregistré le DSN, vérifiez-le et testez la connexion.

odbcinst -q -s
isql -k -v "DSN=FabricHCDSN;"

Lorsqu'une chaîne de connexion ne spécifie pas de valeur, le pilote lit ces paramètres depuis le DSN :

• LivyMode
• UseHighConcurrency
• EnvironmentId
• SessionTag
• IdempotencyKey
• HeartbeatTimeoutInSecond
• AcquireTimeoutSeconds

Le pilote lit également les paramètres réservés à la compatibilité TenantPrincipal et PoolMax. Utilisez les noms des paramètres dans la table des paramètres HC.

Désactiver le mode HC

Vous pouvez désactiver la création de nouvelles sessions HC sans redéployer le pilote. Utilisez la méthode qui correspond à la façon dont vous avez activé le mode HC :

Les paramètres de la chaîne de connexion et du DSN prévalent sur la solution de repli via les variables d’environnement. Ces changements n’affectent que les nouvelles connexions. Les sessions HC existantes continuent jusqu’à leur sortie.

Comprendre le comportement du runtime HC

• Validation :SQLDriverConnect rejette les valeurs HC booléennes invalides et les valeurs entières positives avec SQLSTATE HY024. Il rejette une valeur LivyMode non valide ainsi que des valeurs WorkspaceId, LakehouseId et IdempotencyKey non valides ou trop grandes, avec le code SQLSTATE HY000. Une valeur de compatibilité TenantPrincipal surdimensionnée renvoie HY000également . Pour le DSN uniquement SQLConnect, le pilote enregistre les échecs de validation HC ordinaires et utilise le mode classique. Les valeurs sensibles à la sécurité surdimensionnées échouent toujours à la connexion.
• Données sensibles : Le pilote exclut ou efface IdempotencyKey d’autres champs sensibles des journaux HC et des résultats de diagnostic.
• Annulation : L’annulation de relevé est coopérative. Les tâches du serveur déjà en cours d’exécution se terminent proprement au lieu d’être interrompues immédiatement.
• Disjoncteurs : Les modes HC et classique utilisent des disjoncteurs séparés. Épuiser un mode n’affecte pas l’autre.
• Base de données initiale : Les connexions HC n’exécutent pas l’instruction initiale USE pour le Database paramètre. Exécutez USE <database> après avoir connecté ou utilisez des noms de table entièrement qualifiés.
• Diagnostic : Régler LogLevel=DEBUG pour enregistrer les décisions d’acquisition, de sondage, de publication et de cartographie d’erreurs HC. Pour un dépannage ciblé, définissez LIVY_HC_VERBOSE=1 pour inclure des diagnostics HTTP HC supplémentaires expurgés.

Configuration DSN

Sous Linux, configurez les noms des sources de données (DSN) dans les fichiers INI au lieu du registre Windows.

Créer un DSN

Si ~/.odbc.ini elle existe, ajoutez la nouvelle section DSN sans remplacer le fichier existant. Copiez le modèle installé uniquement lors de la création du fichier :

if [ -e "$HOME/.odbc.ini" ]; then
    echo "Preserve ~/.odbc.ini and add the new DSN section manually."
else
    cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template "$HOME/.odbc.ini"
fi

Modifiez ~/.odbc.ini avec les informations de votre espace de travail Fabric :

[FabricDSN]
Description    = Microsoft Fabric Data Engineering
Driver         = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId    = <workspace-id>
LakehouseId    = <lakehouse-id>
AuthFlow       = AZURE_CLI
LogLevel       = INFO
# LogFile      = /tmp/fabric_odbc.log
# LargeTableSupport = true
# ReuseSession = true

Vérifier le DSN

Listez les DSN configurés, puis testez la connexion :

odbcinst -q -s
isql -k -v "DSN=FabricDSN;"

La isql commande nécessite les outils de ligne de commande unixODBC. L’option -k utilise SQLDriverConnect, qui permet au pilote de traiter les attributs de connexion DSN.

Utiliser un DSN dans les applications

conn = pyodbc.connect("DSN=FabricDSN")

using var connection = new OdbcConnection("DSN=FabricDSN");
await connection.OpenAsync();

SQLRETURN result = SQLConnect(
    hdbc,
    (SQLCHAR*)"FabricDSN",
    SQL_NTS,
    NULL,
    0,
    NULL,
    0);

Exemples d’utilisation

Tester une connexion avec isql

Commencez une session SQL interactive :

isql -k -v "DSN=FabricDSN;"

Lancer une seule requête :

echo "SELECT 1 AS test" | isql -k -v "DSN=FabricDSN;" -b

Utilisez -k pour Fabric DSN afin isql de se connecter via SQLDriverConnect au lieu de SQLConnect.

Travail avec de grands ensembles de résultats

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LargeTableSupport=true;"
    "PageSizeBytes=18874368;"
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()
cursor.execute("SELECT * FROM large_table")

row_count = 0
while True:
    rows = cursor.fetchmany(1000)
    if not rows:
        break

    for row in rows:
        row_count += 1

    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

print(f"Total rows processed: {row_count}")
conn.close()

Découvrez les schémas et les tables

import pyodbc

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SHOW TABLES")
for table in cursor.fetchall():
    print(table)

cursor.execute("DESCRIBE employees")
for column in cursor.fetchall():
    print(column)

cursor.execute("SHOW SCHEMAS")
for schema in cursor.fetchall():
    print(schema)

conn.close()

Mappage de types de données

Le pilote mappe les types de données Spark SQL aux types SQL ODBC :

Différences de plateforme

Troubleshooting

Conducteur non trouvé

Problème : La connexion échoue avec [IM002] Data source name not found and no default driver specified.

Solutions :

1. Vérifiez l’enregistrement des pilotes en exécutant odbcinst -q -d.
2. Vérifiez que /usr/lib/libmicrosoftfabricodbc.so existe.
3. Enregistrez le conducteur en exécutant sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Réinstallez le package en exécutant sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Pilote non retrouvé après l’installation d’une balle de bitume

Problème : Le pilote est enregistré, mais la bibliothèque partagée n’est pas présente au chemin d’accès enregistré.

Solutions :

1. Vérifiez que /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so existe.
2. Réexécuter sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Si vous avez utilisé un préfixe personnalisé, vérifiez que le chemin du pilote enregistré utilise le même préfixe.

DSN introuvable

Problème : La connexion échoue avec [IM002] Data source name not found.

Solutions :

1. Vérifiez la configuration DSN en exécutant odbcinst -q -s.
2. Vérifiez que ~/.odbc.ini ou /etc/odbc.ini contient la section DSN.
3. Assurez-vous que la Driver valeur correspond exactement au nom du conducteur enregistré.

Échecs de connexion

Problème : Le pilote ne peut pas se connecter à Fabric.

Solutions :

1. Vérifiez que l’identifiant de l’espace de travail et l’identifiant du lakehouse sont des GUID valides.
2. Vérifiez l’authentification Azure CLI en exécutant az account show.
3. Assurez-vous d’avoir les autorisations requises pour l’espace de travail Fabric.
4. Vérifiez la connectivité réseau et les paramètres proxy.

Erreurs d’authentification

Problème : l’authentification Azure CLI échoue.

Solutions :

1. Exécutez az login pour actualiser vos identifiants.
2. Réglez l’abonnement correct en exécutant az account set --subscription <subscription-id>.
3. Vérifie le jeton en exécutant az account get-access-token --resource https://api.fabric.microsoft.com.
4. Assurez-vous que votre compte dispose des autorisations requises pour l’espace de travail Fabric.

Erreurs de bibliothèque partagée

Problème : Le conducteur signale error while loading shared libraries: libmicrosoftfabricodbc.so.

Solutions :

1. Réinstallez le package en exécutant sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Vérifiez que /usr/lib/libmicrosoftfabricodbc.so existe.
3. Exécutez sudo ldconfig pour rafraîchir le cache de la bibliothèque partagée.

Délais d’expiration des requêtes

Problème : Les requêtes s’épuisent sur de grandes tables.

Solutions :

1. Ajouter LargeTableSupport=true à la chaîne de connexion.
2. Ajustez PageSizeBytes la taille du résultat.
3. Ajouter EnableAsyncPrefetch=1 à la chaîne de connexion.
4. Utilisez une LIMIT clause pour limiter la taille du résultat.

Activer la journalisation

Activez la journalisation détaillée dans un DSN :

[FabricDSN]
LogLevel = DEBUG
LogFile  = /tmp/fabric_odbc_debug.log

Sinon, ajoutez des paramètres de journalisation à la chaîne de connexion :

LogLevel=DEBUG;LogFile=/tmp/fabric_odbc_debug.log;

Le pilote prend en compte les niveaux logaritaires suivants :

• DEBUG: Inclut des informations détaillées sur le débogage et constitue le niveau de journal de pilotes le plus verbeux.
• INFO: Inclut des informations générales et est la norme par défaut.
• WARN: Inclut uniquement les avertissements.
• ERROR: Inclut uniquement les erreurs.

Activer le traçage unixODBC

Pour les diagnostics d’appels ODBC de bas niveau, ajoutez la configuration suivante à /etc/odbcinst.ini:

[ODBC]
Trace     = yes
TraceFile = /tmp/odbc_trace.log

Désactivez le traçage une fois le dépannage terminé pour éviter une surcharge de performance inutile.

Contenu connexe

• Microsoft ODBC Driver for Microsoft Fabric Data Engineering
• Runtimes Apache Spark dans Fabric
• Fabric Runtime 1.3
• Présentation de l’API Livy pour l’ingénierie des données
• Microsoft JDBC Driver for Microsoft Fabric Data Engineering
• unixODBC