Propriedades de conexão suportadas

Este artigo descreve as propriedades de conexão compatíveis com o Driver JDBC do Databricks, versão 3 e superior.

Propriedades de autenticação e proxy

As propriedades de autenticação e proxy a seguir são suportadas pelo Driver JDBC do Databricks. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`AsyncExecPollInterval`	`200`	O tempo em milissegundos entre cada sondagem para o status de execução da consulta assíncrona. Assíncrona refere-se ao fato de que a chamada RPC usada para executar uma consulta no Spark é assíncrona. Isso não significa que há suporte para operações assíncronas de JDBC.
`Auth_Flow`	`0`	O fluxo de autenticação OAuth2 para a conexão do driver. Essa propriedade será necessária se `AuthMech` for `11`.
`Auth_JWT_Alg`	`RS256`	O algoritmo para autenticação JWT de chave privada. Os algoritmos com suporte 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 descriptografar uma chave privada criptografada.
`Auth_KID`	`null`	O KID (Identificador de Chave) necessário para autenticação JWT. Isso é obrigatório ao usar a chave privada JWT.
`Auth_RefreshToken`	`null`	O token de atualização OAuth2 usado para recuperar 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 que o mecanismo é um token de acesso pessoal do Azure Databricks e `11` especifica que o mecanismo são tokens OAuth 2.0. Propriedades adicionais são necessárias para cada mecanismo. Veja Autenticação do driver.
`AzureTenantId`	`null`	A ID do locatário do Azure para autenticação específica do Azure.
`CFProxyAuth`	`0`	Se definido como `1`, o driver usará o usuário de autenticação de proxy e a senha, representados por `CFProxyUID` e `CFProxyPwd`.
`CFProxyHost`	`null`	Uma cadeia de caracteres que representa o nome do host do proxy a ser usado quando `UseCFProxy` também for definido como `1`.
`CFProxyPort`	`null`	Um inteiro que representa o número da porta do proxy a ser usada quando `UseCFProxy` também for 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 forem definidos 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 forem definidos 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 o `<schema>` no 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 do Google Service.
`GoogleServiceAccount`	`null`	Habilita a autenticação usando uma conta de serviço do Google.
`OAuth2ClientId`	`null`	A ID do cliente OAuth2 para autenticação. Por padrão, `databricks-sql-jdbc` é usado para AWS, GCP e Azure. Uma ID de cliente personalizada é necessária para configurações avançadas do OAuth.
`OAuth2ConnAuthAuthorizeEndpoint`	`null`	A URL do ponto de extremidade da autorização usada em um fluxo OAuth2.
`OAuth2ConnAuthTokenEndpoint`	`null`	A URL do ponto de extremidade 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`	A URL de descoberta do OpenID Connect para recuperar a configuração do OIDC.
`ProxyAuth`	`0`	Se definido como `1`, o driver usará o usuário de autenticação de proxy e a senha, representados por `ProxyUID` e `ProxyPwd`.
`ProxyHost`	`null`	Uma cadeia de caracteres que representa o nome do host do proxy a ser usado quando `UseProxy` também for definido como `1`.
`ProxyPort`	`null`	Um inteiro que representa o número da porta do proxy a ser usada quando `UseProxy` também for 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 forem definidos 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 forem definidos como `1`.
`TokenCachePassPhrase`	`null`	A frase secreta para usar na criptografia do cache de token OAuth U2M.
`UseCFProxy`	`0`	Se definido como `1`, o driver usará as configurações de proxy de busca de nuvem se forem fornecidas, caso contrário, use o proxy regular.
`UseJWTAssertion`	`false`	Habilita 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 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 as propriedades de proxy adicionais forem definidas no 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 repositório de confiança SSL

As propriedades de configuração do repositório de confiança SSL a seguir são compatíveis com o Driver JDBC do Databricks. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`AcceptUndeterminedRevocation`	`0`	Se definido como `1`, aceita certificados com status de revogação indeterminado quando a verificação de revogação de certificado está 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 verificará 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 repositório de chaves SSL para autenticação de certificado do cliente. Por padrão, a autenticação TLS de servidor único é realizada, portanto, um certificado de cliente não é necessário.
`SSLKeyStorePwd`	`null`	A senha do arquivo de repositório de chaves SSL.
`SSLKeyStoreType`	`JKS`	O tipo do repositório de chaves SSL. Os valores válidos são`JKS`, , `PKCS12JCEKSDKS`e `PKCS11`.
`SSLTrustStore`	`null`	O caminho para o arquivo do repositório confiável para a validação de certificado SSL.
`SSLTrustStorePassword`	`null`	A senha do arquivo do repositório confiável, se ele estiver protegido por senha.
`SSLTrustStoreType`	`JKS`	O tipo do repositório confiável, por exemplo, JKS ou PKCS12. Se não for especificado, o driver usará como padrão o repositório de confiança do JKS. Os tipos válidos são `JKS`, `PKCS12`e `BCFKS`.
`UseSystemTrustStore`	`0`	Se definido como `1`, o driver usará o repositório de confiança padrão do sistema para verificação de certificado SSL.

Tipos de repositório de confiança

O driver JDBC dá suporte aos seguintes modos SSL e tipos de repositório de confiança.

Modo de certificado autoassinado

Para usar o modo de certificado autoassinado, defina a propriedade AllowSelfSignedCerts=1de conexão. Esse modo usa uma fábrica de soquetes confiável que aceita qualquer certificado.

Repositório confiável personalizado

Para usar um repositório de confiança personalizado, especifique um arquivo personalizado de repositório de confiança na propriedade de conexão SSLTrustStore. Esse repositório confiável é carregado diretamente do caminho especificado e usa os certificados para a validação de certificado SSL. Ele pode estar no JKS, PKCS12 ou em outros formatos com suporte.

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 repositório de confiança (opcional, padrão para JKS, se não especificado)

Repositório confiável de propriedade do sistema Java

Para usar o repositório de confiança da propriedade do sistema, defina UseSystemTrustStore=1 e certifique-se de que você não especifique um repositório de confiança personalizado. Em vez disso, especifique um repositório de confiança 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 verifica primeiro a propriedade javax.net.ssl.trustStoredo sistema Java. Se estiver definido, ele usará esse arquivo de repositório de confiança em vez do padrão do JDK. Se nenhuma propriedade do sistema estiver definida, usará o repositório de confiança padrão do JDK (cacerts), que é localizado no caminho $JAVA_HOME/lib/security/cacerts ou similar.

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

O JDK vem com um repositório de confiança interno chamado cacerts que contém certificados de autoridades de certificação conhecidas, que permite a verificação de certificados emitidos por esses ACs. Esse repositório de confiança normalmente está localizado $JAVA_HOME/lib/security/cacerts com uma senha padrão "changeit" ou "changeme".

Para usar o repositório de confiança padrão do JDK, defina UseSystemTrustStore=1 e verifique se você não especifica um repositório de confiança personalizado ou um repositório de confiança de propriedade do sistema Java. Se um repositório de confiança 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 repositório de confiança JDK padrão.

Ordem de precedência do repositório confiável

O driver usa a seguinte ordem de precedência para determinar qual repositório de confiança usar:

O repositório confiável personalizado especificado na propriedade de conexão SSLTrustStore
O repositório confiável especificado na propriedade javax.net.ssl.trustStore do sistema Java (quando UseSystemTrustStore=1)
O repositório 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 por Autoridade Certificadora (AC).
- Use UseSystemTrustStore=1 a menos que você precise de um repositório de confiança personalizado.
Para repositórios de confiança personalizados:
- Use ao se conectar a servidores com certificados que não estão no repositório de confiança padrão.
- Verifique se o repositório de confiança contém a cadeia de certificados completa.
- Proteja arquivos de repositório de confiança com permissões apropriadas.

Propriedades da estratégia de repetição

As propriedades de estratégia de repetição a seguir são compatíveis com o Databricks JDBC Driver (OSS). As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`RateLimitRetry`	`1`	Se definido como `1`, habilita a repetição em erros de limite de taxa.
`RateLimitRetryTimeout`	`120`	Tempo de espera para nova tentativa após exceder 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 de espera para nova tentativa em casos de 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 para ingestão de volume do Catálogo do Unity.
`VolumeOperationRetryTimeout`	`15`	O tempo limite para tentativas de solicitações HTTP de ingestão de volume do Unity Catalog, em minutos.

Propriedades de gerenciamento de conexão e desempenho

As seguintes propriedades de desempenho e gerenciamento de conexão são compatíveis com o Driver JDBC (OSS) do Databricks. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	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. Isso só se aplica 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 propriedades de configuração do SQL a seguir são compatíveis com o Driver JDBC do Databricks. Elas também são descritas nos Parâmetros de configuração. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`ansi_mode`	`TRUE`	Indica se o comportamento estrito do ANSI SQL deve ser habilitado para certas funções e regras de conversão.
`enable_photon`	`TRUE`	Se deseja habilitar o mecanismo de consulta vetorizado Photon.
`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 as fontes baseadas em arquivo. A configuração pode ser qualquer inteiro positivo e, opcionalmente, incluir uma medida como `b` (bytes), `k` ou `kb` (1024 bytes).
`query_tags`	`""` (cadeia de caracteres vazia)	Uma lista separada por vírgulas de marcas chave-valor a serem anexadas a consultas SQL para acompanhamento e análise em `system.query.history`.
`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 formulário `area/city`, como América/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` há suporte 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 em log

As propriedades de log a seguir são compatíveis com o Driver JDBC do Databricks. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`LogFileCount`	`10`	O número máximo de arquivos de log permitidos
`LogFileSize`	`10`	O tamanho máximo de arquivo de log permitido, especificado em MB
`LogLevel`	`OFF`	O nível de registros em log, que é um valor de 0 a 6: 0: desabilita todo o registro em log. 1: Habilitar o registro em log no nível FATAL, que registra eventos de erro muito graves que farão com que o conector seja anulado. 2: Habilite o log no nível ERROR, que registra eventos de erro que ainda podem permitir que o conector continue em execução. 3: Habilite o registro em log no nível de WARNING, que registra eventos que podem resultar em um erro se a ação não for executada. 4: Habilitar o registro em log no nível INFO, que registra informações gerais que descrevem o progresso do conector. 5: habilita o registro em log no nível DEBUG, que registra informações detalhadas que são úteis para depurar o conector. 6: Habilitar o registro em log no nível TRACE, que registra todas as atividades do conector. Use essa propriedade para habilitar ou desabilitar o registro em log no conector e especificar a quantidade de detalhes incluídos nos arquivos de log.
`LogPath`	Para determinar o caminho padrão para logs, o driver usa o conjunto de valores 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 onde o conector salva arquivos de log quando o registro em log está habilitado, como uma cadeia de caracteres. Para garantir que a URL de conexão seja compatível com todos os aplicativos JDBC, faça o 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).

Habilitar e configurar o registro de logs

O driver JDBC dá suporte às estruturas SLF4J (Simple Logging Facade for Java) e java.util.logging (JUL). O driver usa a estrutura de registro em log JUL por padrão.

Para habilitar e configurar o registro em log no driver JDBC:

Habilite a estrutura de registro em log que você deseja usar:
- Para registro em log SLF4J, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER e forneça a implementação de associação SLF4J (compatível com o SLF4J versão 2.0.13 e superior) e o arquivo de configuração correspondente no classpath.
- Para registro em log JUL, defina a propriedade do sistema -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Esse é 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 como o caminho completo para a pasta em que você deseja salvar 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 seu aplicativo JDBC e reconecte-se ao servidor para aplicar as configurações.

Outras propriedades de recurso

As propriedades a seguir habilitam recursos no Driver JDBC do Databricks. As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
`EnableArrow`	`1`	Se definido como , a `0`serialização de seta para resultados está desabilitada, o que também desabilita o comportamento de Busca de 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 cadeias de caracteres está habilitado.
`EnableDirectResults`	`1`	Se definido como `1`, habilita os resultados diretos para melhorar o desempenho da consulta.
`EnableGeoSpatialSupport`	`0`	Se definido como `1`, habilita o suporte para tipos de dados geoespaciais (GEOMETRY e GEOGRAPHY) como objetos Java estruturados. Requer `EnableComplexDatatypeSupport=1` e `EnableArrow=1` (a seta está habilitada por padrão). Quando desabilitadas, as colunas geoespaciais são retornadas como STRING no formato EWKT. Consulte funções geoespaciais ST.
`EnableSqlScripting`	`1` ou `true`	Habilita o suporte ao script SQL para blocos de instrução composta (BEGIN... END) e chamadas de procedimento armazenado. Disponível no driver versão 1.0.10 e superior com o Databricks Runtime 16.3 e superior. Os procedimentos armazenados exigem o Databricks Runtime 17.0 e superior e o driver versão 3.0.1 e superior. Use `Statement` ou `PreparedStatement` para chamar procedimentos. Não há suporte para `CallableStatement`. Para obter sintaxe e exemplos, consulte o script SQL.
`EnableMetricViewMetadata`	`0`	Se definido como `1`, habilita operações de metadados aprimoradas para exibições de métrica. Consulte Trabalhar com metadados de exibição de métrica usando o Driver JDBC do Databricks.
`EnableTelemetry`	`0`	Se definido como `1`, a telemetria está habilitada. Consulte Telemetria.
`EnableVolumeOperations`	`1`ou `true`	A propriedade de dados do cliente para habilitar operações relativas a volume em um fluxo. Consulte Gerenciar arquivos em volumes com o Driver JDBC do Databricks. Por padrão, essa propriedade também habilita a operação REMOVE em um volume. Importante: Você deve definir isso como uma propriedade de informações do cliente. Fornecer isso somente na URL de conexão não permite 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 (sem compactação) e 1 (para compactação LZ4). O driver substitui automaticamente para 0 (sem compactação) para resultados embutidos, independentemente da configuração configurada
`UserAgentEntry`	`browser`	A entrada Agente do Usuário a ser incluída na solicitação HTTP. Esse valor está no seguinte formato: `[ProductName]/[ProductVersion] [Comment]`
`UseThriftClient`	`1`	Se o driver JDBC deve usar o cliente Thrift ou as APIs de Execução de Instrução.
`VolumeOperationAllowedLocalPaths`	``	A lista, separada por vírgulas, dos caminhos locais permitidos para o download e upload de arquivos de ingestão de volume do Unity Catalog. Os caminhos também incluem subdiretórios. Quando não especificado, isso volta para o valor de `StagingAllowedLocalPaths`, em seguida, para uma cadeia de caracteres vazia que não especifica nenhuma restrição. 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 gravem arquivos arbitraty e interfiram na implantação interna do serviço.

Coleção 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, runtime, detalhes do sistema operacional)
Configurações de conexão JDBC (exclui quaisquer dados PII)
Medidas de latência da operação
Formato de resultado de 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 erro
Contagens de repetição

Observação

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

Comentários

Esta página foi útil?

Last updated on 2025-12-15