Databricks OSS ODBC Driver

Importante

O driver ODBC OSS da Databricks, versão 0.5.0, está em versão Beta. Para obter informações sobre o driver da versão 2.x de disponibilidade geral, consulte a documentação do driver ODBC da Databricks.

Para relatar um problema ou solicitar uma funcionalidade enquanto o driver estiver em beta, entre em contato com a equipe de conta da Databricks.

O Driver ODBC do Databricks OSS é um driver ODBC 3.8 para os warehouses SQL e Lakehouse//RT . Ele foi projetado para ser um substituto compatível do Databricks ODBC Driver versão 2.x para cargas de trabalho suportadas. Aplicações existentes, DSNs e strings de conexão que usam funcionalidades comuns 2.x geralmente devem funcionar sem alterações.

Requisitos

O Databricks OSS ODBC Driver e o Databricks ODBC Driver na versão 2.x usam o mesmo nome de driver ODBC registrado, identificadores de pacotes, caminhos de instalação e nomes de bibliotecas. Instalar uma versão em vez da outra substitui a instalação existente. Para alternar entre drivers, reinstale o pacote correspondente à versão que você deseja usar.

O driver ODBC do Databricks OSS é compatível com as seguintes plataformas:

Sistema operacional Pacote e arquitetura Requirement
Windows MSI para x64 e x86 A arquitetura do driver deve corresponder à arquitetura da aplicação.
macOS Universal .pkg para Intel e Apple silicon macOS 13.3 ou superior.
Linux .deb e .rpm para x86_64, aarch64 e i686 glibc 2.28 ou superior e um gerenciador de drivers ODBC compatível.

Você também precisa do Server Hostname e do HTTP Path para um warehouse Databricks SQL ou Lakehouse//RT. Consulte Obter detalhes de conexão para um recurso de computação do Azure Databricks.

Instale o driver ODBC OSS do Databricks

  1. Na página de arquivos do Databricks OSS ODBC Driver, baixe o Databricks OSS ODBC Driver na versão 0.5.0 para o seu sistema operacional e arquitetura.
  2. Instale o pacote baixado:

    • No Windows, extraia o download e execute o MSI de 32 ou 64 bits. O instalador registra o Driver ODBC de Databricks no Gerenciador de Drivers ODBC do Windows.

    • No macOS, execute DatabricksODBC-<version>-macOS.pkg.

    • No Linux, instale o pacote .deb ou .rpm e registre o driver no unixODBC:

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

As bibliotecas do driver são instaladas nos mesmos locais da versão 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 64-bit: /opt/databricks/databricksodbc/lib/64/libdatabricksodbc64.so
  • Linux 32-bit: /opt/databricks/databricksodbc/lib/32/libdatabricksodbc32.so

Configurar uma conexão

Comece com seu DSN 2.x existente ou sua cadeia de conexão existente. Propriedades comuns como Driver, Host, Port, HTTPPath, SSL, Catalog e Schema são compatíveis. O driver também aceita propriedades comuns do 2.x que não são necessárias em seu transporte HTTP para que DSNs existentes possam ser reutilizadas.

Para criar uma DSN ou uma cadeia de conexão sem DSN com essas configurações, veja Criar uma DSN ODBC para o Driver ODBC Databricks ou Criar uma cadeia de conexão sem DSN ODBC para o Driver ODBC Databricks.

Para uma nova conexão, use as propriedades no exemplo a seguir. Para uma DSN, insira os mesmos pares-chave-valor usando seu gerenciador de drivers ODBC.

O exemplo a seguir utiliza autenticação OAuth de usuário para máquina (U2M). Quebras de linha estão incluídas para legibilidade. Não os inclua na cadeia de conexão:

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

Há suporte para os seguintes métodos de autenticação:

Método de autenticação Properties
OAuth de Usuário para Máquina (U2M) AuthMech=11;Auth_Flow=2. PWD não é obrigatório. O cache persistente de tokens é ativado por padrão. Configure EnableTokenCache=0 para desativá-la, ou configure TokenCachePassPhrase para usar uma senha ao criptografar o cache.
OAuth máquina a máquina (M2M) AuthMech=11;Auth_Flow=1;Auth_Client_ID=<client-id>;Auth_Client_Secret=<client-secret>.
Passagem de token OAuth AuthMech=11;Auth_Flow=0;Auth_AccessToken=<oauth-token>.
Token de acesso pessoal do Azure Databricks AuthMech=3;UID=token;PWD=<personal-access-token>.

Migrar da versão 2.x

  1. Revise as limitações conhecidas dos recursos usados pela sua aplicação.
  2. Grave a versão 2.x instalada e faça backup dos DSNs, strings de conexão e arquivos de configuração do driver.
  3. Instale o driver ODBC do Databricks OSS.
  4. Reutilize seu DSN ou cadeia de conexão existente.
  5. Criação de conexões de teste, descoberta de metadados, instruções preparadas, vinculação de parâmetros, cancelamento, recuperação de grandes resultados e fluxos de trabalho representativos de aplicações.

O Databricks OSS ODBC Driver pode informar nomes de tipos do Databricks mais específicos e precisão e escala decimais declaradas com mais detalhes do que a versão 2.x. Valide aplicações que comparam valores de metadados exatamente.

Para reverter após substituir uma instalação, reinstale o pacote 2.x necessário e restaure a configuração de backup.

Limitações conhecidas

As seguintes limitações se aplicam enquanto o driver estiver em Beta:

  • O driver suporta Databricks SQL e Lakehouse//RT warehouses. Ele não suporta processamento de uso geral.
  • SQL é sempre enviado diretamente para o Azure Databricks. O driver não realiza a tradução SQL-92 disponível na versão 2.x. UseNativeQuery é aceito quanto à compatibilidade, mas não altera o comportamento.
  • Execução assíncrona através SQL_ATTR_ASYNC_ENABLE de e SQLCompleteAsync não é suportada.
  • PUT, GET, e REMOVE operações para arquivos em volumes do Catálogo Unity não são suportadas.
  • Parâmetros de entrada binários não são suportados.
  • Arrays de parâmetros, incluindo pyodbc fast_executemany com valores de string e Unicode, são suportados, mas o driver envia uma solicitação de execução por linha.
  • Resultados grandes usam Cloud Fetch automaticamente e não podem ser forçados inline. A recuperação de resultados suporta tipos de dados SQL do Databricks exceto FILE e OBJECT. Valores complexos são retornados como texto.
  • Proxies HTTPS suportam autenticação básica, mas não a autenticação Kerberos ou SPNEGO.
  • Configuração de revogação de certificados e chaves privadas TLS mútuas criptografadas não são suportadas.
  • Algumas propriedades avançadas 2.x não são suportadas. O motorista registra um aviso quando uma propriedade não é aplicada.
  • Última atualização em