Driver JDBC Databricks (OSS)

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.

Instale o driver

O Databricks JDBC Driver (OSS) é publicado no repositório Maven. A última versão é 0.9.1-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.1-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.1-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/cliserviceHTTP, 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:

1. Inicie sessão na área de trabalho do Azure Databricks.
2. Na barra lateral, clique em Computação e, em seguida, clique no nome do cluster de destino.
3. Na guia Configuração, expanda Opções avançadas.
4. Clique na guia JDBC/ODBC .
5. 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:

1. Inicie sessão na área de trabalho do Azure Databricks.
2. Na barra lateral, clique em SQL Warehouses e, em seguida, clique no nome do armazém de destino.
3. Clique na guia Detalhes da conexão.
4. 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:

1. 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.

2. 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.

3. 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, LEGACYe 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	4	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	logs/application.log	O caminho completo para a pasta onde o conector salva arquivos de log quando o log está habilitado, como uma cadeia de caracteres. Se o LogPath valor for inválido, o conector enviará as informações registradas para o fluxo de saída padrão (System.out).

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

Recursos adicionais

• Integração do DataGrip com o Azure Databricks

• Integração do DBeaver com o Azure Databricks

• Conectar-se ao SQL Workbench/J

• Conectar-se ao Infoworks

• Conectar-se ao Qlik Replicate

• Conectar-se a StreamSets

• Conectar-se ao Syncsort

• Ligar ao MicroStrategy