Driver JDBC do Databricks (OSS)

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.
• Databricks SQL 2024.30 ou superior

Instalar o driver

O Driver JDBC do Databricks (OSS) é publicado no Repositório Maven. A versão mais recente é 0.9.0-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.0-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.0-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.

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:

• Token de acesso pessoal do Azure Databricks

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

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:

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

O driver JDBC dá suporte à autenticação OAuth M2M ( máquina a máquina) para uma entidade de serviço do Microsoft Entra ID. Isso também é conhecido como autenticação de credenciais de cliente OAuth 2.0.

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:

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.

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.

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.

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