Driver JDBC Databricks (OSS)

Artigo
11/16/2024

Importante

Este driver está em visualização pública e ainda não está disponível como código aberto.

O Databricks fornece um driver JDBC de software de código aberto (OSS) que permite conectar 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 a ingestão de volume do Unity Catalog. Ele executa o modo de consulta nativo e suporta consulta parametrizada nativa, e pode ser executado usando APIs de execução de instrução, que fornece o recurso de retenção de resultados de consulta benéfico, ou Thrift.

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

Requisitos

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

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

Nota

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

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

Instale o driver

O Databricks JDBC Driver (OSS) é publicado no repositório Maven. A última versão é 0.9.6-oss.

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

Para projetos Maven, adicione a seguinte dependência ao arquivo do pom.xml 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 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 Databricks JDBC Driver (OSS), consulte o Repositório Maven.

Configurar a URL de conexão

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

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

A URL de conexão JDBC deve estar no seguinte formato. 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 java.util.Properties classe 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 de URL de conexão são descritos na tabela a seguir. Para obter informações sobre propriedades adicionais, incluindo propriedades de autenticação, consulte as seções abaixo. Os elementos e propriedades de URL não diferenciam maiúsculas de minúsculas.

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

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

Inicie sessão na área de trabalho 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 a URL JDBC para usar como a URL de conexão JDBC ou construa a URL a partir de valores nos campos Nome do host do servidor, Porta e Caminho HTTP.

Para obter a URL de conexão JDBC para um armazém SQL do Databricks:

Inicie sessão na área de trabalho do Azure Databricks.
Na barra lateral, clique em SQL Warehouses e, em seguida, clique no nome do armazém de destino.
Clique na guia Detalhes da conexão.
Copie a URL JDBC para usar como a URL de conexão JDBC ou construa a 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 OAuth user-to-machine (U2M) (Recomendado)
Autenticação máquina a máquina (M2M) OAuth
Token de acesso pessoal do Azure Databricks

Autenticação OAuth user-to-machine (U2M)

O driver JDBC suporta autenticação OAuth user-to-machine (U2M) para login humano em tempo real e consentimento para autenticar a conta de usuário Databricks de destino. Isso também é conhecido como autenticação OAuth baseada em navegador.

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

Property	valor
`AuthMech`	`11`
`Auth_Flow`	`2`

Autenticação OAuth máquina-a-máquina (M2M)

O driver JDBC dá suporte à autenticação OAuth máquina-a-máquina (M2M) usando uma entidade de serviço do Azure Databricks. Isso também é conhecido como autenticação de credenciais de cliente OAuth 2.0. Consulte Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M).

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

Crie uma entidade de serviço gerenciado do Microsoft Entra ID e atribua-a a contas e espaços de trabalho do Azure Databricks. Para obter detalhes, consulte Gerenciar entidades de serviço.

Importante

O Databricks JDBC Driver (OSS) dá suporte aos segredos OAuth do Azure Databricks para autenticação de credenciais de cliente OAuth M2M ou OAuth 2.0. Os segredos de ID do Microsoft Entra não são suportados.
Crie um segredo OAuth do Azure Databricks para a entidade de serviço. Para fazer isso, consulte Gerar e usar manualmente tokens de acesso para autenticação OAuth M2M.
Dê à entidade de serviço acesso ao seu cluster ou depósito. Consulte Permissões de computação ou Gerenciar um armazém SQL.

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

Property	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 da entidade de serviço. (Os segredos de ID do Microsoft Entra não são suportados 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 de driver JDBC usando um token de acesso pessoal do Azure Databricks, adicione as seguintes propriedades à URL ou java.util.Properties objeto de conexão JDBC:

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

Propriedades de ligação

As seguintes propriedades de conexão adicionais são suportadas pelo driver JDBC. As propriedades não diferenciam maiúsculas de minúsculas.

Property	Valor predefinido	Description
`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 é tokens OAuth 2.0. Propriedades adicionais são necessárias para cada mecanismo. Consulte Autenticar o driver.
`Auth_Flow`	`0`	O fluxo de autenticação OAuth2 para a conexão do driver. Esta propriedade é 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 `<schema>` na URL pelo nome do esquema a ser usado ou definindo a `ConnSchema` propriedade como o nome do esquema a ser usado.
`ProxyAuth`	`0`	Se definido como `1`, o driver usa o usuário e a senha de autenticação de proxy, representados por `ProxyUID` e `ProxyPwd`.
`ProxyHost`	`null`	Uma cadeia de caracteres que representa o nome do host proxy a ser usado quando `UseProxy` também estiver definida como `1`.
`ProxyPort`	`null`	Um inteiro que representa o número da porta proxy a ser usada quando `UseProxy` também está 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 são 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 são definidas como `1`.
`UseProxy`	`0`	Se definido como `1`, o driver usa as configurações de proxy fornecidas (por exemplo: `ProxyAuth`, , `ProxyHost`, `ProxyPortProxyPwd`, e `ProxyUID`).
`UseSystemProxy`	`0`	Se definido como `1`, o driver usa as configurações de proxy que foram definidas no nível do sistema. Se quaisquer propriedades de proxy adicionais forem definidas na 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 usa as configurações de proxy de busca na nuvem se elas forem fornecidas, caso contrário, use o proxy regular.
`CFProxyAuth`	`0`	Se definido como `1`, o driver usa o usuário e a senha de autenticação de proxy, representados por `CFProxyUID` e `CFProxyPwd`.
`CFProxyHost`	`null`	Uma cadeia de caracteres que representa o nome do host proxy a ser usado quando `UseCFProxy` também estiver definida como `1`.
`CFProxyPort`	`null`	Um inteiro que representa o número da porta proxy a ser usada quando `UseCFProxy` também está 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 são 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 são definidas como `1`.
`AsyncExecPollInterval`	`200`	O tempo, em milissegundos, entre cada sondagem para o status de execução da consulta assíncrona. Assíncrono refere-se ao fato de que a chamada RPC usada para executar uma consulta no Spark é assíncrona. Isso não significa que as operações assíncronas JDBC são suportadas.
`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 multiuso. O valor padrão funciona para armazéns SQL.

Propriedades de configuração do SQL

As seguintes propriedades de configuração SQL são suportadas pelo driver JDBC. Estes também são descritos em Parâmetros de configuração. As propriedades não diferenciam maiúsculas de minúsculas.

Property	Valor predefinido	Description
`ansi_mode`	`TRUE`	Se é necessário habilitar o comportamento ANSI SQL estrito para determinadas funções e regras de transmissão.
`enable_photo`	`TRUE`	Se o mecanismo de consulta vetorizada Photon deve ser habilitado.
`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 para empacotar em uma única partição ao ler de 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 America/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, `UTC` é suportado 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 registro em log

As seguintes propriedades de log são suportadas pelo driver JDBC. As propriedades não diferenciam maiúsculas de minúsculas.

Property	Valor predefinido	Description
`LogLevel`	`OFF`	O nível de log, que é um valor de 0 a 6: - 0: Desative todo o registro. - 1: Habilite o registro no nível FATAL, que registra eventos de erro muito graves que levarão o conector a abortar. - 2: Habilite o registro no nível ERROR, que registra eventos de erro que ainda podem permitir que o conector continue em execução. - 3: Habilite o registro no nível WARNING, que registra eventos que podem resultar em um erro se uma ação não for tomada. - 4: Habilite o registro no nível INFO, que registra informações gerais que descrevem o progresso do conector. - 5: Habilite o registro no nível DEBUG, que registra informações detalhadas que são úteis para depurar o conector. - 6: Habilite o registro no nível TRACE, que registra toda a atividade do conector. Use essa propriedade para habilitar ou desabilitar o registro em log no conector e para 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. Por outras palavras, o atual diretório `.`	O caminho completo para a pasta onde o conector salva arquivos de log quando o 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 das 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 em log para o driver JDBC:

Habilite a estrutura de log que você deseja usar:
- Para registro em log SLF4J, defina a propriedade -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER system e forneça a implementação de vinculação SLF4J (compatível com SLF4J versão 2.0.13 e superior) e o arquivo de configuração correspondente no classpath.
- Para registro em log JUL, defina a propriedade -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERsystem . Esta é a predefiniçã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 para o caminho completo para a pasta onde você deseja salvar os arquivos de log.

Por exemplo, a seguinte URL de conexão habilita o nível de log 6 e salva os arquivos de log na pasta C:temp:
```
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
```
Reinicie o 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 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();
        }
    }
}

Partilhar via