Controlador ODBC de código abierto de Databricks

Importante

El controlador Databricks OSS ODBC, versión 0.5.0, está en Beta. Para información sobre el controlador 2.x de la versión generalmente disponible, consulte la documentación del controlador ODBC de Databricks.

Para informar de un problema o solicitar una característica mientras el controlador se encuentra en fase beta, ponte en contacto con tu equipo de cuentas de Databricks.

El controlador ODBC de código abierto de Databricks es un controlador ODBC 3.8 para Databricks SQL y los almacenes de datos Lakehouse//RT. Está diseñado para ser un reemplazo compatible del controlador ODBC versión 2.x de Databricks para cargas de trabajo soportadas. Las aplicaciones, los DSN y las cadenas de conexión existentes que utilicen la funcionalidad habitual de la versión 2.x deberían funcionar, por lo general, sin necesidad de cambios.

Requisitos

El controlador ODBC de Databricks OSS y el controlador ODBC de Databricks versión 2.x utilizan el mismo nombre de controlador ODBC registrado, identificadores de paquete, rutas de instalación y nombres de biblioteca. La instalación de una versión sobre otra sustituye a la instalación existente. Para cambiar de controlador, reinstala el paquete de la versión que desees utilizar.

El controlador ODBC de Databricks OSS es compatible con las siguientes plataformas:

Sistema operativo Paquete y arquitectura Requirement
Windows MSI para x64 y x86 La arquitectura del controlador debe coincidir con la arquitectura de la aplicación.
macOS Universal .pkg para Intel y Apple Silicon macOS 13.3 o superior.
Linux .deb y .rpm para x86_64, aarch64 e i686 glibc 2.28 o superior y un administrador de controladores ODBC compatible.

También necesitarás el nombre de host del servidor y la ruta HTTP para un almacén de datos de Databricks SQL o Lakehouse//RT. Consulte Obtener detalles de conexión para un recurso de computación de Azure Databricks.

Instala el controlador ODBC de Databricks OSS

  1. En el archivo del controlador ODBC de Databricks OSS, descargue la versión 0.5.0 del controlador ODBC de Databricks OSS para su sistema operativo y arquitectura.
  2. Instala el paquete descargado:

    • En Windows, descomprime el archivo descargado y ejecuta el MSI de 32 bits o de 64 bits. El instalador registra el controlador ODBC de Databricks en el administrador de controladores ODBC de Windows.

    • En macOS, ejecute DatabricksODBC-<version>-macOS.pkg.

    • En Linux, instale el paquete .deb o .rpm y registre el controlador con unixODBC:

      sudo odbcinst -i -d -f /opt/databricks/databricksodbc/Setup/odbcinst.ini

Las bibliotecas del controlador se instalan en las mismas ubicaciones que la versión 2.x:

  • Windows de 64 bits: C:\Program Files\Databricks ODBC Driver\lib\databricksodbc64.dll
  • Windows de 32 bits: C:\Program Files (x86)\Databricks ODBC Driver\lib\databricksodbc32.dll
  • macOS: /Library/databricks/databricksodbc/lib/libdatabricksodbc.dylib
  • Linux de 64 bits: /opt/databricks/databricksodbc/lib/64/libdatabricksodbc64.so
  • Linux de 32 bits: /opt/databricks/databricksodbc/lib/32/libdatabricksodbc32.so

Configuración de una conexión

Empieza con tu DSN o cadena de conexión 2.x existente. Las propiedades comunes como Driver, Host, Port, HTTPPath, SSL, Catalog, y Schema son compatibles. El controlador también admite propiedades comunes de la versión 2.x que no son necesarias en su transporte HTTP, de modo que se puedan reutilizar los DSN existentes.

Para crear un DSN o una cadena de conexión sin DSN con esta configuración, consulta Crear un DSN ODBC para el controlador ODBC de Databricks o Crear una cadena de conexión sin DSN ODBC para el controlador ODBC de Databricks.

Para una nueva conexión, utilice las propiedades del siguiente ejemplo. Para un DSN, introduzca los mismos pares clave-valor mediante su administrador de controladores ODBC.

El siguiente ejemplo utiliza la autenticación OAuth de usuario a máquina (U2M). Se incluyen saltos de línea para facilitar la lectura. No los incluyas en la cadena de conexión:

Driver=<path-to-driver>;
Host=<server-hostname>;
Port=443;
HTTPPath=<http-path>;
SSL=1;
AuthMech=11;
Auth_Flow=2;
Catalog=main;
Schema=default

Se admiten los siguientes métodos de autenticación:

Método de autenticación Properties
OAuth usuario a máquina (U2M) AuthMech=11;Auth_Flow=2. PWD no es obligatorio. El almacenamiento en caché persistente de tokens está habilitado de forma predeterminada. Establezca EnableTokenCache=0 para deshabilitarlo, o establezca TokenCachePassPhrase para utilizar una frase de contraseña al cifrar la caché.
OAuth de máquina a máquina (M2M) AuthMech=11;Auth_Flow=1;Auth_Client_ID=<client-id>;Auth_Client_Secret=<client-secret>.
Pasar el token de OAuth AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>.
Token de acceso personal de Azure Databricks AuthMech=3;UID=token;PWD=<personal-access-token>.

Migrar desde la versión 2.x

  1. Revisa las limitaciones conocidas de las funciones que utiliza tu aplicación.
  2. Anote la versión 2.x instalada y realice una copia de seguridad de sus DSN, cadenas de conexión y archivos de configuración del controlador.
  3. Instala el controlador ODBC de Databricks OSS.
  4. Reutiliza tu DSN o cadena de conexión existente.
  5. Creación de conexiones de prueba, descubrimiento de metadatos, sentencias preparadas, vinculación de parámetros, cancelación, recuperación de grandes resultados y flujos de trabajo representativos de aplicaciones.

El controlador ODBC de Databricks OSS puede informar de nombres de tipos de Databricks más específicos y de la precisión y escala decimales declaradas con mayor detalle que la versión 2.x. Valida las aplicaciones que comparan exactamente los valores de los metadatos.

Para revertir los cambios tras sustituir una instalación, vuelve a instalar el paquete 2.x necesario y restaura la configuración de la copia de seguridad.

Limitaciones conocidas

Las siguientes limitaciones se aplican mientras el controlador esté en fase beta:

  • El controlador es compatible con los almacenes SQL y Lakehouse//RT de Databricks. No es compatible con la proceso de uso general.
  • Las consultas SQL siempre se envían directamente a Azure Databricks. El controlador no realiza la traducción a SQL-92 disponible en la versión 2.x. UseNativeQuery se admite por compatibilidad, pero no cambia el comportamiento.
  • No se admite la ejecución asíncrona a través de SQL_ATTR_ASYNC_ENABLE y SQLCompleteAsync.
  • No se admiten las operaciones PUT, GET y REMOVE para archivos en volúmenes de Unity Catalog.
  • No se soportan parámetros de entrada binarios.
  • Se admiten las matrices de parámetros, incluido pyodbc fast_executemany con valores de cadena y Unicode, pero el controlador envía una solicitud de ejecución por fila.
  • Los resultados de gran tamaño utilizan Cloud Fetch automáticamente y no se puede forzar su ejecución en línea. La recuperación de resultados admite los tipos de datos de Databricks SQL, excepto FILE y OBJECT. Los valores complejos se devuelven como texto.
  • Los proxies HTTPS admiten la autenticación básica, pero no la autenticación Kerberos ni SPNEGO.
  • No se admiten la configuración de revocación de certificados ni las claves privadas TLS mutuas cifradas.
  • Algunas propiedades avanzadas de 2.x no son compatibles. El controlador registra una advertencia cuando no se aplica una propiedad.
  • Se actualizó por última vez el