Driver JDBC da Databricks (OSS)

Prévia

Esse driver está em Public Preview e ainda não está disponível como código aberto.

Databricks fornece um driver de código aberto software (OSS) JDBC que permite que o senhor conecte ferramentas como DataGrip, DBeaver, e SQL Workbench/J a Databricks por meio do Java Database Connectivity (JDBC), uma especificação padrão da indústria para acessar sistemas de gerenciamento de banco de dados.

Esse driver implementou o JDBC APIs e fornece a funcionalidade principal, incluindo OAuth, cloud Fetch e recurso como Unity Catalog ingestão de volume. Ele executa o modo de consulta nativa e oferece suporte a consultas parametrizadas nativas, e pode ser executado usando o Statement Execution APIs, que fornece o recurso de retenção de resultados de consultas benéficas, ou Thrift.

Este artigo fornece informações sobre a instalação e o uso do driver Databricks JDBC (OSS). Para obter informações sobre o driver Databricks JDBC que não é da 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 é compatível com o JRE 11, 17 e 21.

Observação

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

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

Instalar o driver

O Databricks JDBC Driver (OSS) é publicado no repositórioMaven . A versão mais recente é 0.9.6-oss.

Para instalar o driver, o senhor pode fazer o seguinte:

Para os projetos Maven, adicione a seguinte dependência ao arquivo pom.xml do projeto para instruir o Maven a download 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 os projetos do Gradle, adicione a seguinte dependência ao arquivo de compilação do projeto para instruir o Gradle a download automaticamente o driver JDBC com a versão especificada:
```
implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
```

Para view a sintaxe de dependência para outros tipos de projeto e para obter o número da versão mais recente do driver Databricks JDBC (OSS), consulte o repositórioMaven .

Configurar o URL de conexão

Para se conectar ao seu Databricks workspace usando o driver JDBC, o senhor precisa especificar um URL de conexão JDBC que inclua várias configurações de conexão, como o servidor Databricks workspace 's hostname, as configurações de recurso compute e as credenciais de autenticação para se conectar ao workspace.

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

O URL da 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 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 estã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 as propriedades do URL não diferenciam maiúsculas de minúsculas.

Elemento ou propriedade de URL	Descrição
`<server-hostname>`	O valor do servidor Databricks compute do recurso hostname.
`<port>`	O valor da porta do recurso Databricks compute . O valor de default é `443`.
`<schema>`	O nome do esquema. Como alternativa, o senhor pode definir a propriedade `ConnSchema`. Consulte Propriedades de conexão.
`httpPath`	O valor do caminho HTTP do recurso Databricks compute . O conector forma o endereço HTTP ao qual se conectar, acrescentando 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`, o senhor usaria o seguinte URL de conexão: `jdbc:databricks://localhost:10002;httpPath=cliservice`

Para obter o URL de conexão JDBC para um cluster da Databricks:

Faça login no seu espaço de trabalho do Databricks.
Na barra lateral, clique em computee, em seguida, clique no nome do site clusterde destino.
Em Configuration (Configuração ) tab, expanda Advanced options (Opções avançadas).
Clique no link JDBC/ODBC tab.
Copie o URLJDBC para usá-lo como URL de conexão JDBC ou construa o URL com base nos valores dos campos Server hostname, Port e HTTP Path.

Para obter o JDBC URL de conexão para um Databricks SQL depósito:

Faça login no seu espaço de trabalho do Databricks.
Na barra lateral, clique em SQL warehouse e, em seguida, clique no nome do warehouse de destino.
Clique em Connection details (Detalhes da conexão ) tab.
Copie o URLJDBC para usá-lo como URL de conexão JDBC ou construa o URL com base nos valores dos campos Server hostname, Port e HTTP Path.

Autenticar o motorista

O senhor pode autenticar a conexão do driver JDBC usando um dos seguintes mecanismos de autenticação:

Autenticação OAuth de usuário para máquina (U2M) (recomendado)
Autenticação OAuth máquina a máquina (M2M)
Databricks pessoal access token

Autenticação de usuário para máquina (U2M) OAuth

O driver JDBC é compatível com a autenticação de usuário para máquina (U2M) OAuth para login humano real e consentimento para autenticar o usuário de destino Databricks account. Isso também é conhecido como autenticação OAuth baseada em navegador.

A Databricks criou o ID do cliente OAuth databricks-sql-jdbc para os clientes. Esse também é o ID do cliente default OAuth usado no driver JDBC. Para configurar a autenticação OAuth U2M, basta adicionar 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 OAuth máquina a máquina (M2M)

O driver JDBC oferece suporte à autenticação OAuth máquina a máquina (M2M) usando uma entidade de serviço da Databricks. Isso também é conhecido como autenticação de credenciais de cliente OAuth 2.0. Consulte Autenticar o acesso ao 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 Databricks entidade de serviço em seu Databricks workspace e crie um OAuth secret para essa entidade de serviço. Consulte Autenticar o acesso ao Databricks com uma entidade de serviço usando OAuth (OAuth M2M). Anote o valor do UUID da entidade de serviço ou do ID do aplicativo e o valor do segredo do OAuth da entidade de serviço.
Conceda à entidade de serviço acesso ao seu site cluster ou armazém. Consulte as permissões do sitecompute ou gerenciar a SQL warehouse.

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

Propriedade	Valor
`AuthMech`	`11`
`Auth_Flow`	`1`
`OAuth2ClientID`	O UUID da entidade de serviço ou o valor do ID do aplicativo.
`OAuth2Secret`	O valor do segredo OAuth da entidade de serviço.

Databricks pessoal access token

Para autenticar a conexão do driver JDBC usando um Databricks pessoal access token, adicione as seguintes propriedades ao URL ou objeto java.util.Properties da conexão JDBC:

Propriedade	Valor
`AuthMech`	`3`
`user`	O valor `token`, como uma cadeia de caracteres.
`PWD` ou `password`	O senhor Databricks pessoal access token valor, como uma cadeia de caracteres.

Propriedades de conexão

As seguintes propriedades adicionais de conexão 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, em que `3` especifica que o mecanismo é um Databricks pessoal access token, e `11` especifica que o mecanismo é OAuth 2.0 tokens. 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. Essa 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 default a ser usado.
`ConnSchema` ou `schema`	`default`	O nome do esquema default a ser usado. Isso pode ser especificado substituindo `<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 e a senha de autenticação do 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 é definido como `1`.
`ProxyPort`	`null`	Um número inteiro que representa o número da porta do proxy a ser usada quando `UseProxy` também é 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 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 quaisquer propriedades adicionais de proxy forem definidas no URL de conexão, essas propriedades adicionais de proxy substituirão as que foram definidas no nível do sistema.
`UseCFProxy`	`0`	Se definido como `1`, o driver usará as configurações de proxy de busca do cloud se elas forem fornecidas; caso contrário, usará o proxy regular.
`CFProxyAuth`	`0`	Se definido como `1`, o driver usará o usuário e a senha de autenticação do 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 é definido como `1`.
`CFProxyPort`	`null`	Um número inteiro que representa o número da porta do proxy a ser usada quando `UseCFProxy` também é 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 definidos como `1`.
`AsyncExecPollInterval`	`200`	O tempo em milissegundos entre cada pesquisa do 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 haja 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 clusters todo-propósito. O valor default funciona para o depósito SQL.

Propriedades de configuração do SQL

As seguintes propriedades de configuração do SQL são compatíveis com o driver JDBC. Eles também são descritos em 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 o comportamento ANSI SQL estrito deve ser ativado para determinadas funções e regras de conversão.
`enable_photo`	`TRUE`	Se o mecanismo de consulta vetorizada do Photon deve ser ativado.
`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 de fontes baseadas em arquivos. A configuração pode ser qualquer número 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 offsets 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

As seguintes propriedades de registro 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`	`OFF`	O nível de registro, que é um valor de 0 a 6: 0: Desabilita todos os registros. 1: Habilita o registro no nível FATAL, que logs eventos de erro muito graves que levarão o conector a abortar. 2: Habilite o registro em log no nível ERROR, que logs eventos de erro que ainda podem permitir que o conector continue em execução. 3: Ative o registro no nível WARNING (aviso), que logs eventos que podem resultar em erro se não forem tomadas medidas. 4: Habilite o registro no nível INFO, que logs informações gerais que descrevem o progresso do conector. 5: Ative o registro no nível DEBUG, que logs informações detalhadas que são úteis para a depuração do conector. 6: Habilite o registro no nível TRACE, que logs toda a atividade do conector. Use essa propriedade para ativar ou desativar o registro em log no conector e para especificar a quantidade de detalhes incluídos nos arquivos de log.
`LogPath`	Para determinar o caminho default para logs, o driver usa o valor definido para essas propriedades do sistema, nesta ordem de prioridade: `user.dir` `java.io.tmpdir` o diretório atual, em outras palavras `.`	O caminho completo para a pasta em que o conector salva os arquivos log quando o registro em log está ativado, como uma cadeia de caracteres. Para garantir que o URL de conexão seja compatível com todos os aplicativos JDBC, escape as barras invertidas (`\`) no caminho do arquivo digitando outra barra invertida. Se o valor de `LogPath` for inválido, o conector enviará as informações de registros para a transmissão de saída padrão (System.out).
`LogFileSize`	Sem máximo	O tamanho máximo permitido do arquivo log, especificado em MB
`LogFileCount`	Sem máximo	O número máximo de arquivos permitidos no site log

Ativar e configurar o registro

O driver JDBC é compatível com as estruturas Simple Logging Facade for Java (SLF4J) e java.util.logging (JUL). O driver usa a estrutura de registro JUL por default.

Para ativar e configurar o registro em log do driver JDBC:

Ative a estrutura de registro que você deseja usar:
- Para o registro em log do SLF4J, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER e forneça a implementação de ligação do SLF4J (compatível com o SLF4J versão 2.0.13 e acima) e o arquivo de configuração correspondente no classpath.
- Para o registro de JUL, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Este é o site default.
Defina a propriedade LogLevel nas cadeias de conexão para o nível desejado de informações a serem incluídas nos arquivos log.
Defina a propriedade LogPath nas cadeias de conexão como o caminho completo para a pasta onde o senhor deseja salvar os arquivos log.

Por exemplo, o URL de conexão a seguir ativa o nível de registro 6 e salva os arquivos 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: execução de 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 Databricks compute .

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