Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering unter Linux

ODBC (Open Database Connectivity) ist ein weit verbreiteter Standard, mit dem Clientanwendungen eine Verbindung mit Daten aus Datenbanken und Big Data-Plattformen herstellen und damit arbeiten können.

Der Microsoft ODBC Driver for Fabric Data Engineering ermöglicht es Ihnen, Spark-Workloads in Fabric mit der Zuverlässigkeit und Einfachheit des ODBC-Standards zu verbinden, abzufragen und zu verwalten. Der Treiber basiert auf den Livy-APIs von Fabric und bietet sichere und flexible Spark-SQL-Konnektivität zu Ihren C/C++-, .NET-, Python- und anderen ODBC-kompatiblen Anwendungen unter Linux.

Wichtigste Funktionen

• ODBC 3.x-konform: Vollständige Implementierung der ODBC 3.x-Spezifikation.
• Microsoft Entra ID-Authentifizierung: Mehrere Authentifizierungsflüsse, einschließlich Azure CLI, Client-Zugangsdaten, zertifikatsbasierter und Zugriffstoken-Authentifizierung.
• Spark SQL-Abfrageunterstützung: Direkte Ausführung von Spark SQL-Anweisungen.
• Umfassende Unterstützung für Datentypen: Unterstützung für alle Spark SQL-Datentypen, einschließlich komplexer Typen (ARRAY, MAP, und STRUCT).
• Wiederverwendung von Sitzungen: Integriertes Sitzungsmanagement für bessere Leistung.
• Modus für hohe Parallelität: Aktivieren Sie gemeinsame, vorgewärmte serverseitige Livy-Sitzungen, um die Latenz beim Verbindungsaufbau und die unnötige Vermehrung von Spark-Clustern zu reduzieren.
• Unterstützung für große Tabellen: Optimierte Behandlung für große Ergebnissätze mit konfigurierbaren Seitengrößen.
• Async prefetch: Laden von Daten im Hintergrund zur Verbesserung der Leistung.
• Proxy-Unterstützung: HTTP-Proxy-Konfiguration für Unternehmensumgebungen.
• Unterstützung für Lakehouses mit mehreren Schemas: Stellen Sie eine Verbindung mit einem bestimmten Schema innerhalb eines Lakehouses her.

Voraussetzungen

Bevor Sie den Microsoft ODBC Driver für Microsoft Fabric Data Engineering unter Linux verwenden, stellen Sie sicher, dass Sie die folgenden Voraussetzungen erfüllen:

• Betriebssystem: Ubuntu 22.04 oder neuer, Debian 11 oder neuer, oder Red Hat Enterprise Linux (RHEL) 8 oder später auf x86-64.
• unixODBC: Der ODBC-Treibermanager für Linux. Installieren Sie die Pakete unixodbc und unixodbc-dev.
• libcurl: Die HTTP-Laufzeitabhängigkeit, wie zum Beispiel libcurl4 oder das entsprechende Paket für Ihre Distribution.
• OpenSSL: Die Laufzeitabhängigkeit für TLS und Kryptografie, wie openssl und libssl3 oder entsprechende Pakete.
• Fabric Access: Zugang zu einem Fabric-Arbeitsbereich.
• Microsoft Entra ID-Zugangsdaten: Geeignete Zugangsdaten für die Authentifizierung.
• Arbeitsplatz- und Seehaus-IDs: Die GUID-Kennungen für Ihren Fabric-Arbeitsplatz und Ihr Seehaus.
• Azure CLI (optional): Erforderlich, wenn Sie Azure CLI-Authentifizierung verwenden.

Herunterladen und installieren auf Linux

• Laden Sie den Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering auf Linux (tar) herunter

Den Treiber installieren:

1. Extrahieren Sie ms-sparksql-odbc-linux-2.0.0.tar.

2. Öffnen Sie ein Terminal im extrahierten Verzeichnis.

3. Installieren Sie das Debian-Paket:

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

Das Paket installiert die folgenden Dateien:

Installieren Sie ein RPM-Paket

Auf RHEL, Fedora oder CentOS installieren Sie das RPM-Paket aus dem extrahierten Treiberarchiv:

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

Alternativ verwenden Sie rpm:

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

Überprüfen Sie, ob das RPM den Treiber registriert hat:

odbcinst -q -d | grep "Microsoft"

Um das RPM-Paket zu deinstallieren, führen Sie aus:

sudo dnf remove microsoft-fabric-odbc-driver

Einen Tarball installieren

Für Distributionen ohne Debian- oder RPM-Paketunterstützung oder für einen benutzerdefinierten Installationsstandort entpacken Sie das .tar.gz Paket und führen das Installationsskript aus:

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

Das Installationsskript unterstützt folgende Optionen:

Um die Standardinstallation per Tarball zu überprüfen, führen Sie Folgendes aus:

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

Um es zu deinstallieren, führen Sie sudo ./install.sh --uninstall im Verzeichnis des extrahierten Pakets aus.

Treiber manuell registrieren

Das Paket registriert den Treiber automatisch bei unixODBC. Um den Treiber manuell zu registrieren, führen Sie aus:

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

Überprüfen der Installation

Überprüfen Sie, ob der Treiber registriert ist und die Bibliothek installiert ist:

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

Der Befehl odbcinst sollte [Microsoft ODBC Driver for Microsoft Fabric Data Engineering] auflisten.

Deinstalliere den Treiber

Um den Treiber zu deinstallieren, führen Sie folgenden Befehl aus:

sudo dpkg -r microsoft-fabric-odbc-driver

Dieser Befehl entfernt die Treiberdateien und deregistriert den Treiber aus unixODBC.

Schnellstartbeispiel

Die folgenden Beispiele verbinden sich mit Fabric und führen eine Spark-SQL-Abfrage aus. Erfülle die Voraussetzungen und installiere den Treiber, bevor du ein Beispiel ausführst.

Python-Beispiel

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()

C/C++ Beispiel

#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;
}

Baue und führe das Beispiel aus:

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

.NET-Beispiel

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 der Verbindungszeichenfolge

Grundlegende Verbindungszeichenfolge

Verwenden Sie das folgende Verbindungszeichenfolge-Format:

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

Komponenten der Verbindungszeichenfolge

Exemplarische Verbindungszeichenfolgen

Grundverbindung

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

Verbindung mit Leistungsoptionen

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

Verbindung zum Holzeinschlag

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

Verbindung mit Hochkonkurrenzmodus

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

Eine vollständige Anleitung zur Konfiguration finden Sie unter Modus für hohe Parallelität (HC).

Authentication

Der Microsoft ODBC Driver for Microsoft Fabric Data Engineering unterstützt mehrere Authentifizierungsmethoden über Microsoft Entra ID. Konfigurieren Sie die Authentifizierung durch Verwendung des Parameters AuthFlow im Verbindungszeichenfolge oder DSN.

Authentifizierungsmethoden

Azure CLI-Authentifizierung

Verwenden Sie Azure CLI-Authentifizierung für Entwicklungs- und interaktive Anwendungen.

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)

Bevor Sie sich verbinden, überprüfen Sie, ob die Azure CLI installiert ist, und melden Sie sich an:

az --version
az login

Um Azure CLI auf Debian oder Ubuntu zu installieren, verwenden Sie den Paketmanager:

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

Authentifizierung der Client-Zugangsdaten

Verwenden Sie die Authentifizierung der Client-Zugangsdaten für automatisierte Dienste und Hintergrundjobs.

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};"
)

Geben Sie die folgenden Parameter an:

• TenantId: Die Microsoft Entra-Tenant-ID.
• ClientId: Die Client-ID der Anwendung.
• ClientSecret: Das Client-Geheimnis.

Speichere Geheimnisse in einem sicheren Geheimspeicher oder in Umgebungsvariablen. Speichere keine Geheimnisse in Klartext-Verbindungsstrings oder INI-Dateien.

Zertifikatbasierte Authentifizierung

Verwenden Sie zertifikatsbasierte Authentifizierung für Unternehmensanwendungen, die Zertifikatsdaten benötigen.

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>;"
)

Geben Sie die folgenden Parameter an:

• TenantId: Die Microsoft Entra-Tenant-ID.
• ClientId: Die Client-ID der Anwendung.
• CertificatePath: Der Pfad zur PFX- oder PKCS12-Zertifikatsdatei.
• CertificatePassword: Das Zertifikatspasswort.

Zugriffstokenauthentifizierung

Verwenden Sie die Zugriffstoken-Authentifizierung, wenn Ihre Anwendung ein Token über einen anderen Mechanismus erhält.

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};"
)

Dateitoken-Authentifizierung

Verwenden Sie Dateitoken-Authentifizierung in containerisierten Umgebungen und automatisierten Pipelines, bei denen ein anderer Prozess ein Trägertoken in die bekannte Token-Datei des Treibers schreibt:

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

Unterstützte treiberübergreifende Eigenschaftsaliase finden Sie unter Treiberübergreifende Eigenschaftsaliase.

Konfigurationsparameter

Erforderliche Parameter

Fügen Sie diese Parameter in jede Verbindungszeichenfolge ein:

Optionale Parameter

Verbindungseinstellungen

Leistungseinstellungen

Einstellungen für die Protokollierung

Proxyeinstellungen

Einstellungen für hohe Parallelität (HC)

Verwenden Sie diese Parameter, um den High-Concurrency (HC)-Modus zu aktivieren und zu konfigurieren. Der HC-Modus ist opt-in. Wenn Sie LivyMode oder UseHighConcurrency nicht festlegen, verwendet der Treiber den klassischen Pfad für eine einzelne Sitzung. Für Hinweise und Beispiele siehe High-Concurrency (HC)-Modus.

Priorität und Validierung von Modi

• LivyMode hat Vorrang vor UseHighConcurrency, wenn Sie beide Parameter festlegen.
• Parameterwerte sind nicht groß- und grossschreibungssensitiv.
• UseHighConcurrency akzeptiert true, yes, on oder 1, um den HC-Modus zu aktivieren. Es akzeptiert false, 0, no oder off, um den HC-Modus zu deaktivieren.
• Für andere nichtleere Werte liefert ein SQLDriverConnect Fehler zurück. DSN-only protokolliert den Validierungsfehler SQLConnect und verwendet den klassischen Pfad.

Kompatibilitätseinstellungen

Der Treiber akzeptiert TenantPrincipal und PoolMax, einschließlich ihrer umgebungsvariablen Fallbacks, um mit früheren HC-Konfigurationen kompatibel zu sein. Der Treiber parselt und validiert diese Werte, aber sie beeinflussen nicht das HC-Session-Matching oder die Laufzeit-Poolkapazität. Verlassen Sie sich nicht auf sie für Mieterisolation oder Verbindungsgrenzen.

Rückfälle für Umweltvariablen

Der Treiber verwendet die folgenden Umweltvariablen nur, wenn der entsprechende DSN- oder Verbindungsstring-Parameter nicht gesetzt ist:

Für FABRIC_ODBC_USE_HC erkennt die ausschließlich umgebungsbasierte Aktivierung true, 1 oder yes (ohne Beachtung der Groß-/Kleinschreibung). Andere Werte deaktivieren den HC-Modus. Die Aliase off und on gelten nur für DSN- und Verbindungszeichenfolgenwerte.

Hoch-Nebenläufigkeit (HC) Modus

Der Modus für hohe Parallelität (HC) ermöglicht es ODBC-Verbindungen mit demselben Arbeitsbereich und demselben Lakehouse, eine Verbindung mit gemeinsam genutzten, bereits aufgewärmten serverseitigen Livy Spark-Sitzungen herzustellen, statt für jede Verbindung einen separaten Cluster bereitzustellen. Nutze es für Arbeitslasten wie BI-Dashboards, Notebook-Kernel und ETL-Fan-outs, die viele kurzlebige Verbindungen öffnen und serververwaltete Spark-Kapazitäten teilen können.

Der HC-Modus ist opt-in. Wenn du keine HC-Einstellung konfigurierst, verwendet der Treiber den klassischen Einzelsitzungspfad.

Auswählen eines Verbindungsmodus

Benutze den HC-Modus wenn:

• Ihre Arbeitslast öffnet viele kurzlebige ODBC-Verbindungen, wie BI-Dashboards, Notebook-Kernel oder ETL-Fan-Out.
• Verbindungen zielen auf denselben Arbeitsbereich und dasselbe Lakehouse ab und können eine serververwaltete Spark-Sitzung teilen.
• Die Reduzierung der Kaltstart-Latenz pro Verbindung ist wichtig.

Nutze den klassischen Modus, wenn:

• Jede Verbindung erfordert eine isolierte Spark-Sitzung aufgrund unterschiedlicher Spark-Konfigurationen oder strikter Ressourcenisolation.
• Der Fabric Livy-Endpunkt für den Zielarbeitsbereich und das Lakehouse unterstützt den HC-Modus nicht.

Aktivieren Sie den Modus für hohe Parallelität

Fügen Sie der DSN oder der Verbindungszeichenfolge einen Parameter für den Modus mit hoher Parallelität hinzu.

Empfohlen: Festlegen LivyMode

Verwenden Sie LivyMode, um den Sitzungserfassungsmodus explizit auszuwählen:

LivyMode=HighConcurrency

Unterstützte Werte sind Classic, HighConcurrencyund Auto. Werte sind nicht groß-/kleinsensitiv. Auto Derzeit wählt er den Classic-Modus.

Alternative: Satz UseHighConcurrency

Verwenden Sie die boolesche Einstellung zur Kompatibilität mit bestehenden Konfigurationen:

UseHighConcurrency=true

Zum Aktivieren des Modus für hohe Parallelität verwenden Sie true, 1, yes oder on. Um es zu deaktivieren, verwenden Sie false, 0, no oder off. Werte sind nicht groß-/kleinsensitiv. SQLDriverConnect verweigert andere nichtleere Werte mit SQLSTATE HY024. DSN-only protokolliert den Validierungsfehler SQLConnect und verwendet den klassischen Modus.

Du kannst auch den High-Concurrency-Modus für die aktuelle Shell aktivieren, indem du die Umgebungsvariablen verwendest:

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

Erforderliche Parameter im HC-Modus

Die HC-Aktivierung erfordert folgende gültige Kennungen:

Beziehen Sie SessionTag ein, weil es die serverseitige Zuordnung für Warm-Sessions beeinflusst.

Sitzungsabgleich

Der HC-Modus garantiert nicht, dass jede Verbindung eine bestehende Sitzung wiederverwendet. Für jede Anfrage zur Sitzungserfassung sendet der Treiber:

• Der SessionTag-Wert.
• Die effektive Spark-Konfiguration, einschließlich conf.* Einstellungen und EnvironmentId.

Der Fabric Livy Service bewertet diese Werte und entscheidet, ob die Verbindung mit einer warmen Sitzung verbunden oder eine neue Sitzung erstellt wird. Um die Wiederverwendung der Sitzungen zu verbessern, verwenden Sie konsistente Werte über Verbindungen hinweg, die für die gemeinsame Server-verwaltete Spark-Kapazität gedacht sind.

Exemplarische Verbindungszeichenfolgen

Minimale HC-Verbindung mit Azure CLI-Authentifizierung:

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

HC-Verbindung mit abgestimmten Auszeiten:

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

HC-Verbindung mit einer Umgebung und Spark-Konfigurationsüberschreibungen:

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 mit 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"
)

Konfigurieren Sie den HC-Modus in einem Linux-DSN

Anstatt die HC-Einstellungen in jeder Verbindungszeichenfolge zu wiederholen, speichern Sie sie in ~/.odbc.ini für ein benutzerspezifisches DSN oder in /etc/odbc.ini für ein systemweites DSN.

[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

Nachdem du die DSN gespeichert hast, verifiziere sie und teste die Verbindung.

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

Wenn ein Verbindungszeichenfolge keinen Wert angibt, liest der Treiber folgende Einstellungen aus dem DSN:

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

Der Treiber liest außerdem die nur für die Kompatibilität vorgesehenen Einstellungen TenantPrincipal und PoolMax. Verwenden Sie die Parameternamen in der HC-Einstellungstabelle.

HC-Modus deaktivieren

Du kannst neue HC-Session-Erwerbungen deaktivieren, ohne den Treiber neu zu deployen. Verwenden Sie die Methode, die mit der Aktivierung des HC-Modus übereinstimmt:

Einstellungen für Verbindungszeichenfolgen und DSNs haben Vorrang vor dem Fallback auf Umgebungsvariablen. Diese Änderungen betreffen nur neue Verbindungen. Bestehende HC-Sessions laufen weiter, bis sie veröffentlicht werden.

Verstehen Sie das Laufzeitverhalten von HC

• Validierung:SQLDriverConnect lehnt ungültige HC-Boolesche und positiv-ganzzahlige Werte mit SQLSTATE HY024ab. Es lehnt eine ungültige LivyMode sowie ungültige oder zu große WorkspaceId-, LakehouseId- und IdempotencyKey-Werte mit dem SQLSTATE HY000 ab. Ein zu großer Kompatibilitätswert TenantPrincipal gibt ebenfalls HY000 zurück. Für nur SQLConnectDSN protokolliert der Treiber gewöhnliche HC-Validierungsfehler und verwendet den klassischen Modus. Zu große sicherheitssensible Werte führen weiterhin zum Fehlschlagen der Verbindung.
• Sensible Daten: Der Treiber schließt andere sensible Felder aus HC-Logs und Diagnoseausgaben aus oder löscht IdempotencyKey sie aus.
• Stornierung: Die Kündigung des Kontoauszugs erfolgt kooperativ. Die bereits laufende Serverarbeit endet sauber, anstatt sofort beendet zu werden.
• Leistungsschalter: HC- und klassische Modi verwenden separate Leistungsschalter. Das Ausschöpfen eines Modus wirkt sich nicht auf den anderen aus.
• Anfangsdatenbank: HC-Verbindungen führen die Anfangsanweisung USE für den Parameter Database nicht aus. Führe USE <database> nach der Verbindung aus oder benutze vollständig qualifizierte Tabellennamen.
• Diagnose: Legen Sie LogLevel=DEBUG fest, um die Erfassung von HC, Abfragen, Freigaben und Entscheidungen zur Fehlerzuordnung zu protokollieren. Zur gezielten Fehlerbehebung legen Sie LIVY_HC_VERBOSE=1 so fest, dass zusätzliche bereinigte HC-HTTP-Diagnosedaten einbezogen werden.

DSN-Konfiguration

Unter Linux konfigurieren Sie Datenquellennamen (DSNs) in INI-Dateien statt in der Windows-Registry.

Erstellen eines DSN

Falls ~/.odbc.ini vorhanden, füge den neuen DSN-Abschnitt hinzu, ohne die bestehende Datei zu ersetzen. Kopiere die installierte Vorlage nur, wenn du die Datei erstellst:

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

Bearbeiten Sie ~/.odbc.ini mit den Details Ihres Fabric-Arbeitsbereichs:

[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

Verifiziere die DSN

Liste die konfigurierten DSNs auf und teste dann die Verbindung:

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

Der Befehl isql benötigt die unixODBC-Kommandozeilen-Tools. Die -k Option verwendet SQLDriverConnect, wodurch der Treiber DSN-Verbindungsattribute verarbeiten kann.

Verwendung eines DSN in Anwendungen

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);

Verwendungsbeispiele

Teste eine Verbindung mit isql

Starte eine interaktive SQL-Sitzung:

isql -k -v "DSN=FabricDSN;"

Führe eine einzelne Abfrage aus:

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

Verwenden Sie -k für Fabric DSNs, damit isql über SQLDriverConnect statt über SQLConnect verbindet.

Mit großen Ergebnismengen arbeiten

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()

Schemata und Tabellen entdecken

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()

Datentypzuordnung

Der Treiber ordnet Spark SQL-Datentypen ODBC-SQL-Typen zu:

Plattformunterschiede

Troubleshooting

Fahrer nicht gefunden

Problem: Die Verbindung schlägt mit [IM002] Data source name not found and no default driver specifiedfehl.

Lösungen:

1. Überprüfen Sie die Treiberregistrierung, indem Sie odbcinst -q -d ausführen.
2. Vergewissern Sie sich, dass /usr/lib/libmicrosoftfabricodbc.so vorhanden ist.
3. Registrieren Sie den Fahrer, indem Sie . sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.templateausführen.
4. Installieren Sie das Paket erneut, indem Sie sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb. ausführen.

Fahrer nach Tarball-Installation nicht gefunden

Problem: Der Treiber ist registriert, aber die gemeinsame Bibliothek ist nicht auf dem registrierten Pfad vorhanden.

Lösungen:

1. Vergewissern Sie sich, dass /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so vorhanden ist.
2. Erneutes Ausführen sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Wenn du ein benutzerdefiniertes Präfix verwendet hast, überprüfe, dass der Pfad des registrierten Treibers dasselbe Präfix verwendet.

DSN nicht gefunden

Problem: Die Verbindung schlägt mit [IM002] Data source name not foundfehl.

Lösungen:

1. Überprüfen Sie die DSN-Konfiguration, indem Sie odbcinst -q -s. ausführen.
2. Überprüfen Sie, ob ~/.odbc.ini oder /etc/odbc.ini den DSN-Abschnitt enthält.
3. Stellen Sie sicher, dass der Driver Wert genau mit dem Namen des registrierten Fahrers übereinstimmt.

Verbindungsfehler

Problem: Der Fahrer kann sich nicht mit Fabric verbinden.

Lösungen:

1. Überprüfen Sie, ob die Arbeitsplatz-ID und die Lakehouse-ID gültige GUIDs sind.
2. Überprüfen Sie die Azure CLI-Authentifizierung, indem Sie az account show. ausführen
3. Stelle sicher, dass du die erforderlichen Fabric-Arbeitsbereichsberechtigungen hast.
4. Überprüfe die Netzwerkverbindung und die Proxy-Einstellungen.

Authentifizierungsfehler

Problem: Die Azure CLI-Authentifizierung schlägt fehl.

Lösungen:

1. Laufen Sie az login , um Ihre Zugangsdaten zu aktualisieren.
2. Lege das richtige Abonnement fest, indem du az account set --subscription <subscription-id> ausführst.
3. Überprüfen Sie das Token, indem Sie az account get-access-token --resource https://api.fabric.microsoft.com ausführen.
4. Stellen Sie sicher, dass Ihr Konto die erforderlichen Fabric-Arbeitsbereichsberechtigungen hat.

Fehler in der gemeinsamen Bibliothek

Problem: Der Fahrer meldet error while loading shared libraries: libmicrosoftfabricodbc.so.

Lösungen:

1. Installieren Sie das Paket erneut, indem Sie sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb. ausführen.
2. Vergewissern Sie sich, dass /usr/lib/libmicrosoftfabricodbc.so vorhanden ist.
3. Führe aus, sudo ldconfig um den Cache der gemeinsamen Bibliothek zu aktualisieren.

Zeitüberschreitungen bei Abfragen

Problem: Bei Abfragen großer Tabellen tritt eine Zeitüberschreitung auf.

Lösungen:

1. Fügen Sie LargeTableSupport=true der Verbindungszeichenfolge hinzu.
2. Passen Sie PageSizeBytes für die Ergebnisgröße an.
3. Fügen Sie EnableAsyncPrefetch=1 der Verbindungszeichenfolge hinzu.
4. Verwenden Sie eine LIMIT Klausel, um die Größe des Ergebnisses zu begrenzen.

Protokollierung aktivieren

Aktivieren Sie eine detaillierte Protokollierung in einem DSN:

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

Alternativ können Sie der Verbindungszeichenfolge Protokollierungsparameter hinzufügen:

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

Der Treiber unterstützt folgende Protokollierungsstufen:

• DEBUG: Enthält detaillierte Debuginformationen und ist die ausführlichste Protokollierungsstufe des Treibers.
• INFO: Enthält allgemeine Informationen und ist der Standard.
• WARN: Enthält nur Warnungen.
• ERROR: Enthält nur Fehler.

Aktivieren Sie unixODBC-Tracing

Für die Diagnose auf niedriger ODBC-Aufrufebene fügen Sie /etc/odbcinst.ini die folgende Konfiguration hinzu:

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

Schalten Sie das Nachverfolgen aus, wenn Sie die Fehlersuche beendet haben, um unnötigen Leistungsaufwand zu vermeiden.

Verwandte Inhalte

• Microsoft ODBC-Treiber für Microsoft Fabric Data Engineering
• Apache Spark-Runtimes in Fabric
• Fabric Runtime 1.3
• Was ist die Livy-API für Data Engineering
• Microsoft JDBC-Treiber für Microsoft Fabric Data Engineering
• unixODBC