Driver JDBC do Databricks (OSS)

Artigo
01/17/2025

Importante

Esse driver está em Visualização Pública e estará disponível como código aberto quando estiver em GA (disponibilidade geral).

O Databricks JDBC (OSS), a versão mais recente do driver, permite que você conecte ferramentas como DataGrip, DBeaver e SQL Workbench/J ao Azure Databricks por meio do Java Database Connectivity (JDBC), uma especificação padrão do setor para acessar sistemas de gerenciamento de banco de dados.

Esse driver implementou as APIs JDBC e fornece funcionalidades principais, incluindo OAuth, Cloud Fetch e recursos como ingestão de volume do Catálogo do Unity. Ele executa o modo de consulta nativa e dá suporte à consulta parametrizada nativa e pode ser executado usando APIs de Execução de Instrução, o que fornece o recurso benéfico de retenção de resultados de consulta, ou Thrift.

Este artigo fornece informações sobre como instalar e usar o Driver JDBC do Databricks (OSS). Para obter informações sobre o Driver JDBC do Databricks não OSS, confira Driver JDBC do Databricks.

Requisitos

Para usar o Driver JDBC do Databricks (OSS), os seguintes requisitos devem ser atendidos:

JRE (Java Runtime Environment) 11.0 ou superior. O teste de CI tem suporte no JRE 11, 17 e 21.

Observação

Como resultado de uma alteração no JDK 16 que causou um problema de compatibilidade com a biblioteca Apache Arrow usada pelo driver JDBC, podem ocorrer erros de tempo de execução ao usar o driver JDBC com JDK 16 ou superior. Para evitar esses erros, reinicie seu aplicativo ou driver usando a seguinte opção de comando JVM:

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

Instalar o driver

O Driver JDBC do Databricks (OSS) é publicado no Repositório Maven.

Para instalar o driver, você pode fazer o seguinte:

Para projetos do Maven, adicione a seguinte dependência ao arquivo pom.xml do projeto para instruir o Maven a baixar automaticamente o driver JDBC com a versão especificada:
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.6-oss</version>
  <scope>runtime</scope>
</dependency>
```
Para projetos do Gradle, adicione a seguinte dependência ao arquivo de compilação do projeto para instruir o Gradle a baixar automaticamente o driver JDBC com a versão especificada:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Para exibir a sintaxe de dependência para outros tipos de projeto e obter o número da versão mais recente do Driver JDBC do Databricks (OSS), confira o Repositório Maven.

Configurar o URL de conexão

Para se conectar ao workspace do Azure Databricks usando o driver JDBC, você precisa especificar um URL de conexão JDBC que inclua várias configurações de conexão, como o nome do host do servidor do workspace do Azure Databricks, as configurações de recursos de computação e as credenciais de autenticação para se conectar ao workspace.

Você pode definir o valor dessas propriedades no URL de conexão JDBC, defini-las e passá-las para o método DriverManager.getConnection ou uma combinação de ambos. Confira a documentação do provedor para saber como se conectar melhor usando seu aplicativo, cliente, SDK, API ou ferramenta SQL específica.

O URL de conexão JDBC deve estar no formato a seguir. As propriedades não diferenciam maiúsculas de minúsculas.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

Como alternativa, especifique as configurações usando a classe java.util.Properties ou uma combinação:

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

Os elementos do URL de conexão são descritos na tabela a seguir. Para obter informações sobre propriedades adicionais, incluindo propriedades de autenticação, confira as seções abaixo. Elementos e propriedades de URL não diferenciam maiúsculas de minúsculas.

Elemento ou propriedade de URL	Descrição
`<server-hostname>`	O valor do nome do host do servidor do recurso de computação do Azure Databricks.
`<port>`	O valor da porta do recurso de computação do Azure Databricks. O valor padrão é `443`.
`<schema>`	O nome do esquema. Como alternativa, você pode definir a propriedade `ConnSchema`. Confira as Propriedades de conexão.
`httpPath`	O valor do caminho HTTP do recurso de computação do Azure Databricks. O conector forma o endereço HTTP para se conectar anexando o valor `httpPath` ao host e à porta especificados no URL de conexão. Por exemplo, para se conectar ao endereço HTTP `http://localhost:10002/cliservice`, você usaria o seguinte URL de conexão: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Para obter o URL de conexão JDBC para um cluster do Azure Databricks:

Faça login no workspace do Azure Databricks.
Na barra lateral, clique em Computação e, em seguida, clique no nome do cluster de destino.
Na guia Configuração, expanda Opções avançadas.
Clique na guia JDBC/ODBC.
Copie o URL do JDBC para usar como URL de conexão JDBC ou construa o URL a partir de valores nos campos Nome do host do servidor, Porta e Caminho HTTP.

Para obter o URL de conexão JDBC para um warehouse do Databricks SQL:

Faça login no workspace do Azure Databricks.
Na barra lateral, clique em SQL Warehouses e, em seguida, clique no nome do warehouse de destino.
Clique na guia Detalhes da conexão.
Copie o URL do JDBC para usar como URL de conexão JDBC ou construa o URL a partir de valores nos campos Nome do host do servidor, Porta e Caminho HTTP.

Autenticar o driver

Você pode autenticar a conexão do driver JDBC usando um dos seguintes mecanismos de autenticação:

Autenticação U2M (usuário para computador) do OAuth (recomendado)
Autenticação OAuth máquina a máquina (M2M)
Token de acesso pessoal do Azure Databricks

Autenticação U2M (usuário para computador) do OAuth

O driver JDBC oferece suporte à autenticação U2M (usuário para computador) do OAuth com entrada humana e consentimento em tempo real para autenticar a conta de usuário do Azure Databricks de destino. Isso também é conhecido como autenticação baseada em navegador do OAuth.

O Azure Databricks criou o ID do cliente OAuth databricks-sql-jdbc para os clientes. Esse também é o ID do cliente OAuth padrão usado no driver JDBC. Para configurar a autenticação U2M do OAuth, adicione as seguintes propriedades ao URL de conexão JDBC existente ou ao objeto java.util.Properties:

Propriedade	Valor
`AuthMech`	`11`
`Auth_Flow`	`2`

Autenticação M2M (de computador para computador) do OAuth

O driver JDBC oferece suporte à autenticação computador para computador (M2M) do OAuth usando entidade de serviço do Azure Databricks. Isso também é conhecido como autenticação de credenciais de cliente OAuth 2.0. Veja Autorizar acesso autônomo aos recursos do Azure Databricks com uma entidade de serviço usando OAuth.

Para configurar a autenticação de credenciais do cliente OAuth M2M ou OAuth 2.0:

Crie uma entidade de serviço gerenciada do Microsoft Entra ID e, em seguida, atribua-a a contas e Workspaces do Azure Databricks. Para obter detalhes, confira Gerenciar entidades de serviço.

Importante

O Driver JDBC do Databricks (OSS) dá suporte aos segredos OAuth do Azure Databricks para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0. Não há suporte para segredos do Microsoft Entra ID.
Crie um segredo OAuth do Azure Databricks para a entidade de serviço. Para fazer isso, veja Gerar e usar manualmente tokens de acesso para autenticação principal do serviço OAuth.
Conceda à entidade de serviço acesso ao cluster ou ao warehouse. Consulte Permissões de computação ou Gerenciar um SQL warehouse.

Adicione as seguintes propriedades ao URL de conexão JDBC existente ou ao objeto java.util.Properties:

Propriedade	Valor
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	O valor da ID do aplicativo (cliente) da entidade de serviço.
`OAuth2Secret`	O segredo OAuth do Azure Databricks para o Databricks da entidade de serviço. (Não há suporte para segredos do Microsoft Entra ID para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0).

Token de acesso pessoal do Azure Databricks

Para autenticar sua conexão do driver JDBC usando um token de acesso pessoal do Azure Databricks, adicione as seguintes propriedades ao URL de conexão JDBC ou ao objeto java.util.Properties:

Propriedade	Valor
`AuthMech`	`3`
`user`	O valor `token`, como uma cadeia de caracteres.
`PWD` ou `password`	O valor do token de acesso pessoal do Azure Databricks, como uma cadeia de caracteres.

Propriedades da conexão

As propriedades de conexão adicionais a seguir são compatíveis com o driver JDBC. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`AuthMech`	Obrigatório	O mecanismo de autenticação, onde `3` especifica que o mecanismo é um token de acesso pessoal do Azure Databricks e `11` especifica que o mecanismo são tokens OAuth 2.0. Propriedades adicionais são necessárias para cada mecanismo. Confira Autenticação do driver.
`Auth_Flow`	`0`	O fluxo de autenticação OAuth2 para a conexão do driver. Essa propriedade será necessária se `AuthMech` for `11`.
`SSL`	`1`	Se o conector se comunica com o servidor Spark por meio de um soquete habilitado para SSL.
`ConnCatalog` ou `catalog`	`SPARK`	O nome do catálogo padrão a ser usado.
`ConnSchema` ou `schema`	`default`	O nome do esquema padrão a ser usado. Isso pode ser especificado substituindo o `<schema>` no URL pelo nome do esquema a ser usado ou definindo a propriedade `ConnSchema` como o nome do esquema a ser usado.
`ProxyAuth`	`0`	Se definido como `1`, o driver usará o usuário de autenticação de proxy e a senha, representados por `ProxyUID` e `ProxyPwd`.
`ProxyHost`	`null`	Uma cadeia de caracteres que representa o nome do host do proxy a ser usado quando `UseProxy` também for definido como `1`.
`ProxyPort`	`null`	Um inteiro que representa o número da porta do proxy a ser usada quando `UseProxy` também for definido como `1`.
`ProxyUID`	`null`	Uma cadeia de caracteres que representa o nome de usuário a ser usado para autenticação de proxy quando `ProxyAuth` e `UseProxy` também forem definidos como `1`.
`ProxyPwd`	`null`	Uma cadeia de caracteres que representa a senha a ser usada para autenticação de proxy quando `ProxyAuth` e `UseProxy` também forem definidos como `1`.
`UseProxy`	`0`	Se definido como `1`, o driver usará as configurações de proxy fornecidas (por exemplo: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd` e `ProxyUID`).
`UseSystemProxy`	`0`	Se definido como `1`, o driver usará as configurações de proxy que foram definidas no nível do sistema. Se as propriedades de proxy adicionais forem definidas no URL de conexão, essas propriedades de proxy adicionais substituirão aquelas que foram definidas no nível do sistema.
`UseCFProxy`	`0`	Se definido como `1`, o driver usará as configurações de proxy de busca de nuvem se forem fornecidas, caso contrário, use o proxy regular.
`CFProxyAuth`	`0`	Se definido como `1`, o driver usará o usuário de autenticação de proxy e a senha, representados por `CFProxyUID` e `CFProxyPwd`.
`CFProxyHost`	`null`	Uma cadeia de caracteres que representa o nome do host do proxy a ser usado quando `UseCFProxy` também for definido como `1`.
`CFProxyPort`	`null`	Um inteiro que representa o número da porta do proxy a ser usada quando `UseCFProxy` também for definido como `1`.
`CFProxyUID`	`null`	Uma cadeia de caracteres que representa o nome de usuário a ser usado para autenticação de proxy quando `CFProxyAuth` e `UseCFProxy` também forem definidos como `1`.
`CFProxyPwd`	`null`	Uma cadeia de caracteres que representa a senha a ser usada para autenticação de proxy quando `CFProxyAuth` e `UseCFProxy` também forem definidos como `1`.
`AsyncExecPollInterval`	`200`	O tempo em milissegundos entre cada sondagem para o status de execução da consulta assíncrona. Assíncrona refere-se ao fato de que a chamada RPC usada para executar uma consulta no Spark é assíncrona. Isso não significa que há suporte para operações assíncronas de JDBC.
`UserAgentEntry`	`browser`	A entrada User-Agent a ser incluída na solicitação HTTP. Esse valor está no seguinte formato: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`0`	Se o driver JDBC deve usar o cliente Thrift para se conectar a um cluster para todas as finalidades. O valor padrão também pode ser usado em depósitos SQL.

Propriedades de configuração SQL

As propriedades de configuração SQL a seguir são compatíveis com o driver JDBC. Elas também são descritas nos Parâmetros de configuração. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`ansi_mode`	`TRUE`	Se deseja habilitar o comportamento estrito do SQL ANSI para determinadas funções e regras de conversão.
`enable_photon`	`TRUE`	Se deseja habilitar o mecanismo de consulta vetorizado Photon.
`legacy_time_parser_policy`	`EXCEPTION`	Os métodos usados para analisar e formatar datas e carimbos de data/hora. Os valores válidos são `EXCEPTION`, `LEGACY` e `CORRECTED`.
`max_file_partition_bytes`	`128m`	O número máximo de bytes a serem empacotados em uma única partição ao ler fontes baseadas em arquivo. A configuração pode ser qualquer inteiro positivo e, opcionalmente, incluir uma medida como `b` (bytes), `k` ou `kb` (1024 bytes).
`read_only_external_metastore`	`false`	Controla se um metastore externo é tratado como somente leitura.
`statement_timeout`	`172800`	Define um tempo limite de instrução SQL entre 0 e 172800 segundos.
`timezone`	`UTC`	Defina o fuso horário local. IDs de região no formato `area/city`, como América/Los_Angeles ou deslocamentos de zona no formato (+\|-)HH, (+\|-)HH:mm ou (+\|-)HH:mm:ss, por exemplo, -08, +01:00 ou -13:33:33. Além disso, há suporte para `UTC` como um alias para +00:00
`use_cached_result`	`true`	Se o Databricks SQL armazena em cache e reutiliza os resultados sempre que possível.

Propriedades de log

As propriedades de registro em log a seguir são compatíveis com o driver JDBC. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`LogLevel`	`OFF`	O nível de registros em log, que é um valor de 0 a 6: - 0: Desabilitar todo o registro em log. - 1: Habilitar o registro em log no nível FATAL, que registra eventos de erro muito graves que levarão o conector a anular. - 2: Habilitar o registro em log no nível ERROR, que registra eventos de erro que ainda podem permitir que o conector continue em execução. - 3: Habilitar o registro em log no nível AVISO, que registra eventos que podem resultar em erro se nenhuma ação for tomada. - 4: Habilitar o registro em log no nível INFO, que registra informações gerais que descrevem o progresso do conector. - 5: Habilitar o registro em log no nível DEBUG, que registra informações detalhadas úteis para depurar o conector. - 6: Habilitar o registro em log no nível TRACE, que registra todas as atividades do conector. Use essa propriedade para habilitar ou desabilitar o registro em log no conector e especificar a quantidade de detalhes incluídos nos arquivos de log.
`LogPath`	Para determinar o caminho padrão para logs, o driver usa o valor definido para essas propriedades do sistema, nesta ordem de prioridade: 1. `user.dir` 2. `java.io.tmpdir` 3. O diretório atual, em outras palavras, `.`	O caminho completo para a pasta em que o conector salva arquivos de log quando o registro em log está habilitado, como uma cadeia de caracteres. Para garantir que a URL de conexão seja compatível com todos os aplicativos JDBC, escape as barras invertidas (`\`) no caminho do arquivo digitando outra barra invertida. Se o `LogPath` valor for inválido, o conector enviará as informações registradas para o fluxo de saída padrão (System.out).
`LogFileSize`	Sem máximo	O tamanho máximo permitido do arquivo de log, especificado em MB
`LogFileCount`	Sem máximo	O número máximo de arquivos de log permitidos

Habilitar e configurar o registro em log

O driver JDBC suporta as estruturas Simple Logging Facade for Java (SLF4J) e java.util.logging (JUL). O driver usa a estrutura de log JUL por padrão.

Para habilitar e configurar o registro para o driver JDBC:

Habilite a estrutura de log que você deseja usar:
- Para a criação de log do SLF4J, defina a propriedade -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER do sistema e forneça a implementação da ligação SLF4J (compatível com o SLF4J versão 2.0.13 e superior) e o arquivo de configuração correspondente no classpath.
- Para log JUL, defina a propriedade -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERdo sistema . Esse é o padrão.
Defina a LogLevel propriedade na cadeia de conexão para o nível desejado de informações a serem incluídas nos arquivos de log.
Defina a LogPath propriedade na cadeia de conexão como o caminho completo para a pasta em que você deseja salvar os arquivos de log.

Por exemplo, a seguinte URL de conexão habilita o nível de registro 6 e salva os arquivos de log na pasta C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Reinicie seu aplicativo JDBC e reconecte-se ao servidor para aplicar as configurações.

Exemplo: executar uma consulta usando o driver JDBC

O exemplo a seguir mostra como usar o driver JDBC para executar uma consulta do Databricks SQL usando um recurso de computação do Azure Databricks.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Compartilhar via