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.
Instalar o driver
O Databricks JDBC Driver (OSS) é publicado no repositórioMaven . A versão mais recente é 0.9.1-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.1-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.1-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 |
---|---|
|
O valor do servidor Databricks compute do recurso hostname. |
|
O valor da porta do recurso Databricks compute . O valor de default é |
|
O nome do esquema. Como alternativa, o senhor pode definir a propriedade |
|
O valor do caminho HTTP do recurso Databricks compute . O conector forma o endereço HTTP ao qual se conectar, acrescentando o valor |
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 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 |
---|---|
|
|
|
|
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 |
---|---|
|
|
|
|
|
O UUID da entidade de serviço ou o valor do ID do aplicativo. |
|
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 |
---|---|
|
|
|
O valor |
|
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 |
---|---|---|
|
Obrigatório |
O mecanismo de autenticação, em que |
|
|
O fluxo de autenticação OAuth2 para a conexão do driver. Essa propriedade é necessária se |
|
|
Se o conector se comunica com o servidor Spark por meio de um soquete habilitado para SSL. |
|
|
O nome do catálogo default a ser usado. |
|
|
O nome do esquema default a ser usado. Isso pode ser especificado substituindo |
|
|
Se definido como |
|
|
Uma cadeia de caracteres que representa o nome do host proxy a ser usado quando |
|
|
Um número inteiro que representa o número da porta do proxy a ser usada quando |
|
|
Uma cadeia de caracteres que representa o nome de usuário a ser usado para autenticação de proxy quando |
|
|
Uma cadeia de caracteres que representa a senha a ser usada para autenticação de proxy quando |
|
|
Se definido como |
|
|
Se definido como |
|
|
Se definido como |
|
|
Se definido como |
|
|
Uma cadeia de caracteres que representa o nome do host proxy a ser usado quando |
|
|
Um número inteiro que representa o número da porta do proxy a ser usada quando |
|
|
Uma cadeia de caracteres que representa o nome de usuário a ser usado para autenticação de proxy quando |
|
|
Uma cadeia de caracteres que representa a senha a ser usada para autenticação de proxy quando |
|
|
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. |
|
|
A entrada User-Agent a ser incluída na solicitação HTTP. Esse valor está no seguinte formato: |
|
|
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 |
---|---|---|
|
|
Se o comportamento ANSI SQL estrito deve ser ativado para determinadas funções e regras de conversão. |
|
|
Se o mecanismo de consulta vetorizada do Photon deve ser ativado. |
|
|
Os métodos usados para analisar e formatar datas e carimbos de data/hora. Os valores válidos são |
|
|
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 |
|
|
Controla se um metastore externo é tratado como somente leitura. |
|
|
Define um tempo limite de instrução SQL entre 0 e 172800 segundos. |
|
|
Defina o fuso horário local. IDs de região no formato |
|
|
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 |
---|---|---|
|
|
O nível de registro, que é um valor de 0 a 6:
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. |
|
|
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. Se o valor |
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();
}
}
}