Microsoft ODBC-driver til Microsoft Fabric Data Engineering på Linux

ODBC (Open Database Connectivity) er en bredt anvendt standard, der gør det muligt for klientapplikationer at forbinde til og arbejde med data fra databaser og big data-platforme.

Microsoft ODBC Driver for Fabric Data Engineering lader dig forbinde, forespørge og administrere Spark-arbejdsbelastninger i Fabric med pålideligheden og enkelheden fra ODBC-standarden. Drevet er bygget på Fabric's Livy API'er og leverer sikker og fleksibel Spark SQL-forbindelse til dine C/C++, .NET, Python og andre ODBC-kompatible applikationer på Linux.

Nøglefunktioner

• ODBC 3.x-kompatibel: Fuld implementering af ODBC 3.x-specifikationen.
• Microsoft Entra ID-autentificering: Flere autentificeringsflows, herunder Azure CLI, klientoplysninger, certifikatbaseret og adgangstoken-autentificering.
• Spark SQL-forespørgselsunderstøttelse: Direkte udførelse af Spark SQL-sætninger.
• Omfattende understøttelse af datatyper: Understøttelse af alle Spark SQL-datatyper, inklusive komplekse typer (ARRAY, MAP, og STRUCT).
• Genbrug af sessioner: Indbygget sessionstyring for forbedret ydeevne.
• Høj-samtidighedstilstand: Vælg delte, varme server-side Livy-sessioner for at reducere forbindelsesopstartsforsinkelse og Spark-klyngens spredning.
• Understøttelse af store tabel: Optimeret håndtering af store resultatsæt med konfigurerbare sidestørrelser.
• Asynkron prefetch: Indlæsning af baggrundsdata for forbedret ydeevne.
• Proxy-understøttelse: HTTP-proxykonfiguration til virksomhedsmiljøer.
• Multi-schema lakehouse-support: Forbind til et specifikt skema inden for et lakehouse.

Forudsætninger

Før du bruger Microsoft ODBC Driver til Microsoft Fabric Data Engineering på Linux, skal du sikre dig, at du opfylder følgende forudsætninger:

• Operativsystem: Ubuntu 22.04 eller nyere, Debian 11 eller nyere, eller Red Hat Enterprise Linux (RHEL) 8 eller senere på x86-64.
• unixODBC: ODBC's drivermanager til Linux. Installer og-pakkerne unixodbcunixodbc-dev .
• libcurl: HTTP-runtime-afhængigheden, såsom libcurl4 eller den tilsvarende pakke til din distribution.
• OpenSSL: TLS og kryptografi-runtime-afhængighed, såsom openssl og libssl3 eller tilsvarende pakker.
• Fabric access: Adgang til et Fabric-arbejdsområde.
• Microsoft Entra ID-legitimationsoplysninger: Passende legitimationsoplysninger til autentificering.
• Workspace- og lakehouse-ID'er: GUID-identifikatorerne for dit Fabric-arbejdsområde og lakehouse.
• Azure CLI (valgfrit): Påkrævet, når du bruger Azure CLI-autentificering.

Download og installer på Linux

• Download Microsoft ODBC Driver til Microsoft Fabric Data Engineering på Linux (tar)

For at installere driveren:

1. Udtræk ms-sparksql-odbc-linux-2.0.0.tar.

2. Åbn en terminal i den udpakkede mappe.

3. Installer Debian-pakken:

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

Pakken installerer følgende filer:

Installer en RPM-pakke

På RHEL, Fedora eller CentOS installerer du RPM-pakken fra det udpakkede driverarkiv:

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

Alternativt kan du bruge rpm:

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

Verdsig, at omdrejningstallet registrerede driveren:

odbcinst -q -d | grep "Microsoft"

For at afinstallere RPM-pakken, kør:

sudo dnf remove microsoft-fabric-odbc-driver

Installer en tarball

For distributioner uden Debian- eller RPM-pakkeunderstøttelse, eller for en brugerdefineret installationsplacering, udpak .tar.gz pakken og kør dens installationsscript:

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

Installationsscriptet understøtter disse muligheder:

For at verificere standard tarball-installationen, kør:

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

For at afinstallere det, kør sudo ./install.sh --uninstall fra den udpakkede pakkemappe.

Registrer driveren manuelt

Pakken registrerer automatisk driveren hos unixODBC. For at registrere driveren manuelt, kør:

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

Verificér installationen

Kontroller at driveren er registreret, og at biblioteket er installeret:

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

Kommandoen odbcinst skal vise [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Afinstaller driveren

For at afinstallere driveren, kør følgende kommando:

sudo dpkg -r microsoft-fabric-odbc-driver

Denne kommando fjerner driverfilerne og afregistrerer driveren fra unixODBC.

Eksempel på hurtigstart

Følgende eksempler forbinder til Fabric og kører en Spark SQL-forespørgsel. Gennemfør forudsætningerne og installer driveren, før du kører et eksempel.

Python-eksempel

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

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

Byg og kør eksemplet:

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

.NET-eksempel

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

Forbindelsesstrengsformat

Grundlæggende forbindelsesstreng

Brug følgende forbindelsesstreng-format:

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

Forbindelsesstrengskomponenter

Eksempel på forbindelsesstrenge

Grundlæggende forbindelse

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

Forbindelse med performance-muligheder

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

Forbindelse til skovhugning

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

Forbindelse med høj-samtidighedstilstand

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

For fuldstændig konfigurationsvejledning, se High-concurrency (HC) mode).

Godkendelse

Microsoft ODBC Driver for Microsoft Fabric Data Engineering understøtter flere autentificeringsmetoder via Microsoft Entra ID. Konfigurér autentificering ved at bruge parameteren AuthFlow i forbindelsesstreng eller DSN.

Godkendelsesmetoder

Azure CLI authentication

Brug Azure CLI-autentificering til udvikling og interaktive applikationer.

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)

Før du forbinder, skal du sikre dig, at Azure CLI er installeret, og log ind:

az --version
az login

For at installere Azure CLI på Debian eller Ubuntu, brug pakkehåndteringen:

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

Klientlegitimationsautentificering

Brug kundelegitimationsgodkendelse til automatiserede tjenester og baggrundsjobs.

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

Angiv følgende parametre:

• TenantId: Microsoft Entra lejer-ID.
• ClientId: Applikations-(klient-)ID'et.
• ClientSecret: Klientens hemmelighed.

Gem hemmeligheder i en sikker hemmelig butik eller miljøvariable. Gem ikke hemmeligheder i klartekst-forbindelsesstrenge eller INI-filer.

Certifikatbaseret godkendelse

Brug certifikatbaseret autentificering til virksomhedsapplikationer, der kræver certifikatoplysninger.

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

Angiv følgende parametre:

• TenantId: Microsoft Entra lejer-ID.
• ClientId: Applikations-(klient-)ID'et.
• CertificatePath: Stien til PFX- eller PKCS12-certifikatfilen.
• CertificatePassword: Certifikatets adgangskode.

Adgangstoksgodkendelse

Brug adgangstoken-autentificering, når din applikation får en token gennem en anden mekanisme.

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

Filtoken-autentificering

Brug filtoken-autentificering i containeriserede miljøer og automatiserede pipelines, hvor en anden proces skriver en bærertoken til driverens velkendte tokenfil:

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

For understøttede cross-driver property aliases, se Cross-driver property aliases.

Konfigurationsparametre

Påkrævede parametre

Inkluder disse parametre i hver forbindelsesstreng:

Valgfrie parametre

Forbindelsesindstillinger

Ydelsesindstillinger

Logningsindstillinger

Proxy-indstillinger

Høj-samtidighed (HC) indstillinger

Brug disse parametre til at aktivere og konfigurere high-concurrency (HC) tilstand. HC-tilstand er opt-in. Hvis du ikke sætter LivyMode eller UseHighConcurrency, bruger driveren den klassiske enkelt-session-sti. For vejledning og eksempler, se High-concurrency (HC) mode.

Mode-prioritet og validering

• LivyMode Har forrang over UseHighConcurrency , når du sætter begge parametre.
• Parameterværdier er ikke små og små bogstaver.
• UseHighConcurrency accepterer true, 1, , yes, eller on for at aktivere HC-tilstand. Den accepterer false, 0, no, eller off at deaktivere HC-tilstand.
• For andre ikke-tomme værdier SQLDriverConnect returnerer en fejl. DSN-only SQLConnect logger valideringsfejlen og bruger den klassiske sti.

Kompatibilitetsindstillinger

Driveren accepterer TenantPrincipal og PoolMax, inklusive deres miljøvariable fallbacks, for kompatibilitet med tidligere HC-konfigurationer. Driveren parser og validerer disse værdier, men de påvirker ikke HC-sessionsmatchning eller runtime-poolkapacitet. Stol ikke på dem til lejerisolering eller forbindelsesbegrænsninger.

Miljøvariable faldbacks

Driveren bruger kun følgende miljøvariabler, når den tilsvarende DSN- eller forbindelsesstrengparameter ikke er sat:

For FABRIC_ODBC_USE_HC, genkender truekun miljø-aktivering , 1, eller yes (kasus-insensitiv). Andre værdier lader HC-tilstand være deaktiveret. Og off aliaserne on gælder kun for DSN- og forbindelsesstrengsværdier.

Høj-samtidighed (HC) tilstand

High-concurrency (HC) tilstand lader ODBC-forbindelser til samme arbejdsområde og lakehouse tilknytte sig til delte, varme server-side Livy Spark-sessioner i stedet for at provisionere en separat klynge for hver forbindelse. Brug det til arbejdsbelastninger som BI-dashboards, notebook-kerner og ETL-fan-out, der åbner mange kortvarige forbindelser og kan dele serveradministreret Spark-kapacitet.

HC-tilstand er opt-in. Hvis du ikke konfigurerer en HC-indstilling, bruger driveren den klassiske enkelt-session-sti.

Vælg en forbindelsestilstand

Brug HC-tilstand når:

• Din arbejdsbyrde åbner mange kortlivede ODBC-forbindelser, såsom BI-dashboards, notebook-kerner eller ETL-fan-out.
• Forbindelser retter sig mod det samme arbejdsområde og lakehouse og kan dele en serverstyret Spark-session.
• At reducere latenstid ved koldstart pr. forbindelse er vigtigt.

Brug klassisk tilstand, når:

• Hver forbindelse kræver en isoleret Spark-session på grund af forskellige Spark-konfigurationer eller streng ressourceisolering.
• Fabric Livy-endpointet for det målrettede arbejdsområde og lakehouse understøtter ikke HC-tilstand.

Aktiver høj-samtidighedstilstand

Tilføj en parameter for høj samtidighed til DSN- eller forbindelsesstreng.

Anbefalet: Set LivyMode

Brug LivyMode til eksplicit at vælge sessionsindsamlingstilstanden:

LivyMode=HighConcurrency

Understøttede værdier er Classic, HighConcurrencyog Auto. Værdier er ikke små og små bogstaver. Auto Vælger i øjeblikket klassisk tilstand.

Alternativ: Set UseHighConcurrency

Brug Boolean-indstillingen for kompatibilitet med eksisterende konfigurationer:

UseHighConcurrency=true

For at aktivere høj-samtidighedstilstand brug true, , , yes, eller on1. For at deaktivere det, brug false, , , no, eller off0. Værdier er ikke små og små bogstaver. SQLDriverConnect afviser andre ikke-tomme værdier med SQLSTATE HY024. DSN-only SQLConnect logger valideringsfejlen og bruger klassisk tilstand.

Du kan også aktivere high-concurrency mode for den nuværende shell ved at bruge miljøvariabler:

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

Påkrævede parametre i HC-tilstand

HC-aktivering kræver følgende gyldige identifikatorer:

Inkludér SessionTag , fordi det påvirker server-side matching for varme sessioner.

Sessionsmatchning

HC-tilstand garanterer ikke, at hver forbindelse genbruger en eksisterende session. For hver session-anskaffelsesanmodning sender driveren:

• Værdien SessionTag .
• Den effektive Spark-konfiguration, inklusive conf.* indstillinger og EnvironmentId.

Fabric Livy-tjenesten vurderer disse værdier og beslutter, om forbindelsen skal knyttes til en varm session eller oprettes en ny. For at forbedre genbrug af sessioner skal man bruge konsistente værdier på tværs af forbindelser, der er beregnet til at dele serveradministreret Spark-kapacitet.

Eksempel på forbindelsesstrenge

Minimal HC-forbindelse med Azure CLI authentication:

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

HC-forbindelse med tunede timeouts:

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-forbindelse med et miljø og Spark-konfigurationsoverskrivninger:

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 medpyodbc:

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

Konfigurer HC-tilstand i en Linux DSN

I stedet for at gentage HC-indstillinger i hver forbindelsesstreng, gem dem i ~/.odbc.ini et brugerspecifikt DSN eller /etc/odbc.ini for et systemomfattende 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

Når du har gemt DSN, skal du verificere det og teste forbindelsen.

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

Når en forbindelsesstreng ikke specificerer en værdi, læser driveren disse indstillinger fra DSN:

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

Føreren læser også kun TenantPrincipal kompatibilitet og PoolMax indstillinger. Brug parameternavnene i HC-indstillingstabellen.

Deaktiver HC-tilstand

Du kan deaktivere nye HC-sessioner uden at genudrulle driveren. Brug den metode, der svarer til, hvordan du aktiverede HC-tilstand:

Forbindelsesstreng- og DSN-indstillinger har forrang frem for miljøvariabel-fallback. Disse ændringer påvirker kun nye forbindelser. Eksisterende HC-sessioner fortsætter, indtil de bliver udgivet.

Forstå HC-runtime-adfærd

• Validering:SQLDriverConnect afviser ugyldige HC booleske og positive heltalsværdier med SQLSTATE HY024. Den afviser en ugyldig LivyMode og ugyldig eller overdimensioneret WorkspaceId, LakehouseId, og IdempotencyKey værdier med SQLSTATE HY000. En overdimensioneret kompatibilitetsværdi TenantPrincipal returnerer HY000også . For kun SQLConnectDSN logger driveren almindelige HC-valideringsfejl og bruger klassisk tilstand. Overdimensionerede sikkerhedsfølsomme værdier fejler stadig forbindelsen.
• Følsomme data: Driveren udelukker eller fjerner IdempotencyKey andre følsomme felter fra HC-logs og diagnostiske output.
• Annullering: Annullering af kontoudtog er samarbejdsvillig. Serverarbejde, der allerede er i gang, afsluttes rent i stedet for straks at blive afsluttet.
• Afbrydere: HC- og klassiske tilstande bruger separate afbrydere. At udtømme den ene tilstand påvirker ikke den anden.
• Startdatabase: HC-forbindelser udfører ikke den indledende USE sætning for parameteren Database . Kør USE <database> efter tilslutning eller brug fuldt kvalificerede tabelnavne.
• Diagnostik: Indstil LogLevel=DEBUG til at logge beslutninger om HC-indsamling, polling, frigivelse og fejlkortlægning. For fokuseret fejlfinding skal du indsætte LIVY_HC_VERBOSE=1 til at inkludere yderligere rensede HC HTTP-diagnostik.

DSN-konfiguration

På Linux konfigureres datakildenavne (DSN'er) i INI-filer i stedet for i Windows-registret.

Opret et DSN

Hvis ~/.odbc.ini det findes, tilføj den nye DSN-sektion uden at erstatte den eksisterende fil. Kopier kun den installerede skabelon, når du opretter filen:

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

Rediger ~/.odbc.ini med dine Fabric-arbejdsområdedetaljer:

[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

Verificér DSN

List de konfigurerede DSN'er, og test derefter forbindelsen:

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

Kommandoen isql kræver kommandolinjeværktøjerne unixODBC. Muligheden -k bruger SQLDriverConnect, som lader driveren behandle DSN-forbindelsesattributter.

Brug et DSN i applikationer

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

Eksempler på anvendelse

Test en forbindelse med isql

Start en interaktiv SQL-session:

isql -k -v "DSN=FabricDSN;"

Kør en enkelt forespørgsel:

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

Brug -k til Fabric DSN'er, så isql de forbinder gennem SQLDriverConnect i stedet for SQLConnect.

Arbejde med store resultatsæt

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

Opdag skemaer og tabeller

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

Datatypetilknytning

Driveren mapper Spark SQL-datatyper til ODBC SQL-typer:

Platformforskelle

Fejlfinding

Chauffør ikke fundet

Problem: Forbindelsen fejler med [IM002] Data source name not found and no default driver specified.

Løsninger:

1. Verificér førerregistreringen ved at køre odbcinst -q -d.
2. Bekræfte at det /usr/lib/libmicrosoftfabricodbc.so findes.
3. Registrer føreren ved at køre sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Geninstaller pakken ved at køre sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Driveren blev ikke fundet efter en tarball-installation

Problem: Driveren er registreret, men det delte bibliotek er ikke til stede på den registrerede sti.

Løsninger:

1. Bekræfte at det /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so findes.
2. Kør igen sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Hvis du brugte et brugerdefineret præfiks, så bekræft at den registrerede driversti bruger det samme præfiks.

DSN ikke fundet

Problem: Forbindelsen fejler med [IM002] Data source name not found.

Løsninger:

1. Verificér DSN-konfigurationen ved at køre odbcinst -q -s.
2. Bekræft at ~/.odbc.ini det indeholder /etc/odbc.ini DSN-sektionen.
3. Sørg for, at værdien Driver præcist matcher den registrerede førers navn.

Forbindelsesfejl

Problem: Driveren kan ikke forbinde til Fabric.

Løsninger:

1. Bekræft, at arbejdsområde-ID'et og lakehouse-ID'et er gyldige GUID'er.
2. Tjek Azure CLI-autentificering ved at køre az account show.
3. Sørg for, at du har de nødvendige tilladelser til Fabric workspace.
4. Tjek netværksforbindelse og proxyindstillinger.

Godkendelsesfejl

Problem: Azure CLI-autentificering fejler.

Løsninger:

1. Løb az login for at opdatere dine legitimationsoplysninger.
2. Sæt det korrekte abonnement ved at køre az account set --subscription <subscription-id>.
3. Tjek tokenet ved at køre az account get-access-token --resource https://api.fabric.microsoft.com.
4. Sørg for, at din konto har de nødvendige Fabric-arbejdsområde-tilladelser.

Delte biblioteksfejl

Problem: Chaufføren rapporterer error while loading shared libraries: libmicrosoftfabricodbc.so.

Løsninger:

1. Geninstaller pakken ved at køre sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Bekræfte at det /usr/lib/libmicrosoftfabricodbc.so findes.
3. Kør sudo ldconfig for at opdatere cachen til det delte bibliotek.

Timeout for forespørgsler

Problem: Forespørgsler går ud på store tabeller.

Løsninger:

1. Tilføj LargeTableSupport=true til forbindelsesstreng.
2. Juster PageSizeBytes for resultatstørrelsen.
3. Tilføj EnableAsyncPrefetch=1 til forbindelsesstreng.
4. Brug en LIMIT klausul til at begrænse resultatstørrelsen.

Aktiver logning

Aktiver detaljeret logning i et DSN:

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

Alternativt kan du tilføje logningsparametre til forbindelsesstreng:

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

Driveren understøtter følgende log-niveauer:

• DEBUG: Indeholder detaljeret fejlfinding og er det mest udførlige driver-logniveau.
• INFO: Indeholder generel information og er standarden.
• WARN: Indeholder kun advarsler.
• ERROR: Indeholder kun fejl.

Aktivér unixODBC-sporing

For lavniveau ODBC-kaldsdiagnostik, tilføj følgende konfiguration til /etc/odbcinst.ini:

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

Slå sporing fra, når du er færdig med fejlfinding, for at undgå unødvendigt ydelsesmæssigt overhead.

Relateret indhold

• Microsoft ODBC-driver til Microsoft Fabric Data Engineering
• Apache Spark-runtimes i Fabric
• Stof Driftstid 1.3
• Hvad er Livy API til Data Engineering
• Microsoft JDBC Driver til Microsoft Fabric Data Engineering
• unixODBC