Microsoft ODBC-drivrutin för Microsoft Fabric Data Engineering på Linux

ODBC (Open Database Connectivity) är en allmänt antagen standard som gör det möjligt för klientprogram att ansluta till och arbeta med data från databaser och stordataplattformar.

Microsoft ODBC Driver för Fabric Data Engineering låter dig koppla in, fråga och hantera Spark-arbetsbelastningar i Fabric med samma tillförlitlighet och enkelhet som ODBC-standarden. Drivrutinen är byggd på Fabric:s Livy-API:er och erbjuder säker och flexibel Spark SQL-anslutning till dina C/C++, .NET, Python och andra ODBC-kompatibla applikationer på Linux.

Viktiga funktioner

• ODBC 3.x-kompatibel: Fullständig implementering av ODBC 3.x-specifikationen.
• Microsoft Entra ID-autentisering: Flera autentiseringsflöden, inklusive Azure CLI, klientuppgifter, certifikatbaserad autentisering och autentisering av åtkomsttoken.
• Stöd för Spark SQL-frågor: Direkt exekvering av Spark SQL-satser.
• Omfattande stöd för datatyper: Stöd för alla Spark SQL-datatyper, inklusive komplexa typer (ARRAY, MAP, och STRUCT).
• Återanvändning av sessioner: Inbyggd sessionshantering för förbättrad prestanda.
• Högsamtidighetsläge: Välj in delade, varma server-side Livy-sessioner för att minska anslutningsstartslatens och Spark-klustrets spridning.
• Stöd för stora tabeller: Optimerad hantering för stora resultatuppsättningar med konfigurerbara sidstorlekar.
• Asynkron förinläsning: Datainläsning i bakgrunden för förbättrad prestanda.
• Proxystöd: HTTP-proxykonfiguration för företagsmiljöer.
• Stöd för flera scheman i lakehouse: Anslut till ett specifikt schema i ett lakehouse.

Förutsättningar

Innan du använder Microsoft ODBC Driver för Microsoft Fabric Data Engineering på Linux, se till att du uppfyller följande förutsättningar:

• Operativsystem: Ubuntu 22.04 eller senare, Debian 11 eller senare, eller Red Hat Enterprise Linux (RHEL) 8 eller senare på x86-64.
• unixODBC: ODBC:s drivrutinshanterare för Linux. Installera unixodbc och unixodbc-dev paketen.
• libcurl: HTTP-runtime-beroendet, såsom libcurl4 eller motsvarande paket för din distribution.
• OpenSSL: TLS- och kryptografikörningsberoendet, såsom openssl och libssl3 eller motsvarande paket.
• Fabric access: Tillgång till en Fabric-arbetsplats.
• Microsoft Entra ID-uppgifter: Lämpliga inloggningsuppgifter för autentisering.
• Arbetsyte- och lakehouse-ID:n: GUID-identiteterna för din Fabric-arbetsyta och ditt lakehouse.
• Azure CLI (valfritt): Krävs när du använder Azure CLI-autentisering.

Ladda ner och installera på Linux

• Ladda ner Microsoft ODBC Driver för Microsoft Fabric Data Engineering på Linux (tar)

Så här installerar du drivrutinen:

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

2. Öppna en terminal i den extraherade katalogen.

3. Installera Debian-paketet:

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

Paketet installerar följande filer:

Installera ett RPM-paket

På RHEL, Fedora eller CentOS, installera RPM-paketet från det extraherade drivrutinsarkivet:

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

Alternativt, använd rpm:

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

Kontrollera att RPM har registrerat drivrutinen:

odbcinst -q -d | grep "Microsoft"

För att avinstallera RPM-paketet, kör:

sudo dnf remove microsoft-fabric-odbc-driver

Installera ett tar-arkiv

För distributioner utan Debian- eller RPM-paketstöd, eller för en anpassad installationsplats, extrahera paketet .tar.gz och kör dess installationsskript:

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

Installationsskriptet stöder dessa alternativ:

För att verifiera standardinstallationen av tarball, kör:

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

För att avinstallera den, kör sudo ./install.sh --uninstall från den extraherade paketkatalogen.

Installera drivrutin manuellt

Paketet registrerar automatiskt drivrutinen hos unixODBC. För att registrera drivrutinen manuellt, kör:

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

Kontrollera installationen

Verifiera att drivrutinen är registrerad och att biblioteket är installerat:

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

Kommandot odbcinst ska lista [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Avinstallera drivrutinen

För att avinstallera drivrutinen, kör följande kommando:

sudo dpkg -r microsoft-fabric-odbc-driver

Detta kommando tar bort drivrutinsfilerna och avregistrerar drivrutinen från unixODBC.

Snabbstartsexempel

Följande exempel ansluter till Fabric och kör en Spark SQL-fråga. Fyll i förkunskaperna och installera drivrutinen innan du kör ett exempel.

Python-exempel

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

#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 och kör exemplet:

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

.NET-exempel

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 för anslutningssträng

Grundläggande anslutningssträng

Använd följande reťazec pripojenia-format:

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

Anslutningssträngskomponenter

Exempel på anslutningssträngar

Grundläggande anslutning

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

Anslutning till prestandaalternativ

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

Koppling till skogsavverkning

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

Anslutning med läget för hög samtidighet

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

För fullständig vägledning om konfiguration, se läge för hög samtidighet (HC).

Autentisering

Microsoft ODBC Driver för Microsoft Fabric Data Engineering stöder flera autentiseringsmetoder via Microsoft Entra ID. Konfigurera autentisering genom att använda parametern AuthFlow i reťazec pripojenia eller DSN.

Autentiseringsmetoder

Azure CLI-autentisering

Använd Azure CLI-autentisering för utveckling och interaktiva 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)

Innan du ansluter, kontrollera att Azure CLI är installerat och logga in:

az --version
az login

För att installera Azure CLI på Debian eller Ubuntu, använd pakethanteraren:

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

Autentisering av klientuppgifter

Använd autentisering av klientuppgifter för automatiserade tjänster och bakgrundsjobb.

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

Ange följande parametrar:

• TenantId: Microsoft Entra-klientorganisations-ID:t.
• ClientId: Applikations-ID (klient).
• ClientSecret: Klienthemligheten.

Lagra hemligheter i en säker hemlig lagring eller miljövariabler. Spara inte hemligheter i klartextanslutningssträngar eller INI-filer.

Certifikatbaserad autentisering

Använd certifikatbaserad autentisering för företagsapplikationer som kräver certifikatuppgifter.

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

Ange följande parametrar:

• TenantId: Microsoft Entra-klientorganisations-ID:t.
• ClientId: Applikations-ID (klient).
• CertificatePath: Vägen till PFX- eller PKCS12-certifikatfilen.
• CertificatePassword: Certifikatlösenordet.

Åtkomsttokenautentisering

Använd autentisering av accesstoken när din applikation skaffar en token via en annan mekanism.

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

Autentisering med filtoken

Använd filtokenautentisering i containeriserade miljöer och automatiserade pipelines där en annan process skriver en bärartoken till drivrutinens välkända tokenfil:

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

Information om egenskapsalias mellan drivrutiner som stöds finns i Egenskapsalias mellan drivrutiner.

Konfigurationsparametrar

Obligatoriska parametrar

Inkludera dessa parametrar i varje reťazec pripojenia:

Valfria parametrar

Anslutningsinställningar

Prestandainställningar

Loggningsinställningar

Proxyinställningar

Inställningar för hög samtidighet (HC)

Använd dessa parametrar för att aktivera och konfigurera högkonkurrensläge (HC). HC-läget är frivilligt. Om du inte ställer LivyMode in eller UseHighConcurrency, använder drivrutinen den klassiska enkelsessionsvägen. Vägledning och exempel finns i läge för hög samtidighet (HC).

Lägesprioritering och validering

• LivyMode Har företräde framför UseHighConcurrency när du sätter båda parametrarna.
• Parametervärden är inte kasuskänsliga.
• UseHighConcurrency accepterar true, 1, , yes, eller on aktiverar HC-läge. Den accepterar false, 0, no eller off för att inaktivera HC-läget.
• För andra icke-tomma värden returnerar SQLDriverConnect ett fel. DSN-endast SQLConnect loggar valideringsfelet och använder den klassiska vägen.

Kompatibilitetsinställningar

Drivrutinen accepterar TenantPrincipal och PoolMax, inklusive deras miljövariabler för att säkerställa kompatibilitet med tidigare HC-konfigurationer. Drivrutinen tolkar och validerar dessa värden, men de påverkar inte HC-sessionsmatchning eller körtidspoolens kapacitet. Lita inte på dem för isolering av hyresgäster eller anslutningsbegränsningar.

Reservvärden för miljövariabler

Drivrutinen använder följande miljövariabler endast när motsvarande DSN- eller anslutningssträngsparameter inte är satt:

För FABRIC_ODBC_USE_HC känner aktivering endast för miljö igen true, 1 eller yes (skiftlägesokänsligt). Andra värden lämnar HC-läget inaktiverat. Och onoff aliasen gäller endast för DSN- och anslutningssträngsvärden.

Läge för hög samtidighet (HC)

High-concurrency (HC)-läge låter ODBC-anslutningar till samma arbetsyta och lakehouse ansluta till delade, varma server-sida Livy Spark-sessioner istället för att provisionera ett separat kluster för varje anslutning. Använd det för arbetsbelastningar som BI-dashboards, notebook-kärnor och ETL-fan-out som öppnar många kortvariga anslutningar och kan dela serverhanterad Spark-kapacitet.

HC-läget är frivilligt. Om du inte konfigurerar en HC-inställning använder drivrutinen den klassiska enkelsessionsvägen.

Välj ett anslutningsläge

Använd HC-läge när:

• Din arbetsbelastning öppnar många kortvariga ODBC-anslutningar, till exempel BI-paneler, notebook-kärnor eller ETL-förgreningar.
• Anslutningar riktar sig mot samma arbetsyta och lakehouse och kan dela en serverhanterad Spark-session.
• Att minska kallstartslatens per anslutning är viktigt.

Använd klassiskt läge när:

• Varje anslutning kräver en isolerad Spark-session på grund av olika Spark-konfigurationer eller strikt resursisolering.
• Fabric Livy-endpointen för målarbetsytan och lakehouse stöder inte HC-läge.

Aktivera läge för hög samtidighet

Lägg till en parameter för hög samtidighet i DSN:en eller anslutningssträngen.

Rekommenderat: Set LivyMode

Använd LivyMode för att explicit välja sessionsinhämtningsläget:

LivyMode=HighConcurrency

Värden som stöds är Classic, HighConcurrencyoch Auto. Värden är inte skiftlägeskänsliga. Auto Väljer för närvarande klassiskt läge.

Alternativ: Ange UseHighConcurrency

Använd den booleska inställningen för kompatibilitet med befintliga konfigurationer:

UseHighConcurrency=true

För att aktivera läge för hög samtidighet använder du true, 1, yes eller on. För att inaktivera den, använd false, 0, , noeller off. Värden är inte skiftlägeskänsliga. SQLDriverConnect förkastar andra icke-tomma värden med SQLSTATE HY024. DSN-endast SQLConnect loggar valideringsfelet och använder klassiskt läge.

Du kan också aktivera läget för hög samtidighet för det nuvarande skalet genom att använda 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ödvändiga parametrar i HC-läge

HC-aktivering kräver följande giltiga identifierare:

Inkludera SessionTag eftersom det påverkar matchningen på serversidan för uppvärmda sessioner.

Matchning av sessioner

HC-läget garanterar inte att varje anslutning återanvänder en befintlig session. För varje sessionsinhämtningsbegäran skickar drivrutinen:

• Värdet SessionTag.
• Den effektiva Spark-konfigurationen, inklusive conf.* inställningar och EnvironmentId.

Fabric Livy-tjänsten utvärderar dessa värden och beslutar om kopplingen ska kopplas till en varm session eller skapas en ny. För att förbättra återanvändning av sessioner, använd konsekventa värden över anslutningar som är avsedda att dela serverhanterad Spark-kapacitet.

Exempel på anslutningssträngar

Minimal HC-anslutning 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-anslutning med justerade tidsgränser:

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-anslutning med en miljö och konfigurationsåsidosättningar för Spark:

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

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

Konfigurera HC-läge i en Linux DSN

Istället för att upprepa HC-inställningar i varje anslutningssträng, lagra dem i ~/.odbc.ini för ett användarspecifikt DSN eller i /etc/odbc.ini för ett systemomfattande 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

Efter att du sparat DSN:et, verifiera det och testa anslutningen.

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

När en reťazec pripojenia inte specificerar något värde, läser drivrutinen dessa inställningar från DSN:n:

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

Drivrutinen läser också inställningarna TenantPrincipal och PoolMax, som endast är avsedda för kompatibilitet. Använd parameternamnen i HC-inställningstabellen.

Inaktivera HC-läget

Du kan inaktivera att nya HC-sessioner hämtas utan att driftsätta om drivrutinen. Använd metoden som motsvarar hur du aktiverade HC-läget:

Anslutningssträngs- och DSN-inställningar har företräde framför miljövariabelns fallback. Dessa förändringar påverkar endast nya anslutningar. Befintliga HC-sessioner fortsätter tills de släpps.

Förstå HC:s körtidsbeteende

• Validering:SQLDriverConnect avvisar ogiltiga HC Booleska och positiva heltalsvärden med SQLSTATE HY024. Den avvisar en ogiltig LivyMode samt ogiltiga eller för stora WorkspaceId-, LakehouseId- och IdempotencyKey-värden med SQLSTATE-koden HY000. Ett för stort kompatibilitetsvärde returnerar också HY000. För endast SQLConnectDSN loggar drivrutinen vanliga HC-valideringsfel och använder klassiskt läge. Överdimensionerade säkerhetskänsliga värden misslyckas fortfarande med anslutningen.
• Känslig data: Drivrutinen utesluter eller raderar IdempotencyKey andra känsliga fält från HC-loggar och diagnostiska utdata.
• Avbrytning: Avbrytning av satsen sker kooperativt. Pågående serverprocesser fasas ut på ett kontrollerat sätt i stället för att avbrytas omedelbart.
• Automatsäkringar: HC-läge och klassiskt läge använder separata automatsäkringar. Att tömma ett läge påverkar inte det andra.
• Initialdatabas: HC-anslutningar exekverar inte den initiala USE satsen för parametern Database . Kör USE <database> efter anslutning eller använd fullt kvalificerade tabellnamn.
• Diagnostik: Ställ LogLevel=DEBUG in för att logga beslut om HC-förvärv, polling, release och felkartläggning. För riktad felsökning anger du LIVY_HC_VERBOSE=1 så att ytterligare sanerad HC HTTP-diagnostik inkluderas.

DSN-konfiguration

På Linux, konfigurera datakällnamn (DSN) i INI-filer istället för i Windows-registret.

Skapa ett DSN

Om ~/.odbc.ini det finns, lägg till den nya DSN-sektionen utan att ersätta den befintliga filen. Kopiera den installerade mallen endast när du skapar 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

Redigera ~/.odbc.ini med dina Fabric-arbetsytsdetaljer:

[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

Verifiera DSN

Lista de konfigurerade DSN:erna och testa sedan anslutningen:

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

Kommandot isql kräver kommandoradsverktygen unixODBC. Alternativet -k använder SQLDriverConnect, vilket låter drivrutinen bearbeta DSN-anslutningsattribut.

Använd 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);

Användningsexempel

Testa en anslutning med isql

Starta en interaktiv SQL-session:

isql -k -v "DSN=FabricDSN;"

Kör en enda fråga:

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

Använd -k för Fabric-DSN:er så att isql ansluter via SQLDriverConnect i stället för SQLConnect.

Arbete med stora resultatmängder

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

Upptäck scheman och 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()

Datatypkartläggning

Drivrutinen mappar Spark SQL-datatyper till ODBC SQL-typer:

Plattformsskillnader

Felsökning

Föraren ej hittad

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

Lösningar:

1. Verifiera förarregistreringen genom att köra odbcinst -q -d.
2. Kontrollera att det /usr/lib/libmicrosoftfabricodbc.so finns.
3. Registrera föraren genom att köra sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Installera om paketet genom att köra sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Driver hittades inte efter en tarball-installation

Problem: Drivrutinen är registrerad, men det delade biblioteket finns inte på den registrerade sökvägen.

Lösningar:

1. Kontrollera att det /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so finns.
2. sudo ./install.sh --prefix=/opt/microsoft/fabricodbcKör om .
3. Om du använde ett anpassat prefix, kontrollera att den registrerade drivrutinsvägen använder samma prefix.

DSN hittades inte

Problem: Anslutningen misslyckas med [IM002] Data source name not found.

Lösningar:

1. Verifiera DSN-konfigurationen genom att köra odbcinst -q -s.
2. Kontrollera att ~/.odbc.ini eller /etc/odbc.ini innehåller avsnittet DSN.
3. Se till att Driver värdet exakt matchar den registrerade förarens namn.

Anslutningsfel

Problem: Drivrutinen kan inte ansluta till Fabric.

Lösningar:

1. Kontrollera att arbetsyte-ID:t och lakehouse-ID:t är giltiga GUID:er.
2. Kontrollera Azure CLI-autentisering genom att köra az account show.
3. Se till att du har de nödvändiga behörigheterna för Fabric-arbetsutrymmet.
4. Kolla nätverksanslutning och proxyinställningar.

Autentiseringsfel

Problem: Azure CLI-autentisering misslyckas.

Lösningar:

1. Kör az login för att uppdatera dina autentiseringsuppgifter.
2. Sätt rätt prenumeration genom att köra az account set --subscription <subscription-id>.
3. Kontrollera token genom att köra az account get-access-token --resource https://api.fabric.microsoft.com.
4. Se till att ditt konto har de nödvändiga behörigheterna för Fabric-arbetsytan.

Fel i delade bibliotek

Problem: Föraren rapporterar error while loading shared libraries: libmicrosoftfabricodbc.so.

Lösningar:

1. Installera om paketet genom att köra sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Kontrollera att det /usr/lib/libmicrosoftfabricodbc.so finns.
3. Kör sudo ldconfig för att uppdatera det delade bibliotekscachen.

Tidsgränser för frågor

Problem: Frågor överskrider tidsgränsen mot stora tabeller.

Lösningar:

1. Lägg till LargeTableSupport=true i anslutningssträngen.
2. Justera PageSizeBytes för resultatstorleken.
3. Lägg till EnableAsyncPrefetch=1 i anslutningssträngen.
4. Använd en LIMIT klausul för att begränsa resultatstorleken.

Aktivera loggning

Aktivera detaljerad loggning i ett DSN:

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

Alternativt, lägg till loggningsparametrar i reťazec pripojenia:

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

Drivrutinen stöder följande logaritmnivåer:

• DEBUG: Innehåller detaljerad felsökningsinformation och är den mest utförliga drivrutinsloggnivån.
• INFO: Innehåller allmän information och är standard.
• WARN: Innehåller endast varningar.
• ERROR: Innehåller endast fel.

Aktivera unixODBC-spårning

För låg-nivå ODBC-anropsdiagnostik, lägg till följande konfiguration i /etc/odbcinst.ini:

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

Stäng av spårning när du är klar med felsökningen för att undvika onödig prestandabelastning.

Relaterat innehåll

• Microsoft ODBC-drivrutin för Microsoft Fabric Data Engineering
• Apache Spark-körtider i Fabric
• Fabric-körmiljö 1.3
• Vad är Livy API för datateknik
• Microsoft JDBC-drivrutin för Microsoft Fabric Data Engineering
• unixODBC