Controlador Microsoft ODBC para Microsoft Fabric Data Engineering en Linux

ODBC (conectividad abierta de bases de datos) es un estándar ampliamente adoptado que permite a las aplicaciones cliente conectarse y trabajar con datos de bases de datos y plataformas de macrodatos.

El controlador ODBC de Microsoft para Fabric Data Engineering te permite conectar, consultar y gestionar cargas de trabajo de Spark en Fabric con la fiabilidad y simplicidad del estándar ODBC. Construido sobre las APIs Livy de Fabric, el controlador proporciona conectividad Spark SQL segura y flexible para tus aplicaciones compatibles con C/C++, .NET, Python y otras compatibles con ODBC en Linux.

Características clave

• Compatible con ODBC 3.x: Implementación completa de la especificación ODBC 3.x.
• Autenticación Microsoft Entra ID: Múltiples flujos de autenticación, incluyendo CLI de Azure, credenciales de cliente, autenticación basada en certificados y autenticación de token de acceso.
• Soporte para consultas SQL de Spark: Ejecución directa de sentencias SQL de Spark.
• Soporte integral de tipos de datos: Soporte para todos los tipos de datos SQL de Spark, incluyendo tipos complejos (ARRAY, MAP, y STRUCT).
• Reutilización de sesión: Gestión de sesiones integrada para mejorar el rendimiento.
• Modo de alta concurrencia: Opta por sesiones Livy compartidas y cálidas en el lado del servidor para reducir la latencia de inicio de conexión y la expansión del clúster Spark.
• Soporte para tablas grandes: Manejo optimizado para grandes conjuntos de resultados con tamaños de página configurables.
• Prelectura asincrónica: Carga de datos en segundo plano para mejorar el rendimiento.
• Soporte de proxy: Configuración de proxy HTTP para entornos empresariales.
• Compatibilidad con varios esquemas en lakehouse: Conectar a un esquema específico dentro de un lakehouse.

Prerequisites

Antes de usar el controlador ODBC de Microsoft para Microsoft Fabric Data Engineering en Linux, asegúrate de cumplir con los siguientes requisitos previos:

• Sistema operativo: Ubuntu 22.04 o posterior, Debian 11 o posterior, o Red Hat Enterprise Linux (RHEL) 8 o posterior en x86-64.
• unixODBC: El gestor de controladores ODBC para Linux. Instala los paquetes unixodbc y unixodbc-dev.
• libcurl: La dependencia en tiempo de ejecución HTTP, como libcurl4 o el paquete equivalente para tu distribución.
• OpenSSL: La dependencia en tiempo de ejecución de TLS y criptografía, como openssl y libssl3 /o paquetes equivalentes.
• Acceso a Fabric: Acceso a un espacio de trabajo Fabric.
• Credenciales Microsoft Entra ID: Credenciales adecuadas para la autenticación.
• IDs de espacio de trabajo y casa del lago: Los identificadores GUID para tu espacio de trabajo Fabric y la casa del lago.
• CLI de Azure (opcional): Obligatorio cuando usas autenticación con CLI de Azure.

Descargar e instalar en Linux

• Descargar el controlador Microsoft ODBC para Microsoft Fabric Data Engineering en Linux (tar)

Para instalar el controlador, haga lo siguiente:

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

2. Abre un terminal en el directorio extraído.

3. Instala el paquete Debian:

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

El paquete instala los siguientes archivos:

Instala un paquete RPM

En RHEL, Fedora o CentOS, instala el paquete RPM desde el archivo de controladores extraído:

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

Alternativamente, usa rpm:

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

Verifica que las RPM registraron al conductor:

odbcinst -q -d | grep "Microsoft"

Para desinstalar el paquete RPM, ejecuta:

sudo dnf remove microsoft-fabric-odbc-driver

Instalar un archivo tar

Para distribuciones sin soporte para Debian o paquetes RPM, o para una ubicación de instalación personalizada, extrae el .tar.gz paquete y ejecuta su script de instalación:

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

El script de instalación admite estas opciones:

Para verificar la instalación predeterminada de tarball, ejecuta:

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

Para desinstalarlo, ejecuta sudo ./install.sh --uninstall desde el directorio de paquetes extraídos.

Registrar controlador manualmente

El paquete registra automáticamente el controlador con unixODBC. Para registrar el controlador manualmente, ejecuta:

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

Comprobación de la instalación

Verifica que el controlador esté registrado y que la biblioteca esté instalada:

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

El odbcinst comando debería indicar [Microsoft ODBC Driver for Microsoft Fabric Data Engineering].

Desinstala el controlador

Para desinstalar el controlador, ejecuta el siguiente comando:

sudo dpkg -r microsoft-fabric-odbc-driver

Este comando elimina los archivos del controlador y desregistra el controlador de unixODBC.

Ejemplo de inicio rápido

Los siguientes ejemplos se conectan a Fabric y ejecutan una consulta SQL de Spark. Cumple los requisitos previos e instala el controlador antes de ejecutar un ejemplo.

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

Ejemplo de 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;
}

Construye y ejecuta el ejemplo:

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

ejemplo 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 de la cadena de conexión

Cadena de conexión básica

Utiliza el siguiente formato de cadena de conexión:

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

Componentes de cadena de conexión

Ejemplos de cadena de conexión

Conexión básica

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

Conexión con opciones de rendimiento

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

Conexión con la tala

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

Conexión con el modo de alta concurrencia

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

Para una guía completa de configuración, véase modo de alta concurrencia (HC).

Authentication

El controlador Microsoft ODBC para Microsoft Fabric Data Engineering soporta múltiples métodos de autenticación a través de Microsoft Entra ID. Configura la autenticación usando el AuthFlow parámetro de la cadena de conexión o DSN.

Métodos de autenticación

Autenticación de la CLI de Azure

Utiliza la autenticación de CLI de Azure para aplicaciones de desarrollo e interactivas.

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 conectarte, verifica que la CLI de Azure esté instalada y inicia sesión:

az --version
az login

Para instalar CLI de Azure en Debian o Ubuntu, utiliza el gestor de paquetes:

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

Autenticación de credenciales del cliente

Utiliza la autenticación de credenciales del cliente para servicios automatizados y trabajos en 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};"
)

Introduzca los siguientes parámetros:

• TenantId: El ID del tenant de Microsoft Entra.
• ClientId: el identificador de la aplicación (cliente).
• ClientSecret: El secreto del cliente.

Almacena secretos en un almacén secreto seguro o en variables de entorno. No almacenes secretos en cadenas de conexión en texto plano ni en archivos INI.

Autenticación basada en certificados

Utiliza autenticación basada en certificados para aplicaciones empresariales que requieren credenciales 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>;"
)

Introduzca los siguientes parámetros:

• TenantId: El ID del tenant de Microsoft Entra.
• ClientId: el identificador de la aplicación (cliente).
• CertificatePath: La ruta hacia el archivo de certificados PFX o PKCS12.
• CertificatePassword: La contraseña del certificado.

Autenticación de token de acceso

Utiliza la autenticación de token de acceso cuando tu aplicación adquiera un token a través de otro 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};"
)

Autenticación mediante token de archivo

Utiliza autenticación por token de archivo en entornos contenedores y pipelines automatizados donde otro proceso escribe un token portador en el archivo de token conocido del controlador:

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

Para consultar los alias de propiedades entre controladores compatibles, véase Alias de propiedades entre controladores.

Parámetros de configuración

Parámetros necesarios

Incluye estos parámetros en cada cadena de conexión:

Parámetros opcionales

Configuración de conexión

Configuración de rendimiento

Configuración del registro

Configuración del proxy

Configuraciones de alta concurrencia (HC)

Utiliza estos parámetros para habilitar y configurar el modo de alta concurrencia (HC). El modo HC es opcional. Si no configuras LivyMode o UseHighConcurrency, el controlador utiliza la ruta clásica de una sola sesión. Para orientación y ejemplos, véase Modo de alta concurrencia (HC).

Precedencia de modos y validación

• LivyMode tiene prioridad sobre UseHighConcurrency cuando configuras ambos parámetros.
• Los valores de los parámetros no distinguen entre mayúsculas y minúsculas.
• UseHighConcurrency acepta true, 1, yes, o on para activar el modo HC. Acepta false, 0, no, o off para desactivar el modo HC.
• Para otros valores no vacíos, SQLDriverConnect devuelve un error. Solo SQLConnect DSN registra el fallo de validación y utiliza la ruta clásica.

Configuración de compatibilidad

El controlador acepta TenantPrincipal y PoolMax, incluidos sus valores alternativos mediante variables de entorno, para mantener la compatibilidad con configuraciones anteriores de HC. El controlador analiza y valida estos valores, pero estos no afectan a la coincidencia de sesiones de HC ni a la capacidad del pool en tiempo de ejecución. No dependas de ellos para aislamiento de inquilinos ni límites de conexión.

Alternativas de variables de entorno

El controlador utiliza las siguientes variables de entorno solo cuando el parámetro DSN o cadena de conexión correspondiente no está activado:

Para FABRIC_ODBC_USE_HC, la habilitación solo para entorno reconoce true, 1 o yes (sin distinguir entre mayúsculas y minúsculas). Otros valores dejan el modo HC desactivado. Los on alias y off solo se aplican a valores DSN y cadena de conexión.

Modo de alta concurrencia (HC)

El modo de alta concurrencia (HC) permite que las conexiones ODBC al mismo espacio de trabajo y lakehouse se conecten a sesiones Livy Spark compartidas y cálidas en el lado del servidor, en lugar de provisionar un clúster separado para cada conexión. Úsalo para cargas de trabajo como paneles de BI, kernels de cuadernos y ramificaciones de ETL que abren muchas conexiones de corta duración y pueden compartir la capacidad de Spark administrada por el servidor.

El modo HC es opcional. Si no configuras una configuración HC, el controlador usa la ruta clásica de sesión única.

Elegir un modo de conexión

Usa el modo HC cuando:

• Tu carga de trabajo abre muchas conexiones ODBC de corta duración, como paneles de BI, núcleos de cuadernos o procesos ETL distribuidos en paralelo.
• Las conexiones se dirigen al mismo espacio de trabajo y al mismo lago y pueden compartir una sesión de Spark gestionada por el servidor.
• Reducir la latencia de arranque en frío por conexión es importante.

Usa el modo clásico cuando:

• Cada conexión requiere una sesión Spark aislada debido a diferentes configuraciones o al estricto aislamiento de recursos.
• El endpoint de Fabric Livy para el espacio de trabajo objetivo y la casa del lago no soporta el modo HC.

Activar el modo de alta concurrencia

Añade un parámetro de modo de alta concurrencia al DSN o a la cadena de conexión.

Recomendado: Establecer LivyMode

Utilizar LivyMode para seleccionar explícitamente el modo de adquisición de sesión:

LivyMode=HighConcurrency

Los valores admitidos son Classic, HighConcurrencyy Auto. Los valores no distinguen mayúsculas de minúsculas. Auto Actualmente selecciona el modo clásico.

Alternativa: Set UseHighConcurrency

Utiliza la configuración booleana para compatibilidad con configuraciones existentes:

UseHighConcurrency=true

Para activar el modo de alta concurrencia, use true, 1, yes, o on. Para desactivarlo, usa false, 0, no, o off. Los valores no distinguen mayúsculas de minúsculas. SQLDriverConnect rechaza otros valores no vacíos con SQLSTATE HY024. Solo SQLConnect DSN registra el fallo de validación y utiliza el modo clásico.

También puedes activar el modo de alta concurrencia para la shell actual usando variables de entorno:

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 requeridos en modo HC

La activación de HC requiere los siguientes identificadores válidos:

Incluye SessionTag porque influye en la emparejación del servidor para las sesiones calientes.

Emparejamiento de sesiones

El modo HC no garantiza que todas las conexiones reutilicen una sesión existente. Para cada solicitud de adquisición de sesión, el controlador envía:

• El valor SessionTag.
• La configuración efectiva de Spark, incluida la configuración de conf.* y EnvironmentId.

El servicio Fabric Livy evalúa estos valores y decide si adjunta la conexión a una sesión caliente o crea una nueva. Para mejorar la reutilización de sesiones, utiliza valores consistentes entre conexiones que estén destinadas a compartir la capacidad de Spark gestionada por el servidor.

Ejemplos de cadena de conexión

Conexión HC mínima con autenticación de CLI de Azure:

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

Conexión HC con tiempos de espera configurados:

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

Conexión de HC con un entorno y anulaciones de la configuración de 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"
)

Configurar el modo HC en una DSN de Linux

En lugar de repetir los ajustes HC en cada cadena de conexión, guárdalos ~/.odbc.ini para un DSN específico de usuario o /etc/odbc.ini para un DSN a nivel 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

Después de guardar el DSN, verifícalo y prueba la conexión.

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

Cuando una cadena de conexión no especifica un valor, el controlador lee estos ajustes desde la DSN:

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

El controlador también lee los ajustes de solo compatibilidad TenantPrincipal y PoolMax. Usa los nombres de parámetros en la tabla de configuración de HC.

Desactivar el modo HC

Puedes desactivar nuevas adquisiciones de sesión HC sin tener que volver a desplegar el controlador. Usa el método que corresponde a cómo activaste el modo HC:

La cadena de conexión y la configuración de DSN tienen prioridad sobre la alternativa basada en variables de entorno. Estos cambios afectan solo a nuevas conexiones. Las sesiones de HC existentes siguen activas hasta que se liberan.

Comprender el comportamiento del runtime de HC

• Validación:SQLDriverConnect rechaza valores HC booleanos y enteros positivos inválidos con SQLSTATE HY024. Rechaza un LivyMode no válido y valores de WorkspaceId, LakehouseId y IdempotencyKey no válidos o demasiado grandes con SQLSTATE HY000. Un valor de compatibilidad TenantPrincipal sobredimensionado también devuelve HY000. Para SQLConnect solo con DSN, el controlador registra errores habituales de validación de HC y utiliza el modo clásico. Los valores confidenciales demasiado grandes siguen haciendo fallar la conexión.
• Datos sensibles: El controlador excluye o elimina IdempotencyKey otros campos sensibles de los registros HC y de la salida de diagnóstico.
• Cancelación: La cancelación del extracto es cooperativa. El trabajo del servidor ya en curso finaliza correctamente en lugar de interrumpirse de inmediato.
• Interruptores automáticos: Los modos HC y clásico usan interruptores automáticos separados. Agotar un modo no afecta al otro.
• Base de datos inicial: Las conexiones HC no ejecutan la instrucción inicial USE del Database parámetro. Ejecuta USE <database> después de conectar o usa nombres de tablas totalmente cualificados.
• Diagnóstico: Configura LogLevel=DEBUG para registrar las decisiones de adquisición HC, sondeo, liberación y mapeo de errores. Para una solución de problemas específica, establece LIVY_HC_VERBOSE=1 para que incluya diagnósticos HTTP de HC adicionales depurados.

Configuración de DSN

En Linux, configura los nombres de las fuentes de datos (DSNs) en archivos INI en lugar del registro de Windows.

Creación de un DSN

Si ~/.odbc.ini existe, añade la nueva sección DSN sin reemplazar el archivo existente. Copia la plantilla instalada solo cuando crees el archivo:

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

Edita ~/.odbc.ini con los detalles de tu área de trabajo de 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 la DSN

Enumera las DSN configuradas y luego prueba la conexión:

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

El isql comando requiere las herramientas de línea de comandos unixODBC. La -k opción utiliza SQLDriverConnect, que permite al controlador procesar atributos de conexión DSN.

Utilizar una DSN en aplicaciones

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

Ejemplos de uso

Prueba una conexión con isql

Inicia una sesión SQL interactiva:

isql -k -v "DSN=FabricDSN;"

Ejecuta una sola consulta:

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

Usa -k para los DSN de Fabric para que isql se conecte a través de SQLDriverConnect en lugar de SQLConnect.

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

Descubre esquemas y tablas

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

Asignación de tipos de datos

El controlador asigna los tipos de datos de Spark SQL a tipos de SQL ODBC:

Diferencias entre plataformas

Troubleshooting

Conductor no encontrado

Problema: La conexión falla con [IM002] Data source name not found and no default driver specified.

Soluciones:

1. Verifica el registro de los conductores ejecutando odbcinst -q -d.
2. Compruebe que /usr/lib/libmicrosoftfabricodbc.so existe.
3. Registra al conductor ejecutando sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template.
4. Reinstala el paquete ejecutando sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.

No se encuentra el controlador tras una instalación desde un archivo tar

Problema: El controlador está registrado, pero la biblioteca compartida no está presente en la ruta registrada.

Soluciones:

1. Compruebe que /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so existe.
2. Vuelva a ejecutar sudo ./install.sh --prefix=/opt/microsoft/fabricodbc.
3. Si has usado un prefijo personalizado, verifica que la ruta registrada del controlador use el mismo prefijo.

No se encontró DSN

Problema: La conexión falla con [IM002] Data source name not found.

Soluciones:

1. Verifica la configuración del DSN ejecutando odbcinst -q -s.
2. Verifica que ~/.odbc.ini o /etc/odbc.ini contenga la sección DSN.
3. Asegúrate de que el Driver valor coincida exactamente con el nombre del conductor registrado.

Fallos de conexión

Problema: El controlador no puede conectarse a Fabric.

Soluciones:

1. Verifica que el ID del espacio de trabajo y el ID del lakehouse sean identificadores GUID válidos.
2. Comprueba la autenticación de CLI de Azure ejecutando az account show.
3. Asegúrate de tener los permisos necesarios para el espacio de trabajo de Fabric.
4. Comprueba la conectividad de red y la configuración del proxy.

Errores de autenticación

Problema: La autenticación de CLI de Azure falla.

Soluciones:

1. Ejecuta az login para actualizar tus credenciales.
2. Configura la suscripción correcta ejecutando az account set --subscription <subscription-id>.
3. Comprueba el token ejecutando az account get-access-token --resource https://api.fabric.microsoft.com.
4. Asegúrate de que tu cuenta tenga los permisos necesarios para el espacio de trabajo de Fabric.

Errores de biblioteca compartida

Problema: El conductor informa error while loading shared libraries: libmicrosoftfabricodbc.so.

Soluciones:

1. Reinstala el paquete ejecutando sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb.
2. Compruebe que /usr/lib/libmicrosoftfabricodbc.so existe.
3. Ejecuta sudo ldconfig para actualizar la caché compartida de la biblioteca.

Tiempos de espera de las consultas

Problema: Las consultas superan el tiempo de espera en tablas de gran tamaño.

Soluciones:

1. Agregue LargeTableSupport=true a la cadena de conexión.
2. Ajusta PageSizeBytes según el tamaño del resultado.
3. Agregue EnableAsyncPrefetch=1 a la cadena de conexión.
4. Utiliza una LIMIT cláusula para restringir el tamaño del resultado.

Habilitar registro

Habilitar el registro detallado en una DSN:

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

Alternativamente, añadir parámetros de registro a la cadena de conexión:

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

El controlador soporta los siguientes niveles logarítmicos:

• DEBUG: Incluye información detallada de depuración y es el nivel de registro del controlador más detallado.
• INFO: Incluye información general y es el valor predeterminado.
• WARN: Incluye solo advertencias.
• ERROR: Incluye solo errores.

Activar el trazado de unixODBC

Para diagnósticos de llamadas ODBC de bajo nivel, añade la siguiente configuración a /etc/odbcinst.ini:

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

Desactiva el rastreo cuando termines de solucionar problemas para evitar sobrecarga de rendimiento innecesaria.

Contenido relacionado

• Controlador ODBC de Microsoft para Microsoft Fabric Data Engineering
• Entornos de ejecución de Apache Spark en Fabric
• Fabric Runtime 1.3
• ¿Qué es Livy API para ingeniería de datos?
• Controlador JDBC de Microsoft para la ingeniería de datos de Microsoft Fabric
• unixODBC