Driver Microsoft ODBC para Microsoft Fabric Data Engineering no Linux (Prévia)

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 Microsoft Entra ID: Múltiplos fluxos de autenticação, incluindo CLI do Azure, credenciais de clientes, baseada em certificados e autenticação de 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.
• Suporte a tabelas grandes: Tratamento otimizado para conjuntos de resultados grandes com tamanhos de página configuráveis.
• Prefeição assíncrona: carregamento de dados em segundo plano para melhorar o desempenho.
• Suporte a proxy: Configuração de proxy HTTP para ambientes empresariais.
• Suporte a multi-esquema para casa de lago: Conecte-se a um esquema específico dentro de uma casa de lago.

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 unixodbc pacotes e.unixodbc-dev
• Acesso Fabric: Acesso a um espaço de trabalho 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

O driver Microsoft ODBC para Microsoft Fabric Data Engineering versão 1.0.0 está disponível em prévia pública.

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

Para instalar o driver:

1. Extrair ms-sparksql-odbc-linux-1.0.0.zip.

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

3. Instale o pacote Debian:

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

O pacote instala os seguintes arquivos:

Driver de registro manual

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

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 AuthFlow parâmetro na cadeia de conexão ou DSN.

Métodos de autenticação

Autenticação da CLI do Azure

Use autenticação CLI do Azure para desenvolvimento e aplicações interativas.

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

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ção de DSN

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

Criar um DSN

Copie o modelo instalado:

cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template ~/.odbc.ini

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 -v FabricDSN

O isql comando requer as ferramentas de linha de comando unixODBC.

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 -v FabricDSN

Execute uma única consulta:

echo "SELECT 1 AS test" | isql -v FabricDSN -b

Trabalho 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-1.0.0-Linux.deb.

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 isso ~/.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 do CLI do Azure executando az account showo arquivo .
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-1.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: Consultas acabam em tabelas grandes.

Soluções:

1. Adicione LargeTableSupport=true à cadeia de conexão.
2. Ajuste PageSizeBytes pelo 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:

• TRACE: Inclui todas as chamadas de API.
• DEBUG: Inclui informações detalhadas de depuração.
• 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