Driver JDBC 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 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.

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:

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 Usar uma entidade de serviço para autenticar com o Azure Databricks (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:

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:

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.

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.

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.

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