Driver JDBC do Databricks (OSS)

Importante

Esse driver está em versão preliminar 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 JDBC (Java Database Connectivity), 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.

Instalar o driver

O Driver JDBC do Databricks (OSS) é publicado no Repositório Maven. A última versão é a 0.9.1-oss.

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

1. Faça login no workspace 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 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:

1. Faça login no workspace do Azure Databricks.
2. Na barra lateral, clique em SQL Warehouses e, em seguida, clique no nome do warehouse de destino.
3. Clique na guia Detalhes da conexão.
4. 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. Consulte Autenticar o acesso ao Azure Databricks com uma entidade de serviço usando OAuth (OAuth M2M).

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

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

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. 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_photo	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	4	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	logs/application.log	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. Se o valor LogPath 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 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();
        }
    }
}

Recursos adicionais

• Integração do DataGrip ao 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 ao StreamSets

• Conectar-se ao Syncsort

• Conectar-se ao MicroStrategy