Propriedades de conexão suportadas

Este artigo descreve as propriedades de conexão suportadas pelo Databricks JDBC Driver, versão 3 e superior.

Propriedades de autenticação e proxy

As seguintes propriedades de autenticação e proxy são suportadas pelo Databricks JDBC Driver. As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`AsyncExecPollInterval`	`200`	O tempo, em milissegundos, entre cada interrogação para o estado 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 as operações assíncronas JDBC são suportadas.
`Auth_Flow`	`0`	O fluxo de autenticação OAuth2 para a conexão do controlador. Esta propriedade é necessária se `AuthMech` estiver `11`.
`Auth_JWT_Alg`	`RS256`	O algoritmo para autenticação JWT de chave privada. Os algoritmos suportados são: RSA: RS256, RS384, RS512, PS256, PS384, PS512 e EC: ES256, ES384, ES512
`Auth_JWT_Key_File`	`null`	O caminho para o arquivo de chave privada (formato PEM) para autenticação JWT.
`Auth_JWT_Key_Passphrase`	`null`	A frase secreta para desencriptar uma chave privada encriptada.
`Auth_KID`	`null`	O identificador de chave (KID) necessário para a autenticação JWT. Isso é obrigatório ao usar a chave privada JWT.
`Auth_RefreshToken`	`null`	O token de atualização do OAuth2 utilizado para obter um novo token de acesso.
`Auth_Scope`	`all-apis`	O escopo de autenticação para fluxos OAuth2.
`AuthMech`	Obrigatório	O mecanismo de autenticação, onde `3` especifica o mecanismo é um token de acesso pessoal do Azure Databricks e `11` especifica que o mecanismo é tokens OAuth 2.0. Propriedades adicionais são necessárias para cada mecanismo. Veja Autenticar o driver.
`AzureTenantId`	`null`	O ID do locatário do Azure para a autenticação específica do Azure.
`CFProxyAuth`	`0`	Se definido como `1`, o driver usa o usuário e a senha de autenticação de 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 estiver definido como `1`.
`CFProxyPort`	`null`	Um inteiro que representa o número da porta proxy a ser usada quando `UseCFProxy` também está definido 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 definidas 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 definidas como `1`.
`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 `<schema>` na URL pelo nome do esquema a ser usado ou definindo a propriedade `ConnSchema` como o nome do esquema a ser usado.
`EnableOIDCDiscovery`	`1`	Se definido como `1`, a URL de descoberta do OpenID Connect será usada.
`EnableTokenCache`	`1`	Se definido como `1`, habilita o cache de tokens OAuth para melhorar o desempenho.
`GoogleCredentialsFile`	`null`	O caminho para o arquivo de chave JSON para autenticação da conta de serviço do Google.
`GoogleServiceAccount`	`null`	Permite a autenticação usando uma conta de serviço do Google.
`OAuth2ClientId`	`null`	O ID do cliente OAuth2 para autenticação. Por padrão, `databricks-sql-jdbc` é usado para AWS, GCP e Azure. Um ID de cliente personalizado é necessário para configurações OAuth avançadas.
`OAuth2ConnAuthAuthorizeEndpoint`	`null`	A URL do ponto de extremidade de autorização usada num fluxo OAuth2.
`OAuth2ConnAuthTokenEndpoint`	`null`	O URL do ponto final do token para o fluxo OAuth2.
`OAuth2RedirectUrlPort`	`8020`	A porta de URL de redirecionamento OAuth2 para fluxos de autenticação baseados em navegador.
`OIDCDiscoveryEndpoint`	`null`	O URL de descoberta do OpenID Connect para recuperar a configuração do OIDC.
`ProxyAuth`	`0`	Se definido como `1`, o driver usa o usuário e a senha de autenticação de 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 estiver definido como `1`.
`ProxyPort`	`null`	Um inteiro que representa o número da porta proxy a ser usada quando `UseProxy` também está definido 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 definidas 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 definidas como `1`.
`TokenCachePassPhrase`	`null`	A senha a ser usada para criptografia de cache de token OAuth U2M.
`UseCFProxy`	`0`	Se definido como `1`, o driver usa as configurações de proxy de busca na nuvem se elas forem fornecidas, caso contrário, use o proxy regular.
`UseJWTAssertion`	`false`	Permite a autenticação JWT de chave privada para casos de uso M2M em que a autenticação de segredo do cliente é restrita.
`UseProxy`	`0`	Se definido como `1`, o driver usa as configurações de proxy fornecidas (por exemplo: `ProxyAuth`, `ProxyHost`, `ProxyPort`, `ProxyPwd`e `ProxyUID`).
`UseSystemProxy`	`0`	Se definido como `1`, o driver usa as configurações de proxy que foram definidas no nível do sistema. Se quaisquer propriedades de proxy adicionais forem definidas na URL de conexão, essas propriedades de proxy adicionais substituirão aquelas que foram definidas no nível do sistema.

Propriedades de configuração do armazenamento confiável SSL

As seguintes propriedades de configuração de armazenamento confiável SSL são suportadas pelo Databricks JDBC Driver. As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`AcceptUndeterminedRevocation`	`0`	Se definido como `1`, aceita certificados com status de revogação indeterminado quando a verificação de revogação de certificados estiver habilitada.
`AllowSelfSignedCerts`	`0`	Se definido como `1`, o driver permite conexões com servidores com certificados SSL autoassinados.
`CheckCertificateRevocation`	`0`	Se definido como `1`, o driver verifica se o certificado SSL foi revogado.
`SSL`	`1`	Se o conector se comunica com o servidor Spark por meio de um soquete habilitado para SSL.
`SSLKeyStore`	`null`	O caminho para o arquivo de armazenamento de chaves SSL para autenticação de certificado de cliente. Por padrão, a autenticação TLS somente de servidor é executada para que um certificado de cliente não seja necessário.
`SSLKeyStorePwd`	`null`	A senha para o arquivo de armazenamento de chaves SSL.
`SSLKeyStoreType`	`JKS`	O tipo de repositório de chaves SSL. Os valores válidos são `JKS`, `PKCS12`, `JCEKS`, `DKS` e `PKCS11`.
`SSLTrustStore`	`null`	O caminho para o arquivo de armazenamento confiável para validação de certificado SSL.
`SSLTrustStorePassword`	`null`	A senha para o arquivo de armazenamento confiável, se ele estiver protegido por senha.
`SSLTrustStoreType`	`JKS`	O tipo de armazenamento confiável, por exemplo, JKS ou PKCS12. Se não for especificado, o padrão do driver será o armazenamento confiável JKS. Os tipos válidos são `JKS`, `PKCS12`e `BCFKS`.
`UseSystemTrustStore`	`0`	Se definido como `1`, o driver usa o armazenamento confiável padrão do sistema para verificação de certificado SSL.

Tipos de repositório de confiança

O driver JDBC suporta os seguintes modos SSL e tipos de armazenamento confiável.

Modo de certificado autoassinado

Para usar o modo de certificado autoassinado, defina a propriedade de ligação AllowSelfSignedCerts=1. Esse modo usa uma fábrica de soquete de confiança que aceita qualquer certificado.

Repositório de confiança personalizado

Para usar um repositório confiável personalizado, especifique um arquivo de armazenamento confiável personalizado na SSLTrustStore propriedade de conexão. Este repositório de confiança é carregado diretamente do caminho especificado e usa os certificados para validação de certificados SSL. Pode ser em JKS, PKCS12 ou outros formatos suportados.

Você deve especificar as seguintes propriedades de conexão adicionais:

SSLTrustStore: Caminho para o arquivo de armazenamento confiável
SSLTrustStorePassword: Senha para o repositório de confiança (se necessário)
SSLTrustStoreType: Tipo de armazenamento confiável (opcional, o padrão é JKS se não for especificado)

Repositório de confiança de propriedade de sistema Java

Para usar o repositório confiável de propriedades do sistema, defina UseSystemTrustStore=1 e certifique-se de não especificar um repositório confiável personalizado. Em vez disso, especifique um armazenamento confiável usando a propriedade javax.net.ssl.trustStoredo sistema Java. Essa propriedade é definida no nível da JVM usando o -D sinalizador, por exemplo:

java -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ...

O driver JDBC primeiro verifica a propriedade javax.net.ssl.trustStoredo sistema Java. Se estiver definido, ele usará esse arquivo de armazenamento confiável em vez do padrão do JDK. Se nenhuma propriedade do sistema estiver definida, usa a loja de confiança padrão do JDK (cacerts), que está localizado em $JAVA_HOME/lib/security/cacerts ou caminho semelhante.

Repositório de confiança padrão da JDK (cacerts)

O JDK vem com um armazenamento confiável integrado chamado cacerts , que contém certificados de Autoridades de Certificação conhecidas, o que permite a verificação de certificados emitidos por essas CAs. Esse repositório de confiança normalmente está localizado em $JAVA_HOME/lib/security/cacerts com a senha padrão "changeit" ou "changeme".

Para usar o armazenamento confiável padrão do JDK, defina UseSystemTrustStore=1 e certifique-se de não especificar um armazenamento confiável personalizado ou um armazenamento confiável de propriedade do sistema Java. Se um armazenamento confiável também for especificado usando a propriedade javax.net.ssl.trustStoredo sistema Java, ele será ignorado, o que garante que o driver use apenas certificados do armazenamento confiável JDK padrão.

Ordem de precedência do repositório de confiança

O driver usa a seguinte ordem de precedência para determinar qual armazenamento confiável usar:

O repositório de confiança personalizado especificado na SSLTrustStore propriedade de conexão
O repositório de confiança especificado na propriedade javax.net.ssl.trustStore do sistema Java (quando UseSystemTrustStore=1)
O repositório de certificados de confiança padrão do JDK (cacerts)

Recomendações de segurança

Para manter sua conexão segura, o Databricks recomenda o seguinte:

Para ambientes de produção:
- Não use o modo de certificado autoassinado (AllowSelfSignedCerts=1).
- Use certificados oficiais assinados pela CA.
- Use UseSystemTrustStore=1 a menos que você precise de um armazenamento confiável personalizado.
Para repositórios de confiança personalizados:
- Utilize ao conectar-se a servidores com certificados que não estão no repositório de confiança padrão.
- Verifique se o armazenamento confiável contém a cadeia de certificados completa.
- Proteja arquivos de armazenamento confiáveis com as permissões apropriadas.

Propriedades da estratégia de repetição

As seguintes propriedades de estratégia de repetição são suportadas pelo Databricks JDBC Driver (OSS). As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`RateLimitRetry`	`1`	Se definido como `1`, habilita a tentativa novamente em erros de limite de taxa.
`RateLimitRetryTimeout`	`120`	Tempo de espera para nova tentativa após atingir o limite de taxa, em segundos.
`TemporarilyUnavailableRetry`	`1`	Se definido como `1`, habilita a repetição em erros temporariamente indisponíveis.
`TemporarilyUnavailableRetryTimeout`	`900`	O tempo limite de repetição para erros temporariamente indisponíveis, em segundos.
`VolumeOperationRetryableHttpCode`	`408,429,500,502,503,504`	A lista separada por vírgulas de códigos HTTP repetíveis de ingestão de volume do Unity Catalog.
`VolumeOperationRetryTimeout`	`15`	O tempo de espera para nova tentativa em solicitações HTTP de ingestão de volume do Unity Catalog, em minutos.

Propriedades de gerenciamento de desempenho e conexão

As seguintes propriedades de gerenciamento de conexão e desempenho são suportadas pelo Databricks JDBC Driver (OSS). As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`CloudFetchThreadPoolSize`	`16`	O tamanho do pool de threads para operações de busca na nuvem.
`DefaultStringColumnLength`	`255`	O número máximo de caracteres que podem ser contidos em colunas STRING para relatórios de metadados.
`HttpConnectionPoolSize`	`100`	O tamanho máximo do pool de conexões HTTP.
`IdleHttpConnectionExpiry`	`60`	O tempo de expiração da conexão HTTP ociosa, em segundos.
`RowsFetchedPerBlock`	`2000000`	O número máximo de linhas que uma consulta retorna de cada vez. Isto aplica-se apenas aos resultados em linha.
`SocketTimeout`	`900`	O tempo limite do soquete para operações de rede, em segundos.

propriedades de configuração do SQL

As seguintes propriedades de configuração SQL são suportadas pelo Databricks JDBC Driver. Eles também são descritos em Parâmetros de configuração. As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`ansi_mode`	`TRUE`	Se é necessário habilitar o comportamento ANSI SQL estrito para determinadas funções e regras de transmissão.
`enable_photon`	`TRUE`	Se o mecanismo de consulta vetorizada Photon deve ser habilitado.
`legacy_time_parser_policy`	`EXCEPTION`	Os métodos usados para analisar e formatar datas e marcadores temporais. Os valores válidos são `EXCEPTION`, `LEGACY`e `CORRECTED`.
`max_file_partition_bytes`	`128m`	O número máximo de bytes para colocar numa única partição ao ler a partir de fontes baseadas em ficheiro. A configuração pode ser qualquer inteiro positivo e, opcionalmente, incluir uma medida como `b` (bytes), `k` ou `kb` (1024 bytes).
`query_tags`	`""` (cadeia vazia)	Uma lista separada por vírgulas de etiquetas chave-valor para anexar a consultas SQL para rastreamento e para análise no `system.query.history`.
`read_only_external_metastore`	`false`	Controla se um metastore externo é tratado como de leitura somente.
`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 deslocamentos 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 registo

As seguintes propriedades de log são suportadas pelo Databricks JDBC Driver. As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`LogFileCount`	`10`	O número máximo de arquivos de log permitidos
`LogFileSize`	`10`	O tamanho máximo permitido do arquivo de log, especificado em MB
`LogLevel`	`OFF`	O nível de log, que é um valor de 0 a 6: 0: Desative todos os registros. 1: Habilite o registo no nível FATAL, que regista eventos de erro muito graves que levarão o conector a abortar. 2: Habilite o registro no nível ERROR, que registra eventos de erro que ainda podem permitir que o conector continue em execução. 3: Habilite o registro no nível WARNING, que registra eventos que podem resultar em um erro se uma ação não for tomada. 4: Habilite o registro no nível INFO, que registra informações gerais que descrevem o progresso do conector. 5: Ative o logging no nível DEBUG, que regista informações detalhadas úteis para resolver problemas do conector. 6: Habilite o registro em log no nível TRACE, que registra toda a atividade do conector. Use essa propriedade para habilitar ou desabilitar o registro em log no conector e para especificar a quantidade de detalhes incluídos nos arquivos de log.
`LogPath`	Para determinar o caminho padrão 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, ou seja, `.`	O caminho completo para a pasta onde o conector guarda ficheiros de registo quando o registo está ativado, como uma cadeia de caracteres. Para garantir que a URL de conexão seja compatível com todos os aplicativos JDBC, escape das barras invertidas (`\`) no caminho do arquivo digitando outra barra invertida. Se o valor `LogPath` for inválido, o conector enviará as informações registradas para o fluxo de saída padrão (System.out).

Ativar e configurar o registo de logs

O driver JDBC suporta os frameworks Simple Logging Facade for Java (SLF4J) e java.util.logging (JUL). O driver usa a estrutura de log JUL por padrão.

Para ativar e configurar o registo para o driver JDBC:

Habilite a estrutura de log que você deseja usar:
- Para registo de logs SLF4J, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER e forneça a implementação de ligação SLF4J (compatível com a versão 2.0.13 e superior do SLF4J) e o respetivo ficheiro de configuração no classpath.
- Para o registo dos logs JUL, configure a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Este é o padrão.
Defina a propriedade LogLevel na cadeia de conexão para o nível desejado de informações a serem incluídas nos arquivos de log.
Defina a propriedade LogPath na cadeia de conexão para o caminho completo para a pasta onde você deseja salvar os arquivos de log.

Por exemplo, a seguinte URL de conexão habilita o nível de log 6 e salva os arquivos de 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.

Outras propriedades de funcionalidades

As propriedades a seguir habilitam recursos no Databricks JDBC Driver. As propriedades são insensíveis a maiúsculas e minúsculas.

Propriedade	Valor predefinido	Descrição
`EnableArrow`	`1`	Se definido como `0`, a serialização de seta para resultados será desativada, o que também desativa o comportamento de busca na nuvem, pois o formato de seta é necessário para o Cloud Fetch.
`EnableComplexDatatypeSupport`	`0`	Se definido como `1`, o suporte para tipos de dados complexos (ARRAYs, STRUCTs, MAPs) como objetos Java nativos em vez de strings está habilitado.
`EnableDirectResults`	`1`	Se definido como `1`, habilita resultados diretos para melhorar o desempenho da consulta.
`EnableGeoSpatialSupport`	`0`	Se definido para `1`, permite o suporte para tipos de dados geoespaciais (GEOMETRIA e GEOGRAFIA) como objetos Java estruturados. Requer `EnableComplexDatatypeSupport=1` e `EnableArrow=1` (A seta está ativada por defeito). Quando desativadas, as colunas geoespaciais são devolvidas como STRING no formato EWKT. Ver funções geoespaciais ST.
`EnableSqlScripting`	`1` ou `true`	Permite o suporte de scripting SQL para blocos de instruções compostas (BEGIN... END) e chamadas de procedimentos armazenados. Disponível na versão do driver 1.0.10 e superiores com o Databricks Runtime 16.3 e superiores. Os procedimentos armazenados requerem Databricks Runtime 17.0 ou superior e driver de versão 3.0.1 ou superior. Use `Statement` ou `PreparedStatement` para chamar procedimentos. `CallableStatement` não é suportado. Para sintaxe e exemplos, veja script SQL.
`EnableMetricViewMetadata`	`0`	Se definido para `1`, permite operações melhoradas de metadados para vistas métricas. Veja como trabalhar com os metadados da vista métrica usando o driver JDBC do Databricks.
`EnableTelemetry`	`0`	Se definido como `1`, a telemetria estará habilitada. Ver Telemetria.
`EnableVolumeOperations`	`1`ou `true`	A propriedade client info para habilitar operações de volume em um fluxo. Consulte Gerenciar arquivos em volumes com o Databricks JDBC Driver. Por padrão, esta propriedade também ativa a REMOVE operação num volume. Importante: Você deve definir isso como uma propriedade de informações do cliente. Fornecê-lo apenas na URL de conexão não habilita operações de volume para um fluxo.
`MaxBatchSize`	`500`	O tamanho máximo do lote para operações em lote e processamento de dados.
`QueryResultCompressionType`	1	Os valores válidos são 0 (para nenhuma compactação) e 1 (para compactação LZ4). O driver substitui automaticamente para 0 (sem compressão) para obter resultados em linha, independentemente da configuração configurada
`UserAgentEntry`	`browser`	A entrada User-Agent deve ser incluída no pedido HTTP. Esse valor está no seguinte formato: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`1`	Se o driver JDBC deve usar o cliente Thrift ou APIs de Execução de Instruções.
`VolumeOperationAllowedLocalPaths`	``	A lista, separada por vírgulas, de caminhos locais permitidos para o download e upload de ficheiros de ingestão de volumes do Unity Catalog. Os caminhos incluem também subdiretórios. Quando não especificado, isso recai para o valor de `StagingAllowedLocalPaths`, em seguida, para uma cadeia de caracteres vazia que não especifica quaisquer restrições. Consulte Gerenciar arquivos usando volumes. Importante: Se a configuração estiver em um ambiente multilocatário (como ferramentas de BI ou serviços de desenvolvedor) e os usuários controlarem a URL JDBC completa, o serviço deverá definir essa propriedade como um local de área restrita ou um caminho inexistente. Isso impede que os usuários escrevam arquivos de arbitragem e interfiram na implantação interna do serviço.

Recolha de telemetria

A telemetria permite que o Databricks simplifique a depuração e forneça solução de problemas oportuna coletando:

Detalhes do ambiente do cliente (versão do driver, tempo de execução, detalhes do sistema operacional)
Configurações de conexão JDBC (exclui quaisquer dados PII)
Medições de latência de operação
Formato do resultado da execução (JSON embutido, Seta, etc.)
Tipos de operação (consulta de execução, consulta de metadados, operações de volume)
Dados de classificação de erros
Contagem de repetições

Observação

A Databricks mantém padrões de privacidade rigorosos, garantindo que não haja coleta de conteúdo de consulta, resultados ou informações de identificação pessoal (PII).

Feedback

Esta página foi útil?

Last updated on 2025-12-15