Microsoft ODBC-driver voor Microsoft Fabric Data Engineering op Linux

ODBC (Open Database Connectivity) is een veelgebruikte standaard waarmee clienttoepassingen verbinding kunnen maken met en kunnen werken met gegevens uit databases en big data-platforms.

De Microsoft ODBC Driver for Fabric Data Engineering stelt je in staat om Spark-workloads in Fabric te verbinden, te bevragen en te beheren met de betrouwbaarheid en eenvoud van de ODBC-standaard. Gebouwd op de Livy-API's van Fabric, biedt de driver veilige en flexibele Spark SQL-connectiviteit naar je C/C++, .NET, Python en andere ODBC-compatibele applicaties op Linux.

Belangrijkste kenmerken

• ODBC 3.x-conform: Volledige implementatie van de ODBC 3.x-specificatie.
• Microsoft Entra ID-authenticatie: Meerdere authenticatieflows, waaronder Azure CLI, clientgegevens, certificaatgebaseerde en toegangstokenauthenticatie.
• Spark SQL-queryondersteuning: Directe uitvoering van Spark SQL-instructies.
• Uitgebreide ondersteuning voor datatypes: Ondersteuning voor alle Spark SQL-datatypes, inclusief complexe types (ARRAY, MAP, en STRUCT).
• Hergebruik van sessies: Ingebouwd sessiebeheer voor betere prestaties.
• High-concurrency-modus: Meld je aan voor gedeelde, warme server-side Livy-sessies om de opstartlatentie van de verbinding en de Spark-cluster sprawl te verminderen.
• Ondersteuning voor grote tabellen: Geoptimaliseerde behandeling voor grote resultatensets met configureerbare paginagroottes.
• Asynchroon vooraf laden: Gegevens op de achtergrond laden voor betere prestaties.
• Proxy-ondersteuning: HTTP-proxyconfiguratie voor enterprise-omgevingen.
• Ondersteuning voor multi-schema-lakehouses: Maak verbinding met een specifiek schema binnen een lakehouse.

Prerequisites

Voordat je de Microsoft ODBC Driver voor Microsoft Fabric Data Engineering op Linux gebruikt, zorg ervoor dat je aan de volgende vereisten voldoet:

• Besturingssysteem: Ubuntu 22.04 of nieuwer, Debian 11 of nieuwer, of Red Hat Enterprise Linux (RHEL) 8 of nieuwer op x86-64.
• unixODBC: De ODBC-drivermanager voor Linux. Installeer de pakketten unixodbc en unixodbc-dev.
• libcurl: De HTTP-runtime-afhankelijkheid, zoals libcurl4 of het equivalente pakket voor je distributie.
• OpenSSL: De TLS- en cryptografie-runtime-afhankelijkheid, zoals openssl en libssl3 of equivalente pakketten.
• Fabric access: Toegang tot een Fabric werkruimte.
• Microsoft Entra ID-inloggegevens: Geschikte inloggegevens voor authenticatie.
• Werkruimte- en meerhuis-ID's: De GUID-identificaties voor je Fabric-werkruimte en meerhuis.
• Azure CLI (optioneel): Vereist wanneer je Azure CLI-authenticatie gebruikt.

Download en installeer op Linux

• Download Microsoft ODBC Driver voor Microsoft Fabric Data Engineering op Linux (tar)

Het stuurprogramma installeren:

1. Pak ms-sparksql-odbc-linux-2.0.0.tar uit.

2. Open een terminal in de uitgepakte map.

3. Installeer het Debian-pakket:

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

Het pakket installeert de volgende bestanden:

Installeer een RPM-pakket

Op RHEL, Fedora of CentOS installeer je het RPM-pakket uit het uitgepakte driverarchief:

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

Alternatief kunt u gebruikmaken rpm:

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

Controleer of de RPM de driver heeft geregistreerd:

odbcinst -q -d | grep "Microsoft"

Om het RPM-pakket te verwijderen, voer je uit:

sudo dnf remove microsoft-fabric-odbc-driver

Installeer een tarball

Voor distributies zonder Debian- of RPM-pakketondersteuning, of voor een aangepaste installatielocatie, haal het .tar.gz pakket uit en voer het installatiescript uit:

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

Het installatiescript ondersteunt deze opties:

Om de standaard tarball-installatie te verifiëren, voer je uit:

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

Om dit te verwijderen, voert u sudo ./install.sh --uninstall uit vanuit de map van het uitgepakte pakket.

Stuur de chauffeur handmatig in

Het pakket registreert de driver automatisch bij unixODBC. Om de driver handmatig te registreren, voer je uit:

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

De installatie controleren

Controleer of de driver geregistreerd is en dat de bibliotheek is geïnstalleerd:

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

Het odbcinst commando zou moeten vermelden [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Verwijder de driver

Om de driver te verwijderen, voer je het volgende commando uit:

sudo dpkg -r microsoft-fabric-odbc-driver

Dit commando verwijdert de driverbestanden en verwijdert het register van de driver uit unixODBC.

Snelstartvoorbeeld

De volgende voorbeelden verbinden met Fabric en voeren een Spark SQL-query uit. Voltooi de vereisten en installeer de driver voordat je een voorbeeld uitvoert.

Python-voorbeeld

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++ voorbeeld

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

Bouw en draai het voorbeeld:

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

.NET-voorbeeld

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

Indeling van verbindingstekenreeks

Basisverbindingsreeks

Gebruik het volgende verbindingsreeks-formaat:

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

Onderdelen van verbindingsreeks

Voorbeeld van verbindingsreeksen

Basisverbinding

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

Verbinding met prestatie-opties

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

Verbinding met logging

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

Verbinding met modus voor hoge gelijktijdigheid

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

Voor volledige configuratierichtlijnen, zie High-concurrency (HC) mode).

Verificatie

De Microsoft ODBC Driver for Microsoft Fabric Data Engineering ondersteunt meerdere authenticatiemethoden via Microsoft Entra ID. Configureer authenticatie door de AuthFlow parameter in de verbindingsreeks of DSN te gebruiken.

Verificatiemethoden

Azure CLI-verificatie

Gebruik Azure CLI-authenticatie voor ontwikkel- en interactieve applicaties.

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)

Controleer voordat je verbinding maakt of de Azure CLI is geïnstalleerd en log in:

az --version
az login

Om Azure CLI op Debian of Ubuntu te installeren, gebruik je de pakketbeheerder:

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

Authenticatie van clientgegevens

Gebruik client-credential-authenticatie voor geautomatiseerde diensten en achtergrondopdrachten.

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

Geef de volgende parameters op:

• TenantId: De Microsoft Entra tenant-ID.
• ClientId: de toepassings-id (client).
• ClientSecret: Het cliëntgeheim.

Bewaar geheimen in een beveiligde geheime opslag of omgevingsvariabelen. Sla geen geheimen op in platte tekst verbindingsstrings of INI-bestanden.

Verificatie op basis van certificaat

Gebruik certificaatgebaseerde authenticatie voor bedrijfsapplicaties die certificaatgegevens vereisen.

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

Geef de volgende parameters op:

• TenantId: De Microsoft Entra tenant-ID.
• ClientId: de toepassings-id (client).
• CertificatePath: Het pad naar het PFX- of PKCS12-certificaatbestand.
• CertificatePassword: Het certificaatwachtwoord.

Verificatie van toegangstokens

Gebruik toegangstokenauthenticatie wanneer je applicatie via een ander mechanisme een token verkrijgt.

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

Authenticatie met bestandstoken

Gebruik bestandstokenauthenticatie in containeriseerde omgevingen en geautomatiseerde pijplijnen waarbij een ander proces een bearertoken schrijft naar het bekende tokenbestand van de driver:

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

Voor ondersteunde cross-driver property aliases, zie Cross-driver property aliases.

Configuratieparameters

Benodigde parameters

Neem deze parameters op in elke verbindingsreeks:

Optionele parameters

Verbindingsinstellingen

Prestatie-instellingen

Instellingen voor logboekregistratie

Proxy-instellingen

Instellingen voor hoge gelijktijdigheid (HC)

Gebruik deze parameters om high-concurrency (HC) modus in te schakelen en te configureren. HC-modus moet worden ingeschakeld. Als je niet instelt LivyMode of UseHighConcurrency, gebruikt de driver het klassieke pad voor één sessie. Voor richtlijnen en voorbeelden raadpleegt u High-concurrency (HC) mode.

Modusprioriteit en validatie

• LivyMode Heeft voorrang boven UseHighConcurrency wanneer je beide parameters instelt.
• Parameterwaarden zijn niet hoofdlettergevoelig.
• UseHighConcurrency accepteert true, 1, , yesof on om HC-modus in te schakelen. Het accepteert false, 0, , no, of off om HC-modus uit te schakelen.
• Voor andere niet-lege waarden geeft een SQLDriverConnect foutmelding terug. DSN-only SQLConnect registreert de validatiefout en gebruikt het klassieke pad.

Compatibiliteitsinstellingen

De driver accepteert TenantPrincipal en PoolMax, inclusief hun omgevingsvariabele fallbacks, voor compatibiliteit met eerdere HC-configuraties. De driver parseert en valideert deze waarden, maar ze hebben geen invloed op het matchen van HC-sessies of de capaciteit van de runtimepool. Vertrouw er niet op voor huurdersisolatie of verbindingsbeperkingen.

Terugvalopties voor omgevingsvariabelen

De driver gebruikt de volgende omgevingsvariabelen alleen wanneer de bijbehorende DSN- of verbindingsstringparameter niet is ingesteld:

Voor FABRIC_ODBC_USE_HC herkent inschakeling alleen voor omgevingen true, 1 of yes (ongeacht hoofdletters en kleine letters). Andere waarden zorgen ervoor dat de HC-modus uitgeschakeld blijft. De on en off aliasen gelden alleen voor DSN- en verbindingsstringwaarden.

Modus voor hoge gelijktijdigheid (HC)

Met de modus voor hoge gelijktijdigheid (HC) kunnen ODBC-verbindingen naar dezelfde werkruimte en hetzelfde lakehouse verbinding maken met gedeelde, actieve Livy Spark-sessies aan de serverzijde, in plaats van voor elke verbinding een afzonderlijk cluster in te richten. Gebruik het voor workloads zoals BI-dashboards, notebook-kernels en ETL-fan-out die veel kortstondige verbindingen openen en serverbeheerde Spark-capaciteit kunnen delen.

HC-modus moet worden ingeschakeld. Als je geen HC-instelling instelt, gebruikt de driver het klassieke pad voor één sessie.

Een verbindingsmodus kiezen

Gebruik HC-modus wanneer:

• Je werklast opent veel kortstondige ODBC-verbindingen, bijvoorbeeld BI-dashboards, kernels van notebooks of ETL-fan-out.
• Verbindingen richten zich op dezelfde werkruimte en lakehouse en kunnen een serverbeheerde Spark-sessie delen.
• Het verminderen van de koude startlatentie per verbinding is belangrijk.

Gebruik de klassieke modus wanneer:

• Elke verbinding vereist een geïsoleerde Spark-sessie vanwege verschillende Spark-configuraties of strikte resource-isolatie.
• Het Fabric Livy-eindpunt voor de doelwerkruimte en het lakehouse biedt geen ondersteuning voor HC-modus.

Schakel de modus voor hoge gelijktijdigheid in

Voeg een parameter voor de modus voor hoge gelijktijdigheid toe aan de DSN of verbindingsreeks.

Aanbevolen: Set LivyMode

Gebruik LivyMode dit om expliciet de sessie-acquisitiemodus te selecteren:

LivyMode=HighConcurrency

Ondersteunde waarden zijn Classic, HighConcurrencyen Auto. Waarden zijn niet hoofdlettergevoelig. Auto Selecteert momenteel de klassieke modus.

Alternatief: Set UseHighConcurrency

Gebruik de Booleaanse instelling voor compatibiliteit met bestaande configuraties:

UseHighConcurrency=true

Om de modus voor hoge gelijktijdigheid in te schakelen, gebruikt u true, 1, yes of on. Om het uit te schakelen, gebruik false, 0, no, of off. Waarden zijn niet hoofdlettergevoelig. SQLDriverConnect verwerpt andere niet-lege waarden met SQLSTATE HY024. DSN-only SQLConnect registreert de validatiefout en gebruikt de klassieke modus.

Je kunt ook high-concurrency-modus inschakelen voor de huidige shell door gebruik te maken van omgevingsvariabelen:

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

Vereiste parameters in HC-modus

HC-activatie vereist de volgende geldige identificaties:

Neem het op SessionTag omdat het server-side matching voor warme sessies beïnvloedt.

Sessiekoppeling

HC-modus garandeert niet dat elke verbinding een bestaande sessie hergebruikt. Voor elk sessie-acquisitieverzoek stuurt de driver het volgende:

• De SessionTag-waarde.
• De effectieve Spark-configuratie, inclusief conf.* instellingen en EnvironmentId.

De Fabric Livy-dienst beoordeelt deze waarden en beslist of de verbinding aan een warme sessie wordt gekoppeld of een nieuwe sessie wordt aangemaakt. Om het hergebruik van sessies te verbeteren, gebruik consistente waarden over verbindingen die bedoeld zijn om serverbeheerde Spark-capaciteit te delen.

Voorbeeld van verbindingsreeksen

Minimale HC-verbinding met Azure CLI-authenticatie:

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

HC-verbinding met afgestemde time-outs:

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-verbinding met een omgeving en Spark-configuratie-overrides:

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

Configureer HC-modus in een Linux DSN

In plaats van HC-instellingen in elke verbindingsreeks te herhalen, sla ze op ~/.odbc.ini voor een gebruikersspecifieke DSN of /etc/odbc.ini voor een systeembreed 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

Nadat je het DSN hebt opgeslagen, verifieer het en test je de verbinding.

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

Wanneer een verbindingsreeks geen waarde specificeert, leest de driver deze instellingen uit het DSN:

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

Het stuurprogramma leest ook de instellingen TenantPrincipal en PoolMax die alleen voor compatibiliteit bedoeld zijn. Gebruik de parameternamen in de HC-instellingentabel.

Schakel HC-modus uit

Je kunt nieuwe HC-sessies aankopen uitschakelen zonder de driver opnieuw te deployen. Gebruik de methode die overeenkomt met hoe je HC-modus hebt ingeschakeld:

Connection-string en DSN-instellingen krijgen voorrang boven de omgevingsvariabele fallback. Deze veranderingen hebben alleen invloed op nieuwe verbindingen. Bestaande HC-sessies gaan door tot ze worden uitgebracht.

Begrijp het uitvoerende gedrag van HC

• Validatie:SQLDriverConnect verwerpt ongeldige HC Booleaanse en positieve-gehele getallen met SQLSTATE HY024. Het verwerpt een ongeldig(e) LivyMode en ongeldige of te grote waarden voor WorkspaceId, LakehouseId en IdempotencyKey met SQLSTATE HY000. Een te grote compatibiliteitswaarde TenantPrincipal resulteert ook in HY000. Voor DSN-only SQLConnect, registreert de driver gewone HC-validatiefouten en gebruikt de klassieke modus. Te grote beveiligingskritieke waarden zorgen er nog steeds voor dat de verbinding mislukt.
• Gevoelige gegevens: De driver sluit andere gevoelige velden uit of verwijdert IdempotencyKey deze uit HC-logs en diagnostische output.
• Annuleren: Het annuleren van een statement gebeurt coöperatief. Het serverwerk dat al in uitvoering is, wordt schoon afgerond in plaats van direct te worden beëindigd.
• Stroomonderbraken: HC- en klassieke modi gebruiken aparte stroomonderbrekers. Het uitputten van de ene modus beïnvloedt de andere niet.
• Initiële database: HC-verbindingen voeren de initiële USE instructie voor de Database parameter niet uit. Voer USE <database> uit nadat u verbinding hebt gemaakt of gebruik volledig gekwalificeerde tabelnamen.
• Diagnostiek: Stel LogLevel=DEBUG in om het verkrijgen van HC, polling, vrijgave en beslissingen over fouttoewijzing te loggen. Voor gerichte probleemoplossing kun je LIVY_HC_VERBOSE=1 instellen op het opnemen van extra opgeschoonde HC HTTP-diagnostiek.

DSN-configuratie

Op Linux configureer je databronnamen (DSN's) in INI-bestanden in plaats van in het Windows-register.

Een DSN maken

Als ~/.odbc.ini dat bestaat, voeg dan de nieuwe DSN-sectie toe zonder het bestaande bestand te vervangen. Kopieer de geïnstalleerde template alleen wanneer je het bestand aanmaakt:

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

Bewerk ~/.odbc.ini met de details van je Fabric-werkruimte:

[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

Controleer het DSN

Geef een lijst van de geconfigureerde DSN's en test vervolgens de verbinding:

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

Voor het isql commando zijn de unixODBC-opdrachtregelprogramma's vereist. De -k optie gebruikt SQLDriverConnect, waarmee de driver DSN-verbindingsattributen verwerkt.

Gebruik een DSN in applicaties

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

Voorbeelden van gebruik

Test een verbinding met isql

Start een interactieve SQL-sessie:

isql -k -v "DSN=FabricDSN;"

Voer één enkele query uit:

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

Gebruik -k voor Fabric DSN’s zodat isql verbinding maakt via SQLDriverConnect in plaats van via SQLConnect.

Werk met grote resultatensets

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

Ontdek schema’s en tabellen

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

Koppeling van gegevenstypen

Het stuurprogramma wijst Spark SQL-gegevenstypen toe aan ODBC SQL-typen:

Platformverschillen

Probleemoplossingsproces

Bestuurder niet gevonden

Probleem: De verbinding faalt met [IM002] Data source name not found and no default driver specified.

Oplossingen:

1. Controleer de chauffeursregistratie door te draaien odbcinst -q -d.
2. Controleer of dat bestaat /usr/lib/libmicrosoftfabricodbc.so .
3. Registreer het stuurprogramma door sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template uit te voeren.
4. Installeer het pakket opnieuw door . uit te voeren sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Driver niet gevonden na een tarball-installatie

Probleem: De driver is geregistreerd, maar de gedeelde bibliotheek is niet aanwezig op het geregistreerde pad.

Oplossingen:

1. Controleer of dat bestaat /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so .
2. Opnieuw uitvoeren sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Als je een aangepaste prefix hebt gebruikt, controleer dan of het pad van de geregistreerde driver hetzelfde prefix gebruikt.

DSN is niet gevonden

Probleem: De verbinding faalt met [IM002] Data source name not found.

Oplossingen:

1. Controleer de DSN-configuratie door te draaien odbcinst -q -s.
2. Controleer dat of /etc/odbc.ini het ~/.odbc.ini DSN-gedeelte bevat.
3. Zorg ervoor dat de Driver waarde precies overeenkomt met de naam van de geregistreerde bestuurder.

Verbindingsfouten

Probleem: De driver kan geen verbinding maken met Fabric.

Oplossingen:

1. Controleer of de workspace ID en lakehouse ID geldige GUIDs zijn.
2. Controleer de Azure CLI-authenticatie door az account show uit te voeren.
3. Zorg dat je de vereiste Fabric-werkruimterechten hebt.
4. Controleer de netwerkconnectiviteit en proxy-instellingen.

Authenticatiefouten

Probleem: Azure CLI-authenticatie faalt.

Oplossingen:

1. Ren az login om je gegevens te verversen.
2. Stel het juiste abonnement in door az account set --subscription <subscription-id> uit te voeren.
3. Controleer het token door az account get-access-token --resource https://api.fabric.microsoft.com uit te voeren.
4. Zorg ervoor dat je account de vereiste Fabric-werkruimterechten heeft.

Fouten in gedeelde bibliotheken

Probleem: De bestuurder meldt error while loading shared libraries: libmicrosoftfabricodbc.so.

Oplossingen:

1. Installeer het pakket opnieuw door . uit te voeren sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Controleer of dat bestaat /usr/lib/libmicrosoftfabricodbc.so .
3. Voer sudo ldconfig uit om de gedeelde bibliotheekcache te vernieuwen.

Time-outs voor zoekopdrachten

Probleem: Er treedt een time-out op bij query's op grote tabellen.

Oplossingen:

1. Voeg LargeTableSupport=true toe aan de verbindingsreeks.
2. Pas PageSizeBytes aan op de grootte van het resultaat.
3. Voeg EnableAsyncPrefetch=1 toe aan de verbindingsreeks.
4. Gebruik een LIMIT clausule om de grootte van het resultaat te beperken.

Logboekregistratie inschakelen

Schakel gedetailleerde logging in een DSN in:

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

Alternatief kun je loggparameters toevoegen aan de verbindingsreeks:

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

De driver ondersteunt de volgende logboekniveaus:

• DEBUG: Bevat gedetailleerde foutopsporingsinformatie en is het meest uitgebreide logniveau voor stuurprogramma's.
• INFO: Bevat algemene informatie en is de standaard.
• WARN: Bevat alleen waarschuwingen.
• ERROR: Bevat alleen fouten.

Schakel unixODBC-tracering in

Voor laag-niveau ODBC-aanroepdiagnostiek voegt u de volgende configuratie toe aan /etc/odbcinst.ini:

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

Zet het traceren uit zodra je klaar bent met het oplossen van problemen om onnodige prestatie-overhead te voorkomen.

Verwante onderwerpen

• Microsoft ODBC-stuurprogramma voor Microsoft Fabric Data Engineering
• Apache Spark-runtimes in Fabric
• Fabric Runtime 1.3
• Wat is de Livy-API voor Data Engineering?
• Microsoft JDBC-stuurprogramma voor Microsoft Fabric Data Engineering
• unixODBC