Propriedades de conexão suportadas

Este artigo descreve as propriedades de conexão compatíveis com o driverDatabricks JDBC (OSS).

Propriedades de autenticação e proxy

As seguintes propriedades de autenticação e proxy 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
AsyncExecPollInterval	200	O tempo em milissegundos entre cada pesquisa para o 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.
Auth_Flow	0	O fluxo de autenticação OAuth2 para a conexão do driver. Essa propriedade é necessária se AuthMech for 11.
Auth_JWT_Key_File	null	O caminho para o arquivo key privado (formato PEM) para autenticação JWT.
Auth_JWT_Alg	RS256	O algoritmo para autenticação privada key JWT. Os algoritmos suportados são: RSA: RS256, RS384, RS512, PS256, PS384, PS512 e EC: ES256, ES384, ES512
Auth_JWT_Key_Passphrase	null	A frase secreta para descriptografar um site privado criptografado key.
Auth_KID	null	O identificador de chave (KID) necessário para a autenticação JWT. Isso é obrigatório ao usar o key JWT privado.
AuthMech	Obrigatório	O mecanismo de autenticação, em que 3 especifica que o mecanismo é um token de acesso pessoal Databricks e 11 especifica que o mecanismo é OAuth 2.0 tokens. Propriedades adicionais são necessárias para cada mecanismo. Consulte Autenticar o driver.
CFProxyAuth	0	Se definido como 1, o driver usa o usuário e a senha de autenticação 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.
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.
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> na URL pelo nome do esquema a ser usado ou definindo a propriedade ConnSchema com o nome do esquema a ser usado.
GoogleServiceAccount	null	Permite a autenticação usando um serviço do Google account.
GoogleCredentialsFile	null	O caminho para o arquivo JSON key para autenticação do serviço Google account.
EnableOIDCDiscovery	1	Se definido como 1, o URL de descoberta do OpenID Connect será usado.
OIDCDiscoveryEndpoint	null	O URL de descoberta do OpenID Connect para recuperar a configuração do OIDC.
Auth_RefreshToken	null	Os tokens OAuth2 refresh usados para recuperar novos tokens de acesso.
OAuth2ConnAuthAuthorizeEndpoint	null	O URL do endpoint de autorização usado em um fluxo OAuth2.
OAuth2ConnAuthTokenEndpoint	null	Os tokens endpoint URL para o fluxo OAuth2.
ProxyAuth	0	Se definido como 1, o driver usa o usuário e a senha de autenticação 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 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 são definidos como 1.
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 alguma propriedade adicional do proxy for definida no URL da conexão, essas propriedades adicionais do proxy substituirão as que foram definidas no nível do sistema.
UseCFProxy	0	Se definido como 1, o driver usa as configurações do proxy de busca na nuvem, se elas forem fornecidas, caso contrário, use o proxy normal.
UseJWTAssertion	false	Habilita a autenticação privada key JWT para casos de uso M2M em que a autenticação secreta do cliente é restrita.

Propriedades de configuração do armazenamento de confiança SSL

As seguintes propriedades de configuração do armazenamento de confiança SSL 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
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.
SSLTrustStore	null	O caminho para o arquivo de armazenamento confiável para validação do certificado SSL.
SSLTrustStorePassword	null	A senha do arquivo de armazenamento 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 usa como padrão o armazenamento de confiança JKS. Os tipos válidos são JKS, PKCS12 e BCFKS.
UseSystemTrustStore	0	Se definido como 1, o driver usará o armazenamento confiável default do sistema para a verificação do certificado SSL.

Tipos de lojas confiáveis

O driver JDBC é compatível com os seguintes modos SSL e tipos de armazenamento de confiança.

Modo de certificado autoassinado

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

Loja fiduciária personalizada

Para usar um armazenamento confiável personalizado, especifique um arquivo de armazenamento confiável personalizado na propriedade de conexão SSLTrustStore. Esse trust store é carregado diretamente do caminho especificado e usa os certificados para validação de certificados SSL. Ele pode estar em JKS, PKCS12 ou outros formatos compatíveis.

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 confiável (se necessário)
• SSLTrustStoreType: Tipo de armazenamento confiável (opcional, padrão para JKS se não for especificado)

Armazenamento confiável de propriedades do sistema Java

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

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

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

JDK default trust store (cacerts)

O JDK vem com um armazenamento de confiança 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 trust store geralmente está localizado em $JAVA_HOME/lib/security/cacerts com uma senha default " changeit" ou "changeme".

Para usar o repositório de confiança do JDK default, defina UseSystemTrustStore=1 e certifique-se de não especificar 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 do sistema Java javax.net.ssl.trustStore, ele será ignorado, o que garante que o driver use apenas certificados do repositório de confiança do JDK default.

Ordem de precedência da Trust Store

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

1. O armazenamento confiável personalizado especificado na propriedade de conexão SSLTrustStore
2. O armazenamento de confiança especificado na propriedade do sistema Java javax.net.ssl.trustStore (quando UseSystemTrustStore=1)
3. O armazenamento de confiança do JDK default (cacerts)

Recomendações de segurança

Para manter sua conexão segura, a 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 uma loja confiável personalizada.

• Para lojas fiduciárias personalizadas:

  • Use ao se conectar a servidores com certificados que não estejam no repositório de confiança default.
  • Certifique-se de que o repositório confiável contenha a cadeia completa de certificados.
  • Proteja arquivos de armazenamento confiável com as permissões apropriadas.

Propriedades de configuração do SQL

As seguintes propriedades de configuração do SQL são compatíveis com o Databricks JDBC Driver (OSS). 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_photon	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 compactados 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 para 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 deslocamentos de zona no formato (+|-) HH, (+|-) HH ou (+|-) HH:mm, 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 Databricks JDBC Driver (OSS). 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: Desative todos os registros. 1: Ativar o registro em log 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:

1. 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.

2. Defina a propriedade LogLevel nas strings de conexão para o nível desejado de informações a serem incluídas nos arquivos log.

3. 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 habilita o nível de registro 6 e salva os arquivos log no diretório C pasta:

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp

4. Reinicie o aplicativo JDBC e reconecte-se ao servidor para aplicar as configurações.

Outras propriedades do recurso

As propriedades a seguir ativam o recurso no driverDatabricks JDBC (OSS). As propriedades não diferenciam maiúsculas de minúsculas.

Propriedade	Valor padrão	Descrição
EnableComplexDatatypeSupport	0	Se definido como 1, o suporte a tipos de dados complexos (ARRAYs, STRUCTs, MAPs) como objetos nativos Java em vez de strings estará ativado.
EnableTelemetry	0	Se definido como 1, a telemetria é ativada. Consulte Telemetria.
UserAgentEntry	browser	A entrada User-Agent 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 Statement Execution.
VolumeOperationAllowedLocalPaths	``	A lista separada por vírgulas de caminhos locais permitidos para downloads e upload de arquivos do UC Volume Ingestion. Os caminhos também incluem subdiretórios. Consulte gerenciar arquivos usando volumes.
VolumeOperationRetryableHttpCode	408,502,503,504	A lista separada por vírgulas de códigos HTTP que podem ser tentados novamente para a ingestão de volumes do Unity Catalog.
VolumeOperationRetryTimeout	15	O tempo limite de nova tentativa em minutos para solicitações HTTP de ingestão de volume do Unity Catalog.

Coleção de telemetria

A telemetria permite que a Databricks simplifique a depuração e ofereça solução de problemas em tempo hábil por meio da coleta:

• 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 de PII)
• operações medições de latência
• Formato do resultado da execução (JSON em linha, Arrow, etc.)
• tipos de operações (consulta de execução, consulta de metadados, operações de volume)
• Dados de classificação de erros
• Contagens de novas tentativas

nota

Databricks mantém padrões rígidos de privacidade, garantindo a não coleta de conteúdo de consultas, resultados ou informações de identificação pessoal (PII).