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

ODBC (Open Database Connectivity) er en mye brukt standard som gjør det mulig for klientapplikasjoner å koble til og arbeide med data fra databaser og big data-plattformer.

Microsoft ODBC Driver for Fabric Data Engineering lar deg koble til, spørre og administrere Spark-arbeidsbelastninger i Fabric med påliteligheten og enkelheten til ODBC-standarden. Bygget på Fabric sine Livy-API-er, gir driveren sikker og fleksibel Spark SQL-tilkobling til dine C/C++, .NET, Python og andre ODBC-kompatible applikasjoner på Linux.

Viktige funksjoner

• ODBC 3.x-kompatibel: Full implementering av ODBC 3.x-spesifikasjonen.
• Microsoft Entra ID-autentisering: Flere autentiseringsprosesser, inkludert Azure CLI, klientlegitimasjon, sertifikatbasert autentisering og tilgangstokenautentisering.
• Spark SQL-spørringsstøtte: Direkte kjøring av Spark SQL-setninger.
• Omfattende støtte for datatyper: Støtte for alle Spark SQL-datatyper, inkludert komplekse typer (ARRAY, MAP, og STRUCT).
• Gjenbruk av sesjoner: Innebygd sesjonsadministrasjon for bedre ytelse.
• Høy-samtidighetsmodus: Velg delte, varme server-side Livy-økter for å redusere tilkoblingsoppstartsforsinkelse og Spark-klyngespredning.
• Støtte for store tabeller: Optimalisert håndtering for store resultatsett med konfigurerbare sidestørrelser.
• Asynkron forhåndshenting: Bakgrunnsdata laster inn for bedre ytelse.
• Proxy-støtte: HTTP-proxykonfigurasjon for bedriftsmiljøer.
• Multi-skjema lakehouse-støtte: Koble til et spesifikt skjema i et lakehouse.

Forutsetninger

Før du bruker Microsoft ODBC-driveren for Microsoft Fabric Data Engineering på Linux, må du sørge for at du har følgende forutsetninger:

• Operativsystem: Ubuntu 22.04 eller nyere, Debian 11 eller nyere, eller Red Hat Enterprise Linux (RHEL) 8 eller nyere på x86-64.
• unixODBC: ODBC-driveradministratoren for Linux. Installer unixodbc og-pakkene unixodbc-dev .
• libcurl: HTTP-kjøretidsavhengigheten, for eksempel libcurl4 eller tilsvarende pakke for distribusjonen din.
• OpenSSL: TLS- og kryptografi-runtime-avhengighet, som for eksempel openssl og libssl3 tilsvarende pakker.
• Fabric access: Tilgang til et Fabric-arbeidsområde.
• Microsoft Entra ID-legitimasjon: Passende legitimasjon for autentisering.
• Workspace- og lakehouse-ID-er: GUID-identifikatorene for din Fabric workspace og lakehouse.
• Azure CLI (valgfritt): Kreves når du bruker Azure CLI-autentisering.

Last ned og installer på Linux

• Last ned Microsoft ODBC-driver for Microsoft Fabric Data Engineering på Linux (tar)

For å installere driveren:

1. Trekk ut ms-sparksql-odbc-linux-2.0.0.tar.

2. Åpne en terminal i den utpakkede katalogen.

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, installer RPM-pakken fra det utpakkede driverarkivet:

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

Alternativt, bruk rpm:

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

Sjekk at RPM registrerte driveren:

odbcinst -q -d | grep "Microsoft"

For å avinstallere RPM-pakken, kjør:

sudo dnf remove microsoft-fabric-odbc-driver

Installer en tarball

For distribusjoner uten Debian- eller RPM-pakkestøtte, eller for et tilpasset installasjonssted, pakk ut .tar.gz pakken og kjør installasjonsskriptet:

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

Installasjonsskriptet støtter disse alternativene:

For å verifisere standard tarball-installasjon, kjør:

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

For å avinstallere den, kjør sudo ./install.sh --uninstall fra den pakkede pakkekatalogen.

Registrer driveren manuelt

Pakken registrerer automatisk driveren hos unixODBC. For å registrere driveren manuelt, kjør:

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

Verifiser installasjonen

Verifiser at driveren er registrert og at biblioteket er installert:

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

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

Avinstaller driveren

For å avinstallere driveren, kjør følgende kommando:

sudo dpkg -r microsoft-fabric-odbc-driver

Denne kommandoen fjerner driverfilene og avregistrerer driveren fra unixODBC.

Eksempel på hurtigstart

Følgende eksempler kobler til Fabric og kjører en Spark SQL-spørring. Fullfør forutsetningene og installer driveren før du kjø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;
}

Bygg og kjør eksempelet:

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

Tilkoblingsstrengformat

Grunnleggende tilkoblingsstreng

Bruk følgende tilkoblingsstreng-format:

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

Tilkoblingsstrengkomponenter

Eksempler på tilkoblingsstrenger

Grunnleggende forbindelse

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

Tilkobling med ytelsesalternativer

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 med hogst

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øy samtidighetsmodus

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

For fullstendig konfigurasjonsveiledning, se High-concurrency (HC) mode).

Godkjenning

Microsoft ODBC-driveren for Microsoft Fabric Data Engineering støtter flere autentiseringsmetoder gjennom Microsoft Entra ID. Konfigurer autentisering ved å bruke parameteren AuthFlow i tilkoblingsstreng eller DSN.

Godkjenningsmetoder

Azure CLI-autentisering

Bruk Azure CLI-autentisering for utviklings- og interaktive applikasjoner.

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 kobler til, sjekk at Azure CLI er installert og logg inn:

az --version
az login

For å installere Azure CLI på Debian eller Ubuntu, bruk pakkebehandleren:

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

Autentisering av klientopplysninger

Bruk autentisering av klientinformasjon for automatiserte tjenester og bakgrunnsjobber.

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

Oppgi følgende parametere:

• TenantId: Microsoft Entra-leietaker-ID.
• ClientId: Applikasjons- (klient-)ID-en.
• ClientSecret: Klientens hemmelighet.

Lagre hemmeligheter i en sikker hemmelig lagring eller miljøvariabler. Ikke lagre hemmeligheter i klartekstforbindelser eller INI-filer.

Sertifikatbasert godkjenning

Bruk sertifikatbasert autentisering for bedriftsapplikasjoner som krever sertifikatlegitimasjon.

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

Oppgi følgende parametere:

• TenantId: Microsoft Entra-leietaker-ID.
• ClientId: Applikasjons- (klient-)ID-en.
• CertificatePath: Veien til PFX- eller PKCS12-sertifikatfilen.
• CertificatePassword: Sertifikatpassordet.

Autentisering av tilgangstoken

Bruk autentisering av tilgangstokenet når applikasjonen din får tak i en token gjennom en annen 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};"
)

Filtokenautentisering

Bruk filtokenautentisering i containeriserte miljøer og automatiserte pipelines der en annen prosess skriver en bærertoken til driverens velkjente tokenfil:

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

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

Konfigurasjonsparametere

Påkrevde parametere

Inkluder disse parameterne i hver tilkoblingsstreng:

Valgfrie parametere

Tilkoblingsinnstillinger

Ytelsesinnstillinger

Loggingsinnstillinger

Proxy-innstillinger

Høy-samtidighetsinnstillinger (HC)

Bruk disse parameterne for å aktivere og konfigurere høy-samtidighet (HC)-modus. HC-modus er frivillig. Hvis du ikke setter LivyMode eller UseHighConcurrency, bruker driveren den klassiske enkeltsesjonsruten. For veiledning og eksempler, se High-concurrency (HC)-modus.

Modusforrang og validering

• LivyMode Har forrang over UseHighConcurrency når du setter begge parameterne.
• Parameterverdiene er ikke små og små og mellombokstaver.
• UseHighConcurrency aksepterer true, 1, yes, eller on for å aktivere HC-modus. Den godtar false, 0, , noeller off å deaktivere HC-modus.
• For andre ikke-tomme verdier returnerer SQLDriverConnect en feil. DSN-only SQLConnect logger valideringsfeilen og bruker den klassiske stien.

Kompatibilitetsinnstillinger

Driveren aksepterer TenantPrincipal og PoolMax, inkludert deres miljøvariable fallbacks, for kompatibilitet med tidligere HC-konfigurasjoner. Driveren parser og validerer disse verdiene, men de påvirker ikke HC-sesjonsmatching eller kapasiteten i kjøretidspoolen. Ikke stol på dem for leietakerisolasjon eller tilkoblingsbegrensninger.

Miljøvariabler for fallbacks

Driveren bruker følgende miljøvariabler kun når den tilsvarende DSN- eller tilkoblingsstrengparameteren ikke er satt:

For FABRIC_ODBC_USE_HC, gjenkjenner truekun miljøaktivering , 1, eller yes (kasus-ufølsom). Andre verdier lar HC-modus være deaktivert. Og onoff aliasene gjelder kun for DSN- og tilkoblingsstrengverdier.

Høy-samtidighet (HC) modus

High-concurrency (HC)-modus lar ODBC-tilkoblinger til samme arbeidsområde og lakehouse koble seg til delte, varme server-side Livy Spark-økter i stedet for å opprette en separat klynge for hver tilkobling. Bruk det til arbeidsbelastninger som BI-dashbord, notebook-kjerner og ETL-fan-out som åpner mange kortvarige tilkoblinger og kan dele serveradministrert Spark-kapasitet.

HC-modus er frivillig. Hvis du ikke konfigurerer en HC-innstilling, bruker driveren den klassiske enkeltsesjonsstien.

Velg en tilkoblingsmodus

Bruk HC-modus når:

• Arbeidsmengden din åpner mange kortvarige ODBC-tilkoblinger, som BI-dashbord, notebook-kjerner eller ETL-fan-out.
• Tilkoblinger retter seg mot samme arbeidsområde og lakehouse, og kan dele en serverstyrt Spark-økt.
• Å redusere kaldstartsforsinkelse per tilkobling er viktig.

Bruk klassisk modus når:

• Hver tilkobling krever en isolert Spark-økt på grunn av ulike Spark-konfigurasjoner eller streng ressursisolasjon.
• Fabric Livy-endepunktet for målarbeidsområdet og lakehouse støtter ikke HC-modus.

Aktiver høy-samtidighetsmodus

Legg til en høy-samtidighetsmodusparameter til DSN- eller tilkoblingsstreng.

Anbefalt: Sett LivyMode

Bruk LivyMode for å velge sesjonsinnhentingsmodus eksplisitt:

LivyMode=HighConcurrency

Støttede verdier er Classic, HighConcurrencyog Auto. Verdier er ikke små og små bokstaver. Auto Velger for øyeblikket klassisk modus.

Alternativ: Sett UseHighConcurrency

Bruk Boolean-innstillingen for kompatibilitet med eksisterende konfigurasjoner:

UseHighConcurrency=true

For å aktivere høy-samtidighetsmodus, bruk true, 1, yes, eller on. For å deaktivere den, bruk false, 0, no, eller off. Verdier er ikke små og små bokstaver. SQLDriverConnect avviser andre ikke-tomme verdier med SQLSTATE HY024. DSN-only SQLConnect logger valideringsfeilen og bruker klassisk modus.

Du kan også aktivere høy-samtidighetsmodus for det nåværende skallet ved å bruke 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

Nødvendige parametere i HC-modus

HC-aktivering krever følgende gyldige identifikatorer:

Inkluder SessionTag fordi det påvirker server-side matching for varme økter.

Sesjonsmatching

HC-modus garanterer ikke at hver tilkobling gjenbruker en eksisterende økt. For hver forespørsel om sesjonsinnhenting sender driveren:

• Verdien SessionTag .
• Den effektive Spark-konfigurasjonen, inkludert conf.* innstillinger og EnvironmentId.

Fabric Livy-tjenesten vurderer disse verdiene og bestemmer om forbindelsen skal knyttes til en varm sesjon eller opprettes en ny. For å forbedre gjenbruk av sesjoner, bruk konsistente verdier på tvers av tilkoblinger som er ment å dele serveradministrert Spark-kapasitet.

Eksempler på tilkoblingsstrenger

Minimal HC-tilkobling med Azure CLI-autentisering:

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

HC-tilkobling med justerte 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-tilkobling med et miljø og Spark-konfigurasjonsoverstyringer:

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

Konfigurer HC-modus i en Linux DSN

I stedet for å gjenta HC-innstillinger i hver tilkoblingsstreng, lagre dem for ~/.odbc.ini en brukerspesifikk DSN eller /etc/odbc.ini for en 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

Etter at du har lagret DSN-et, verifiser det og test tilkoblingen.

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

Når en tilkoblingsstreng ikke spesifiserer en verdi, leser driveren disse innstillingene fra DSN:

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

Føreren leser også kun TenantPrincipal kompatibilitet og PoolMax innstillinger. Bruk parameternavnene i HC-innstillingstabellen.

Deaktiver HC-modus

Du kan deaktivere nye HC-sesjonsinnhentinger uten å deployere driveren på nytt. Bruk metoden som tilsvarer hvordan du aktiverte HC-modus:

Tilkoblingsstreng- og DSN-innstillinger har forrang over miljøvariabel-fallback. Disse endringene gjelder kun nye forbindelser. Eksisterende HC-økter fortsetter til de slippes.

Forstå HC sin kjøretidsoppførsel

• Validering:SQLDriverConnect avviser ugyldige HC boolske og positive heltallsverdier med SQLSTATE HY024. Den avviser en ugyldig LivyMode og ugyldig eller overdimensjonert WorkspaceId, LakehouseId, og IdempotencyKey verdier med SQLSTATE HY000. En overdimensjonert kompatibilitetsverdi TenantPrincipal returnerer HY000også . For kun SQLConnectDSN logger driveren vanlige HC-valideringsfeil og bruker klassisk modus. Overdimensjonerte sikkerhetsfølsomme verdier feiler fortsatt forbindelsen.
• Sensitive data: Driveren ekskluderer eller fjerner IdempotencyKey andre sensitive felt fra HC-logger og diagnostiske resultater.
• Avbestilling: Avbestilling av kontoutskrift er samarbeidsvillig. Serverarbeid som allerede pågår avsluttes rent i stedet for å bli avsluttet umiddelbart.
• Sikringer: HC- og klassiske moduser bruker separate sikringer. Å bruke ut én modus påvirker ikke den andre.
• Startdatabase: HC-tilkoblinger utfører ikke den opprinnelige USE setningen for parameteren Database . Kjør USE <database> etter tilkobling eller bruk fullt kvalifiserte tabellnavn.
• Diagnostikk: Sett LogLevel=DEBUG til å loggføre beslutninger om HC-innhenting, polling, frigivelse og feilkartlegging. For fokusert feilsøking, sett LIVY_HC_VERBOSE=1 til å inkludere ekstra renset HC HTTP-diagnostikk.

DSN-konfigurasjon

På Linux, konfigurer datakildenavn (DSN) i INI-filer i stedet for i Windows-registeret.

Opprett et DSN

Hvis ~/.odbc.ini det finnes, legg til den nye DSN-seksjonen uten å erstatte den eksisterende filen. Kopier den installerte malen kun når du oppretter 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-arbeidsområ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

Verifiser DSN-en

List opp de konfigurerte DSN-ene, og test deretter tilkoblingen:

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

Kommandoen isql krever kommandolinjeverktøyene unixODBC. Alternativet -k bruker SQLDriverConnect, som lar driveren behandle DSN-tilkoblingsattributter.

Bruk DSN i applikasjoner

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

Brukseksempler

Test en tilkobling med isql

Start en interaktiv SQL-økt:

isql -k -v "DSN=FabricDSN;"

Kjør én enkelt spørring:

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

Bruk -k for Fabric DSN-er slik at isql de kobler gjennom SQLDriverConnect i stedet for SQLConnect.

Arbeid med store resultatsett

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

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

Tilordning av datatype

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

Plattformforskjeller

Feilsøking

Føreren ikke funnet

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

Løsninger:

1. Verifiser førerregistreringen ved å kjøre odbcinst -q -d.
2. Sjekk at det /usr/lib/libmicrosoftfabricodbc.so finnes.
3. Registrer sjåføren ved å kjøre sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Installer pakken på nytt ved å kjøre sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Driver ikke funnet etter en tarball-installasjon

Problem: Driveren er registrert, men det delte biblioteket er ikke til stede på den registrerte stien.

Løsninger:

1. Sjekk at det /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so finnes.
2. Kjør på nytt sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Hvis du brukte et tilpasset prefiks, sjekk at den registrerte driverstien bruker samme prefiks.

DSN ikke funnet

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

Løsninger:

1. Verifiser DSN-konfigurasjonen ved å kjøre odbcinst -q -s.
2. Verifiser at ~/.odbc.ini eller /etc/odbc.ini inneholder DSN-delen.
3. Sørg for at verdien samsvarer Driver nøyaktig med den registrerte sjåførens navn.

Tilkoblingsfeil

Problem: Driveren kan ikke koble til Fabric.

Løsninger:

1. Sjekk at arbeidsplass-ID-en og lakehouse-ID-en er gyldige GUID-er.
2. Sjekk Azure CLI-autentisering ved å kjøre az account show.
3. Sørg for at du har de nødvendige Fabric-arbeidsplasstillatelsene.
4. Sjekk nettverkstilkobling og proxy-innstillinger.

Godkjenningsfeil

Problem: Azure CLI-autentisering feiler.

Løsninger:

1. Løp az login for å oppdatere legitimasjonen din.
2. Sett riktig abonnement ved å kjøre az account set --subscription <subscription-id>.
3. Sjekk tokenet ved å kjøre az account get-access-token --resource https://api.fabric.microsoft.com.
4. Sørg for at kontoen din har de nødvendige Fabric-arbeidsplasstillatelsene.

Delte bibliotekfeil

Problem: Føreren rapporterer error while loading shared libraries: libmicrosoftfabricodbc.so.

Løsninger:

1. Installer pakken på nytt ved å kjøre sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Sjekk at det /usr/lib/libmicrosoftfabricodbc.so finnes.
3. Kjør sudo ldconfig for å oppdatere cachen i det delte biblioteket.

Spørringstidsavbrudd

Problem: Forespørsler går ut på tid på store tabeller.

Løsninger:

1. Legg til LargeTableSupport=true i tilkoblingsstreng.
2. Juster PageSizeBytes for resultatstørrelsen.
3. Legg til EnableAsyncPrefetch=1 i tilkoblingsstreng.
4. Bruk en LIMIT klausul for å begrense resultatstørrelsen.

Aktiver logging

Aktiver detaljert logging i et DSN:

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

Alternativt, legg til loggingsparametere i tilkoblingsstreng:

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

Driveren støtter følgende log-nivåer:

• DEBUG: Inkluderer detaljert feilsøkingsinformasjon og er det mest ordrike nivået på driverloggen.
• INFO: Inkluderer generell informasjon og er standard.
• WARN: Inkluderer kun advarsler.
• ERROR: Inneholder kun feil.

Aktiver unixODBC-sporing

For lavnivå ODBC-kalldiagnostikk, legg til følgende konfigurasjon til /etc/odbcinst.ini:

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

Slå av sporing når du er ferdig med feilsøking for å unngå unødvendig ytelsesbelastning.

Relatert innhold

• Microsoft ODBC-driver for Microsoft Fabric Data Engineering
• Apache Spark runtimes i Stoff
• Stoff Kjøretid 1.3
• Hva er Livy API for Data Engineering
• Microsoft JDBC-driver for Microsoft Fabric Data Engineering
• unixODBC