Driver ODBC da Microsoft para Engenharia de Dados no Microsoft Fabric no Linux

O ODBC (Open Database Connectivity) é um padrão amplamente adotado que permite que os aplicativos cliente se conectem e trabalhem com dados de bancos de dados e plataformas de Big Data.

O driver Microsoft ODBC para Engenharia de Dados Fabric permite conectar, consultar e gerenciar cargas de trabalho Spark no Fabric com a confiabilidade e simplicidade do padrão ODBC. Construído sobre as APIs Livy da Fabric, o driver oferece conectividade Spark SQL segura e flexível para suas aplicações compatíveis com C/C++, .NET, Python e outras compatíveis com ODBC no Linux.

Características principais

• Compatível com ODBC 3.x: Implementação completa da especificação ODBC 3.x.
• Autenticação do Microsoft Entra ID: vários fluxos de autenticação, incluindo CLI do Azure, credenciais de cliente, autenticação baseada em certificado e autenticação por token de acesso.
• Suporte a consultas SQL do Spark: Execução direta das instruções SQL do Spark.
• Suporte abrangente de tipos de dados: Suporte para todos os tipos de dados SQL do Spark, incluindo tipos complexos (ARRAY, MAP, e STRUCT).
• Reutilização de sessões: Gerenciamento de sessões integrado para melhorar o desempenho.
• Modo de alta concorrência: Opte por sessões compartilhadas e quentes do lado do servidor do Livy para reduzir a latência de início da conexão e a expansão do cluster Spark.
• Suporte a tabelas grandes: Tratamento otimizado para conjuntos de resultados grandes com tamanhos de página configuráveis.
• Pré-carregamento assíncrono: carregamento de dados em segundo plano para melhorar o desempenho.
• Suporte a proxy: Configuração de proxy HTTP para ambientes empresariais.
• Suporte a vários esquemas no lakehouse: Conecte-se a um esquema específico em um lakehouse.

Pré-requisitos

Antes de usar o driver Microsoft ODBC para Microsoft Fabric Data Engineering no Linux, certifique-se de cumprir os seguintes pré-requisitos:

• Sistema operacional: Ubuntu 22.04 ou posterior, Debian 11 ou posterior, ou Red Hat Enterprise Linux (RHEL) 8 ou posterior em x86-64.
• unixODBC: O gerenciador de drivers ODBC para Linux. Instale os pacotes unixodbc e unixodbc-dev.
• libcurl: a dependência de tempo de execução HTTP, como libcurl4 ou o pacote equivalente para sua distribuição.
• OpenSSL: A dependência de tempo de execução de TLS e criptografia, como openssl e libssl3 ou pacotes equivalentes.
• Acesso ao Fabric: Acesso a um espaço de trabalho do Fabric.
• Credenciais do Microsoft Entra ID: Credenciais apropriadas para autenticação.
• IDs de espaço de trabalho e casa do lago: Os identificadores GUID para seu espaço de trabalho Fabric e casa do lago.
• CLI do Azure (opcional): Exigido quando você usa autenticação CLI do Azure.

Baixe e instale no Linux

• Baixe o driver Microsoft ODBC para Microsoft Fabric Data Engineering no Linux (tar)

Para instalar o driver:

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

2. Abra um terminal no diretório extraído.

3. Instale o pacote Debian:

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

O pacote instala os seguintes arquivos:

Instale um pacote RPM

No RHEL, Fedora ou CentOS, instale o pacote RPM a partir do arquivo de drivers extraídos:

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

Alternativamente, use rpm:

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

Verifique se o RPM registrou o driver:

odbcinst -q -d | grep "Microsoft"

Para desinstalar o pacote RPM, execute:

sudo dnf remove microsoft-fabric-odbc-driver

Instale um arquivo tar

Para distribuições sem suporte a Debian ou pacotes RPM, ou para um local de instalação personalizado, extraia o .tar.gz pacote e execute seu script de instalação:

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

O script de instalação suporta estas opções:

Para verificar a instalação padrão do tarball, execute:

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

Para desinstalá-lo, execute sudo ./install.sh --uninstall a partir do diretório de pacotes extraídos.

Registrar driver manualmente

O pacote registra automaticamente o driver com unixODBC. Para registrar o driver manualmente, execute:

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

Verificar a instalação

Verifique se o driver está registrado e que a biblioteca está instalada:

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

O odbcinst comando deve listar [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Desinstale o driver

Para desinstalar o driver, execute o seguinte comando:

sudo dpkg -r microsoft-fabric-odbc-driver

Esse comando remove os arquivos do driver e desregistra o driver do unixODBC.

Exemplo de início rápido

Os exemplos a seguir conectam-se ao Fabric e executam uma consulta SQL do Spark. Complete os pré-requisitos e instale o driver antes de rodar um exemplo.

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

Exemplo em 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;
}

Construa e execute o exemplo:

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

Exemplo de .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 da cadeia de conexão

Cadeia de conexão básica

Use o seguinte formato de cadeia de conexão:

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

Componentes da cadeia de conexão

Exemplos de cadeias de conexão

Conexão básica

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

Conexão com opções de desempenho

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

Conexão com a exploração de madeira

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

Conexão com modo de alta concorrência

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

Para orientações completas de configuração, veja modo de alta concorrência (HC).

Authentication

O Microsoft ODBC Driver for Microsoft Fabric Data Engineering suporta múltiplos métodos de autenticação por meio do Microsoft Entra ID. Configure a autenticação usando o parâmetro AuthFlow na cadeia de conexão ou no DSN.

Métodos de autenticação

Autenticação da CLI do Azure

Use a autenticação da CLI do Azure para o desenvolvimento e aplicativos interativos.

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)

Antes de se conectar, verifique se a CLI do Azure está instalada e faça login:

az --version
az login

Para instalar o CLI do Azure no Debian ou Ubuntu, use o gerenciador de pacotes:

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

Autenticação de credenciais do cliente

Use autenticação de credenciais de clientes para serviços automatizados e trabalhos em segundo plano.

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

Forneça os parâmetros a seguir:

• TenantId: O ID do tenant da Microsoft Entra.
• ClientId: A ID do aplicativo (cliente).
• ClientSecret: O segredo do cliente.

Armazene segredos em um armazenamento secreto seguro ou variáveis de ambiente. Não armazene segredos em cadeias de conexão em texto simples ou arquivos INI.

Autenticação baseada em certificado

Use autenticação baseada em certificado para aplicações empresariais que exigem credenciais de certificado.

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

Forneça os parâmetros a seguir:

• TenantId: O ID do tenant da Microsoft Entra.
• ClientId: A ID do aplicativo (cliente).
• CertificatePath: O caminho para o arquivo de certificados PFX ou PKCS12.
• CertificatePassword: A senha do certificado.

Autenticação de token de acesso

Use autenticação de token de acesso quando sua aplicação adquirir um token por outro mecanismo.

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

Autenticação de token de arquivo

Use a autenticação por token em arquivo em ambientes conteinerizados e pipelines automatizados, nos quais outro processo grava um token de portador no arquivo de token bem conhecido do driver:

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

Para aliases de propriedade cross-driver suportados, veja Aliases de propriedade cross-driver.

Parâmetros de configuração

Parâmetros necessários

Inclua estes parâmetros em cada cadeia de conexão:

Parâmetros opcionais

Configurações de conexão

Configurações de desempenho

Configurações de registro

Configurações de proxy

Configurações de alta concorrência (HC)

Use esses parâmetros para ativar e configurar o modo de alta concorrência (HC). O modo HC é opcional. Se você não definir LivyMode ou UseHighConcurrency, o driver usa o caminho clássico de sessão única. Para orientações e exemplos, veja Modo de alta concorrência (HC).

Precedência de modos e validação

• LivyMode Tem prioridade sobre UseHighConcurrency quando você define ambos os parâmetros.
• Os valores dos parâmetros não diferenciam maiúsculas de minúsculas.
• UseHighConcurrency aceita true, 1, yes, ou on para ativar o modo HC. Aceita false, 0, no, ou off para desativar o modo HC.
• Para outros valores não vazios, SQLDriverConnect retorna um erro. Somente o DSN SQLConnect registra a falha de validação e usa o caminho clássico.

Configurações de compatibilidade

O driver aceita TenantPrincipal e PoolMax, incluindo suas alternativas por variáveis de ambiente, para compatibilidade com configurações anteriores do HC. O driver analisa e valida esses valores, mas eles não afetam a correspondência de sessões HC ou a capacidade do pool de runtime. Não confie neles para isolamento de inquilinos ou limites de conexão.

Alternativas de variáveis ambientais

O driver usa as seguintes variáveis de ambiente apenas quando o parâmetro correspondente DSN ou string de conexão não está definido:

Para FABRIC_ODBC_USE_HC, a habilitação somente por ambiente reconhece true, 1 ou yes (sem diferenciar maiúsculas de minúsculas). Outros valores deixam o modo HC desativado. Os on aliases e off se aplicam apenas a valores DSN e de string de conexão.

Modo de alta concorrência (HC)

O modo de alta concorrência (HC) permite que conexões ODBC com o mesmo workspace e lakehouse se conectem a sessões Livy Spark compartilhadas e já ativas no servidor, em vez de provisionar um cluster separado para cada conexão. Use-o para cargas de trabalho, como painéis de BI, kernels de notebook e distribuição de ETL, que abrem muitas conexões de curta duração e podem compartilhar a capacidade do Spark gerenciada pelo servidor.

O modo HC é opcional. Se você não configurar uma configuração HC, o driver usa o caminho clássico de sessão única.

Escolher um modo de conexão

Use o modo HC quando:

• Sua carga de trabalho abre muitas conexões ODBC de curta duração, como painéis de BI, kernels de notebook ou processos ETL paralelos.
• As conexões têm como alvo o mesmo espaço de trabalho e o mesmo lakehouse e podem compartilhar uma sessão Spark gerenciada pelo servidor.
• Reduzir a latência de início a frio por conexão é importante.

Use o modo clássico quando:

• Cada conexão requer uma sessão Spark isolada devido a diferentes configurações do Spark ou isolamento rigoroso de recursos.
• O endpoint do Fabric Livy para o workspace de destino e o lakehouse não é compatível com o modo HC.

Ativar o modo de alta concorrência

Adicione um parâmetro de modo de alta concorrência ao DSN ou à cadeia de conexão.

Recomendado: Definir LivyMode

Use LivyMode para selecionar explicitamente o modo de aquisição de sessão:

LivyMode=HighConcurrency

Os valores com suporte são Classic, HighConcurrencye Auto. Os valores não diferenciam maiúsculas de minúsculas. Auto Atualmente seleciona o modo clássico.

Alternativa: Set UseHighConcurrency

Use a configuração booleana para compatibilidade com configurações existentes:

UseHighConcurrency=true

Para ativar o modo de alta concorrência, use true, 1, yes, ou on. Para desativá-lo, use false, 0, no, ou off. Os valores não diferenciam maiúsculas de minúsculas. SQLDriverConnect rejeita outros valores não vazios com SQLSTATE HY024. Somente DSN SQLConnect registra em log a falha de validação e usa o modo clássico.

Você também pode ativar o modo de alta concorrência para a shell atual usando variáveis de ambiente:

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

Parâmetros necessários no modo HC

A ativação HC requer os seguintes identificadores válidos:

Inclua SessionTag porque isso influencia o matching do lado do servidor para sessões quentes.

Associação de sessões

O modo HC não garante que toda conexão reutilize uma sessão existente. Para cada solicitação de aquisição de sessão, o driver envia:

• O SessionTag valor.
• A configuração efetiva do Spark, incluindo as configurações de conf.* e EnvironmentId.

O serviço Fabric Livy avalia esses valores e decide se deve anexar a conexão a uma sessão quente ou criar uma nova sessão. Para melhorar o reuso das sessões, use valores consistentes entre conexões que tenham a intenção de compartilhar a capacidade do Spark gerenciado pelo servidor.

Exemplos de cadeias de conexão

Conexão HC mínima com autenticação da CLI do Azure:

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

Conexão HC com tempos limite ajustados:

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

Conexão HC com um ambiente e substituições de configuração do 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 com 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"
)

Configurar o modo HC em um DSN Linux

Em vez de repetir as configurações de HC em cada cadeia de conexão, armazene-as em ~/.odbc.ini para um DSN específico do usuário ou em /etc/odbc.ini para um DSN de 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

Depois de salvar o DSN, verifique e teste a conexão.

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

Quando uma cadeia de conexão não especifica um valor, o driver lê estas configurações da DSN:

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

O driver também lê apenas TenantPrincipal compatibilidade e PoolMax configurações. Use os nomes dos parâmetros na tabela de configurações do HC.

Desativar o modo HC

Você pode desativar novas aquisições de sessão HC sem precisar reimplantar o driver. Use o método que corresponde a como você ativou o modo HC:

As configurações de conexão string e DSN têm precedência sobre o fallback da variável ambiental. Essas mudanças afetam apenas novas conexões. As sessões de HC existentes continuam até serem encerradas.

Entenda o comportamento em tempo de execução do HC

• Validação:SQLDriverConnect rejeita valores booleanos HC e inteiros positivos inválidos com SQLSTATE HY024. Rejeita um valor inválido de LivyMode e valores inválidos ou grandes demais de WorkspaceId, LakehouseId e IdempotencyKey com SQLSTATE HY000. Um valor de compatibilidade TenantPrincipal sobredimensionado também retorna HY000. Para SQLConnect somente DSN, o driver registra falhas comuns na validação de HC e usa o modo clássico. Valores sensíveis relacionados à segurança excessivamente grandes ainda causam falha na conexão.
• Dados sensíveis: O driver exclui ou remove IdempotencyKey outros campos sensíveis dos logs HC e da saída de diagnóstico.
• Cancelamento: O cancelamento da instrução ocorre de forma cooperativa. O processamento no servidor já em andamento é finalizado de forma limpa, em vez de ser encerrado imediatamente.
• Disjuntores: Os modos HC e clássico usam disjuntores separados. Esgotar um modo não afeta o outro.
• Banco de dados inicial: As conexões HC não executam a instrução USE inicial para o parâmetro Database. Execute USE <database> após conectar ou use nomes de tabelas totalmente qualificados.
• Diagnóstico: Defina LogLevel=DEBUG para registrar a aquisição de HC, a sondagem, a liberação e as decisões de mapeamento de erros. Para solução de problemas focada, configure LIVY_HC_VERBOSE=1 para incluir diagnósticos HC HTTP adicionais e eliminados.

Configuração de DSN

No Linux, configure nomes de fontes de dados (DSNs) em arquivos INI em vez do registro do Windows.

Criar um DSN

Se ~/.odbc.ini existir, adicione a nova seção DSN sem substituir o arquivo existente. Copie o template instalado apenas quando criar o arquivo:

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

Edite ~/.odbc.ini com os detalhes do seu espaço de trabalho 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

Verifique a DSN

Liste as DSNs configuradas e então teste a conexão:

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

O isql comando requer as ferramentas de linha de comando unixODBC. A opção -k usa SQLDriverConnect, que permite ao driver processar atributos de conexão do DSN.

Use uma DSN em aplicações

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

Exemplos de uso

Teste uma conexão com o isql

Inicie uma sessão interativa de SQL:

isql -k -v "DSN=FabricDSN;"

Execute uma única consulta:

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

Use -k para DSNs do Fabric para que isql se conecte através de SQLDriverConnect em vez de SQLConnect.

Trabalhar com grandes conjuntos de resultados

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

Descubra esquemas e tabelas

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

Mapeamento de tipo de dados

O driver mapeia tipos de dados SQL do Spark para tipos SQL ODBC:

Diferenças de plataforma

Troubleshooting

Motorista não encontrado

Problema: A conexão falha com [IM002] Data source name not found and no default driver specified.

Soluções:

1. Verifique o registro do motorista executando odbcinst -q -d.
2. Verifique se existe /usr/lib/libmicrosoftfabricodbc.so .
3. Registre o motorista executando sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Reinstale o pacote executando sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

Driver não encontrado após uma instalação via tarball

Problema: O driver está registrado, mas a biblioteca compartilhada não está presente no caminho registrado.

Soluções:

1. Verifique se existe /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so .
2. Executar novamente sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Se você usou um prefixo personalizado, verifique se o caminho do driver registrado usa o mesmo prefixo.

DSN não encontrado

Problema: A conexão falha com [IM002] Data source name not found.

Soluções:

1. Verifique a configuração da DSN executando odbcinst -q -s.
2. Verifique se ~/.odbc.ini ou /etc/odbc.ini contém a seção DSN.
3. Certifique-se de que o Driver valor corresponda exatamente ao nome do motorista registrado.

Falhas na conexão

Problema: O driver não consegue se conectar ao Fabric.

Soluções:

1. Verifique se o ID do workspace e o ID do lakehouse são GUIDs válidos.
2. Verifique a autenticação da CLI do Azure executando az account show.
3. Certifique-se de ter as permissões necessárias para o espaço de trabalho do Fabric.
4. Verifique a conectividade de rede e as configurações do proxy.

Erros de autenticação

Problema: A autenticação do CLI do Azure falha.

Soluções:

1. Corra az login para atualizar suas credenciais.
2. Defina a assinatura correta executando az account set --subscription <subscription-id>.
3. Verifique o token executando az account get-access-token --resource https://api.fabric.microsoft.com.
4. Certifique-se de que sua conta tenha as permissões necessárias para o espaço de trabalho do Fabric.

Erros de biblioteca compartilhada

Problema: O motorista relata error while loading shared libraries: libmicrosoftfabricodbc.so.

Soluções:

1. Reinstale o pacote executando sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Verifique se existe /usr/lib/libmicrosoftfabricodbc.so .
3. Execute sudo ldconfig para atualizar o cache da biblioteca compartilhada.

Tempos limite de consulta

Problema: As consultas expiram em tabelas grandes.

Soluções:

1. Adicione LargeTableSupport=true à cadeia de conexão.
2. Ajuste PageSizeBytes de acordo com o tamanho do resultado.
3. Adicione EnableAsyncPrefetch=1 à cadeia de conexão.
4. Use uma LIMIT cláusula para restringir o tamanho do resultado.

Habilitar registro de log

Ative o registro detalhado em uma DSN:

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

Alternativamente, adicione parâmetros de registro à cadeia de conexão:

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

O driver suporta os seguintes níveis logarítmicos:

• DEBUG: Inclui informações detalhadas de depuração e é o nível de log de driver mais extenso.
• INFO: Inclui informações gerais e é o padrão.
• WARN: Inclui apenas avisos.
• ERROR: Inclui apenas erros.

Ativar o rastreamento unixODBC

Para diagnósticos de chamadas ODBC de baixo nível, adicione a seguinte configuração a /etc/odbcinst.ini:

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

Desative o rastreamento quando terminar de solucionar o problema para evitar sobrecarga desnecessária de desempenho.

Conteúdo relacionado

• Driver ODBC da Microsoft para Engenharia de Dados do Microsoft Fabric
• Runtimes do Apache Spark no Fabric
• Fabric Runtime 1.3
• O que é a API livy para engenharia de dados
• Microsoft JDBC Driver para Microsoft Fabric Data Engineering
• unixODBC