Driver Microsoft ODBC per Microsoft Fabric Data Engineering su Linux

ODBC (Open Database Connectivity) è uno standard ampiamente adottato che consente alle applicazioni client di connettersi e lavorare con i dati provenienti da database e piattaforme Big Data.

Il driver Microsoft ODBC per Fabric Data Engineering ti permette di connettere, interrogare e gestire carichi di lavoro Spark in Fabric con l'affidabilità e la semplicità dello standard ODBC. Costruito sulle API Livy di Fabric, il driver offre connettività Spark SQL sicura e flessibile per le tue applicazioni compatibili con C/C++, .NET, Python e altre compatibili ODBC su Linux.

Funzionalità principali

• Conforme a ODBC 3.x: Implementazione completa della specifica ODBC 3.x.
• Autenticazione Microsoft Entra ID: Flussi di autenticazione multipli, inclusi interfaccia della riga di comando di Azure, credenziali client, certificati e autenticazione tramite token di accesso.
• Supporto alle query Spark SQL: esecuzione diretta delle istruzioni SQL di Spark.
• Supporto completo dei tipi di dati: Supporto per tutti i tipi di dati SQL di Spark, inclusi i tipi complessi (ARRAY, MAP, e STRUCT).
• Riutilizzo della sessione: gestione delle sessioni integrata per migliorare le prestazioni.
• Modalità ad alta concorrenza: Opta per sessioni Livy condivise e calde lato server per ridurre la latenza di avvio della connessione e la diffusione del cluster Spark.
• Supporto per tabelle grandi: gestione ottimizzata per grandi set di risultati con dimensioni di pagina configurabili.
• Precaricamento asincrono: caricamento dei dati in background per migliorare le prestazioni.
• Supporto proxy: configurazione proxy HTTP per ambienti aziendali.
• Supporto per lakehouse con più schemi: connettiti a uno schema specifico all'interno di un lakehouse.

Prerequisiti

Prima di utilizzare il driver Microsoft ODBC per Microsoft Fabric Data Engineering su Linux, assicurati di avere i seguenti prerequisiti:

• Sistema operativo: Ubuntu 22.04 o successiva, Debian 11 o successiva, o Red Hat Enterprise Linux (RHEL) 8 o successivamente su x86-64.
• unixODBC: Il gestore di driver ODBC per Linux. Installa i pacchetti unixodbc e unixodbc-dev.
• libcurl: La dipendenza a runtime HTTP, come libcurl4 o il pacchetto equivalente per la tua distribuzione.
• OpenSSL: la dipendenza di runtime per TLS e la crittografia, ad esempio openssl e libssl3 o pacchetti equivalenti.
• Accesso a Fabric: Accesso a uno spazio di lavoro Fabric.
• Credenziali Microsoft Entra ID: Credenziali appropriate per l'autenticazione.
• ID dello spazio di lavoro e della casa sul lago: gli identificatori GUID per il tuo spazio di lavoro Fabric e la casa sul lago.
• interfaccia della riga di comando di Azure (opzionale): Richiesta quando si utilizza l'autenticazione interfaccia della riga di comando di Azure.

Scarica e installa su Linux

• Scarica il driver Microsoft ODBC per Microsoft Fabric Data Engineering su Linux (tar)

Per installare il driver:

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

2. Apri un terminale nella directory estratta.

3. Installa il pacchetto Debian:

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

Il pacchetto installa i seguenti file:

Installa un pacchetto RPM

Su RHEL, Fedora o CentOS, installa il pacchetto RPM dall'archivio dei driver estratti:

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

In alternativa, usa rpm:

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

Verifica che i giri al minuto registrino il driver:

odbcinst -q -d | grep "Microsoft"

Per disinstallare il pacchetto RPM, esegui:

sudo dnf remove microsoft-fabric-odbc-driver

Installare un tarball

Per distribuzioni senza supporto a Debian o pacchetti RPM, o per una posizione di installazione personalizzata, estrai il .tar.gz pacchetto ed esegui il suo script di installazione:

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

Lo script di installazione supporta queste opzioni:

Per verificare l'installazione predefinita del tarball, esegui:

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

Per disinstallarlo, esegui sudo ./install.sh --uninstall dalla directory del pacchetto estratto.

Registra il driver manualmente

Il package registra automaticamente il driver con unixODBC. Per registrare manualmente il driver, digitare:

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

Verificare l'installazione

Verifica che il driver sia registrato e che la libreria sia installata:

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

Il odbcinst comando dovrebbe elencare [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Disinstalla il driver

Per disinstallare il driver, esegui il seguente comando:

sudo dpkg -r microsoft-fabric-odbc-driver

Questo comando rimuove i file del driver e disregistra il driver da unixODBC.

Esempio di avvio rapido

I seguenti esempi si collegano a Fabric ed eseguono una query Spark SQL. Completa i prerequisiti e installa il driver prima di eseguire un esempio.

esempio di Python

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

Esempio di C/C++

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

Costruisci e esegui l'esempio:

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

esempio di .NET

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

Formato stringa di connessione

Stringa di connessione di base

Usa il seguente formato di stringa di connessione:

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

Componenti della stringa di connessione

Esempi di stringhe di connessione

Connessione di base

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

Connessione con le opzioni di prestazione

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

Connessione con registrazione

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

Connessione con la modalità ad alta concorrenza

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

Per una guida completa sulla configurazione, vedi modalità ad alta concorrenza (HC).

Authentication

Il driver Microsoft ODBC per Microsoft Fabric Data Engineering supporta più metodi di autenticazione tramite Microsoft Entra ID. Configura l'autenticazione usando il parametro AuthFlow nella stringa di connessione o DSN.

Metodi di autenticazione

Autenticazione dell’interfaccia della riga di comando di Azure

Usa l'autenticazione interfaccia della riga di comando di Azure per lo sviluppo e le applicazioni interattive.

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)

Prima di connetterti, verifica che interfaccia della riga di comando di Azure sia installata e accedi:

az --version
az login

Per installare interfaccia della riga di comando di Azure su Debian o Ubuntu, usa il gestore di pacchetti:

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

Autenticazione delle credenziali client

Usa l'autenticazione delle credenziali del client per servizi automatizzati e lavori in background.

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

Fornire i parametri seguenti:

• TenantId: L'ID tenant di Microsoft Entra.
• ClientId: ID dell'applicazione (client).
• ClientSecret: Il segreto del cliente.

Memorizza i segreti in un archivio segreto sicuro o in variabili di ambiente. Non memorizzare segreti in stringhe di connessione in testo semplice o file INI.

Autenticazione basata su certificati

Utilizzare l'autenticazione basata su certificati per applicazioni aziendali che richiedono credenziali di certificazione.

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

Fornire i parametri seguenti:

• TenantId: L'ID tenant di Microsoft Entra.
• ClientId: ID dell'applicazione (client).
• CertificatePath: Il percorso verso il file di certificati PFX o PKCS12.
• CertificatePassword: La password del certificato.

Autenticazione del token di accesso

Usa l'autenticazione del token di accesso quando la tua applicazione acquisisce un token tramite un altro meccanismo.

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

Autenticazione del file token

Usa l'autenticazione tramite file di token in ambienti containerizzati e pipeline automatizzate, in cui un altro processo scrive un token bearer nel file di token predefinito del driver:

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

Per gli alias di proprietà cross-driver supportati, consulta Alias di proprietà cross-driver.

Parametri di configurazione

Parametri obbligatori

Includi questi parametri in ogni stringa di connessione:

Parametri facoltativi

Impostazioni di connessione

Impostazioni delle prestazioni

Impostazioni di registrazione

Impostazioni proxy

Impostazioni ad alta concorrenza (HC)

Utilizzare questi parametri per abilitare e configurare la modalità ad alta concorrenza (HC). La modalità HC è facoltativa. Se non imposti LivyMode o UseHighConcurrency, il driver utilizza il classico percorso a sessione singola. Per indicazioni ed esempi, vedi modalità ad alta concorrenza (HC).

Precedenza modale e validazione

• LivyMode ha la precedenza rispetto UseHighConcurrency a quando imposti entrambi i parametri.
• I valori dei parametri non distinguono tra maiuscole e minuscole.
• UseHighConcurrency accetta true, 1, yes o on per abilitare la modalità HC. Accetta false, 0, no o off per disabilitare la modalità HC.
• Per altri valori non vuoti, SQLDriverConnect restituisce un errore. Solo SQLConnect DSN registra il fallimento di validazione e utilizza il percorso classico.

Impostazioni di compatibilità

Il driver supporta TenantPrincipal e PoolMax, inclusi i corrispondenti valori di fallback tramite variabili di ambiente, per garantire la compatibilità con le precedenti configurazioni HC. Il driver analizza e valida questi valori, ma non influiscono sull'abbinamento delle sessioni HC o sulla capacità del pool runtime. Non affidarti a loro per l'isolamento degli inquilini o i limiti di connessione.

Valori di fallback delle variabili d'ambiente

Il driver utilizza le seguenti variabili di ambiente solo quando il parametro DSN o stringa di connessione corrispondente non è impostato:

Per FABRIC_ODBC_USE_HC, l'abilitazione limitata all'ambiente riconosce true, 1 o yes (senza distinzione tra maiuscole e minuscole). Altri valori lasciano la modalità HC disabilitata. Gli on alias e off si applicano solo ai valori DSN e delle stringhe di connessione.

Modalità ad alta concorrenza (HC)

La modalità High Concurrency (HC) permette alle connessioni ODBC allo stesso spazio di lavoro e allo stesso lakehouse di collegarsi a sessioni Livy Spark condivise e calde lato server invece di fornire un cluster separato per ogni connessione. Usalo per carichi di lavoro come dashboard BI, kernel di notebook e fan-out ETL che aprono molte connessioni di breve durata e possono condividere la capacità Spark gestita dal server.

La modalità HC è facoltativa. Se non configuri un'impostazione HC, il driver usa il classico percorso a sessione singola.

Scegliere una modalità di connessione

Usa la modalità HC quando:

• Il tuo carico di lavoro apre molte connessioni ODBC di breve durata, come dashboard BI, kernel di notebook o fan-out ETL.
• Le connessioni mirano allo stesso spazio di lavoro e allo stesso lago e possono condividere una sessione Spark gestita dal server.
• Ridurre la latenza di avvio a freddo per connessione è importante.

Usa la modalità classica quando:

• Ogni connessione richiede una sessione Spark isolata a causa delle diverse configurazioni di Spark o di un isolamento rigoroso delle risorse.
• L'endpoint Fabric Livy per lo spazio di lavoro target e lakehouse non supporta la modalità HC.

Abilita la modalità ad alta concorrenza

Aggiungi un parametro per la modalità a elevata concorrenza al DSN o alla stringa di connessione.

Consigliato: Set LivyMode

Usare LivyMode per selezionare esplicitamente la modalità acquisizione sessione:

LivyMode=HighConcurrency

I valori supportati sono Classic, HighConcurrencye Auto. I valori non fanno distinzione tra maiuscole e minuscole. Auto Attualmente seleziona la modalità classica.

Alternativa: Set UseHighConcurrency

Usa l'impostazione booleana per la compatibilità con le configurazioni esistenti:

UseHighConcurrency=true

Per abilitare la modalità ad alta concorrenza, usare true, 1, yes, o on. Per disabilitarla, usa false, 0, no, o off. I valori non fanno distinzione tra maiuscole e minuscole. SQLDriverConnect rifiuta altri valori non vuoti con SQLSTATE HY024. Solo DSN SQLConnect registra l’errore di convalida e utilizza la modalità classica.

Puoi anche abilitare la modalità ad alta concorrenza per la shell attuale usando variabili ambientali:

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

Parametri richiesti in modalità HC

L'attivazione HC richiede i seguenti identificatori validi:

Includi SessionTag perché influenza il matching lato server per le sessioni calde.

Abbinamento delle sessioni

La modalità HC non garantisce che ogni connessione riutilizzi una sessione esistente. Per ogni richiesta di acquisizione di sessione, il pilota invia:

• Il valore SessionTag.
• La configurazione effettiva di Spark, inclusi conf.* i parametri e EnvironmentId.

Il servizio Fabric Livy valuta questi valori e decide se collegare la connessione a una sessione calda o crearne una nuova. Per migliorare il riutilizzo delle sessioni, utilizza valori coerenti tra le connessioni che sono destinate a condividere la capacità di Spark gestita dal server.

Esempi di stringhe di connessione

Connessione HC minima con autenticazione interfaccia della riga di comando di Azure:

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

Connessione HC con timeout regolati:

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

Connessione HC con un ambiente e sovrascrittura della configurazione di 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 con 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"
)

Configura la modalità HC in una DSN Linux

Invece di ripetere le impostazioni HC in ogni stringa di connessione, memorizzale ~/.odbc.ini per un DSN specifico per l'utente o /etc/odbc.ini per un DSN di sistema.

[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

Dopo aver salvato il DSN, verificalo e testa la connessione.

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

Quando una stringa di connessione non specifica un valore, il driver legge queste impostazioni dal DSN:

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

Il driver legge anche le impostazioni di sola compatibilità TenantPrincipal e PoolMax. Usa i nomi dei parametri nella tabella delle impostazioni HC.

Disabilita la modalità HC

Puoi disabilitare l'avvio di nuove sessioni HC senza ridistribuire il driver. Usa il metodo che corrisponde a come hai abilitato la modalità HC:

Le impostazioni della stringa di connessione e del DSN hanno la precedenza rispetto al meccanismo di fallback basato sulle variabili d'ambiente. Questi cambiamenti riguardano solo le nuove connessioni. Le sessioni HC esistenti continuano fino a quando non vengono rilasciate.

Comprendere il comportamento del runtime di HC

• Validazione:SQLDriverConnect rifiuta valori HC booleani e valori interi positivi invalidi con SQLSTATE HY024. Rifiuta un valore LivyMode non valido e valori WorkspaceId, LakehouseId e IdempotencyKey non validi o troppo grandi con SQLSTATE HY000. Un valore di compatibilità TenantPrincipal sovradimensionato restituisce HY000anch'esso . Per la sola SQLConnectDSN, il driver registra i normali fallimenti di validazione HC e utilizza la modalità classica. I valori critici per la sicurezza di dimensioni eccessive continuano ancora a causare il fallimento della connessione.
• Dati sensibili: Il driver esclude o cancella IdempotencyKey altri campi sensibili dai log HC e dagli output diagnostici.
• Cancellazione: La cancellazione dell'estratto conto è cooperativa. Il lavoro sul server già in corso si conclude in modo pulito invece di essere terminato immediatamente.
• Interruttori automatici: Le modalità HC e classica utilizzano interruttori separati. Esaurire una modalità non influisce sull'altra.
• Database iniziale: Le connessioni HC non eseguono l'istruzione iniziale USE per il Database parametro. Esegui USE <database> dopo esserti connesso oppure usa nomi di tabella completamente qualificati.
• Diagnostica: Impostare LogLevel=DEBUG per registrare l'acquisizione HC, il polling, il rilascio e le decisioni di mappatura degli errori. Per una risoluzione mirata dei problemi, configura LIVY_HC_VERBOSE=1 per includere ulteriori diagnostiche HC HTTP ripulite.

Configurazione DSN

Su Linux, configura i nomi delle sorgenti dati (DSN) nei file INI invece che nel registro Windows.

Creare una DSN

Se ~/.odbc.ini esiste, aggiungi la nuova sezione DSN senza sostituire il file esistente. Copia il modello installato solo quando crei il file:

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

Modifica ~/.odbc.ini con i dettagli del tuo spazio di lavoro Fabric:

[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

Verifica il DSN

Elenca le DSN configurate e poi testa la connessione:

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

Il isql comando richiede gli strumenti a riga di comando unixODBC. L'opzione -k usa SQLDriverConnect, che permette al driver di elaborare gli attributi di connessione DSN.

Usa una DSN nelle applicazioni

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

Esempi di utilizzo

Testa una connessione con isql

Inizia una sessione SQL interattiva:

isql -k -v "DSN=FabricDSN;"

Esegui una singola query:

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

Usa -k per i DSN di Fabric in modo che isql si connetta tramite SQLDriverConnect invece che tramite SQLConnect.

Lavoro con grandi insiemi di risultati

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

Scopri schemi e tabelle

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

Mappatura del tipo di dati

Il driver esegue il mapping dei tipi di dati Spark SQL ai tipi SQL ODBC:

Differenze tra le piattaforme

Troubleshooting

Conducente non trovato

Problema: La connessione fallisce con [IM002] Data source name not found and no default driver specified.

Soluzioni:

1. Verifica la registrazione dei conducenti eseguendo odbcinst -q -d.
2. Verificare che /usr/lib/libmicrosoftfabricodbc.so esista.
3. Registra il conducente facendo eseguire sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Reinstalla il pacchetto eseguendo sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Driver non trovato dopo l'installazione di un archivio tar

Problema: il driver è registrato, ma la libreria condivisa non è presente sul percorso registrato.

Soluzioni:

1. Verificare che /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so esista.
2. Rieseguire sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Se hai usato un prefisso personalizzato, verifica che il percorso driver registrato utilizzi lo stesso prefisso.

DSN non trovato

Problema: La connessione fallisce con [IM002] Data source name not found.

Soluzioni:

1. Verifica la configurazione DSN eseguendo odbcinst -q -s.
2. Verifica che ~/.odbc.ini o /etc/odbc.ini contenga la sezione DSN.
3. Assicurati che il Driver valore corrisponda esattamente al nome del conducente registrato.

Errori di connessione

Problema: il driver non riesce a collegarsi a Fabric.

Soluzioni:

1. Verifica che l'ID del workspace e l'ID del lakehouse siano GUID validi.
2. Controlla l'autenticazione interfaccia della riga di comando di Azure eseguendo az account show.
3. Assicurati di avere i permessi necessari per lo spazio di lavoro Fabric.
4. Controlla la connettività di rete e le impostazioni del proxy.

Errori di autenticazione

Problema: l'autenticazione interfaccia della riga di comando di Azure fallisce.

Soluzioni:

1. Esegui az login per aggiornare le tue credenziali.
2. Imposta l'abbonamento corretto eseguendo az account set --subscription <subscription-id>.
3. Controlla il token eseguendo az account get-access-token --resource https://api.fabric.microsoft.com.
4. Assicurati che il tuo account abbia i permessi necessari per lo spazio di lavoro Fabric.

Errori nella libreria condivisa

Problema: Il conducente segnala error while loading shared libraries: libmicrosoftfabricodbc.so.

Soluzioni:

1. Reinstalla il pacchetto eseguendo sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Verificare che /usr/lib/libmicrosoftfabricodbc.so esista.
3. Esegui sudo ldconfig per aggiornare la cache della libreria condivisa.

Timeout delle query

Problema: le query si esauriscono su tabelle grandi.

Soluzioni:

1. Aggiungere LargeTableSupport=true alla stringa di connessione.
2. Regola PageSizeBytes in base alla dimensione del risultato.
3. Aggiungere EnableAsyncPrefetch=1 alla stringa di connessione.
4. Usa una LIMIT clausola per limitare la dimensione del risultato.

Abilitare la registrazione

Abilitare il logging dettagliato in un DSN:

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

In alternativa, aggiungi parametri di logging alla stringa di connessione:

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

Il driver supporta i seguenti livelli log:

• DEBUG: Include informazioni dettagliate di debug ed è il livello di log del driver più dettagliato.
• INFO: Include informazioni generali ed è il valore predefinito.
• WARN: Include solo avvertimenti.
• ERROR: Include solo gli errori.

Abilita il tracciamento unixODBC

Per la diagnostica delle chiamate ODBC di basso livello, aggiungere la seguente configurazione a /etc/odbcinst.ini:

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

Disattiva il tracciamento quando hai finito di risolvere i problemi per evitare sovraccarichi di prestazioni inutili.

Contenuti correlati

• Driver ODBC di Microsoft per Microsoft Fabric Data Engineering
• Runtime di Apache Spark in Fabric
• Runtime Fabric 1.3
• Informazioni sull'API Livy per ingegneria dei dati
• Microsoft JDBC Driver per Microsoft Fabric Data Engineering
• unixODBC