Partager via

Propriétés de connexion prises en charge

Cet article décrit les propriétés de connexion prises en charge par le pilote JDBC Databricks, version 3 et ultérieure.

propriétés d’authentification et de proxy

Les propriétés d’authentification et de proxy suivantes sont prises en charge par le pilote JDBC Databricks. Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
AsyncExecPollInterval 200 Temps en millisecondes entre chaque sondage pour l’état d’exécution de requête asynchrone. L’option asynchrone fait référence au fait que l’appel RPC utilisé pour exécuter une requête sur Spark est asynchrone. Cela ne signifie pas que les opérations asynchrones JDBC sont prises en charge.
Auth_Flow 0 Flux d’authentification OAuth2 pour la connexion du pilote. Cette propriété est requise si AuthMech est 11.
Auth_JWT_Alg RS256 Algorithme pour l’authentification JWT de clé privée. Les algorithmes pris en charge sont : RSA : RS256, RS384, RS512, PS256, PS384, PS512 et EC : ES256, ES384, ES512
Auth_JWT_Key_File null Chemin d’accès au fichier de clé privée (format PEM) pour l’authentification JWT.
Auth_JWT_Key_Passphrase null Phrase secrète pour déchiffrer une clé privée chiffrée.
Auth_KID null Identificateur de clé (KID) requis pour l’authentification JWT. Cela est obligatoire lors de l’utilisation de la clé privée JWT.
Auth_RefreshToken null Jeton d’actualisation OAuth2 utilisé pour récupérer un nouveau jeton d’accès.
Auth_Scope all-apis Étendue d’authentification pour les flux OAuth2.
AuthMech Obligatoire Le mécanisme d’authentification, où 3 spécifie le mécanisme, est un jeton d’accès personnel Azure Databricks, et 11 spécifie que le mécanisme fait appel à des jetons OAuth 2.0. Des propriétés supplémentaires sont requises pour chaque mécanisme. Consultez Authentifier le pilote.
AzureTenantId null ID de locataire Azure pour l’authentification spécifique à Azure.
CFProxyAuth 0 Si la valeur est 1, le pilote utilise l’utilisateur et le mot de passe d’authentification proxy, représentés par CFProxyUID et CFProxyPwd.
CFProxyHost null Chaîne qui représente le nom de l’hôte proxy qui sera utilisé lorsque UseCFProxy est également défini sur 1.
CFProxyPort null Entier qui représente le numéro du port proxy à utiliser lorsque UseCFProxy est également défini sur 1.
CFProxyPwd null Chaîne qui représente le mot de passe à utiliser pour l’authentification proxy quand CFProxyAuth et UseCFProxy sont également définies sur 1.
CFProxyUID null Chaîne qui représente le nom d’utilisateur à utiliser pour l’authentification proxy quand CFProxyAuth et UseCFProxy sont également définies sur 1.
ConnCatalog ou catalog SPARK Nom du catalogue par défaut à utiliser.
ConnSchema ou schema default Nom du schéma par défaut à utiliser. Cela peut être spécifié en remplaçant <schema> dans l’URL par le nom du schéma à utiliser, ou en définissant la propriété ConnSchema sur le nom du schéma à utiliser.
EnableOIDCDiscovery 1 Si la valeur est 1, l’URL de découverte OpenID Connect est utilisée.
EnableTokenCache 1 Si la valeur est définie 1, permet la mise en cache des jetons OAuth pour améliorer les performances.
GoogleCredentialsFile null Chemin d’accès au fichier de clé JSON pour l’authentification du compte Google Service.
GoogleServiceAccount null Active l’authentification à l’aide d’un compte de service Google.
OAuth2ClientId null ID client OAuth2 pour l’authentification. Par défaut, databricks-sql-jdbc est utilisé pour AWS, GCP et Azure. Un ID client personnalisé est requis pour les configurations OAuth avancées.
OAuth2ConnAuthAuthorizeEndpoint null URL du point de terminaison d’autorisation utilisée dans un flux OAuth2.
OAuth2ConnAuthTokenEndpoint null L'URL du point de terminaison du jeton pour le flux OAuth2.
OAuth2RedirectUrlPort 8020 Port d’URL de redirection OAuth2 pour les processus d’authentification basés sur le navigateur.
OIDCDiscoveryEndpoint null URL de découverte d’OpenID Connect pour récupérer la configuration OIDC.
ProxyAuth 0 Si la valeur est 1, le pilote utilise l’utilisateur et le mot de passe d’authentification proxy, représentés par ProxyUID et ProxyPwd.
ProxyHost null Chaîne qui représente le nom de l’hôte proxy qui sera utilisé lorsque UseProxy est également défini sur 1.
ProxyPort null Entier qui représente le numéro du port proxy à utiliser lorsque UseProxy est également défini sur 1.
ProxyPwd null Chaîne qui représente le mot de passe à utiliser pour l’authentification proxy quand ProxyAuth et UseProxy sont également définies sur 1.
ProxyUID null Chaîne qui représente le nom d’utilisateur à utiliser pour l’authentification proxy quand ProxyAuth et UseProxy sont également définies sur 1.
TokenCachePassPhrase null Phrase secrète à utiliser pour le chiffrement du cache de jeton U2M OAuth.
UseCFProxy 0 Si la valeur est 1, le pilote utilise les paramètres de proxy d’extraction cloud s’ils sont fournis ; autrement, il utilise le proxy standard.
UseJWTAssertion false Active l’authentification JWT de clé privée pour les cas d’utilisation M2M où l’authentification par clé secrète client est restreinte.
UseProxy 0 Si la valeur est 1, le pilote utilise les paramètres de proxy fournis (par exemple : ProxyAuth, ProxyHost, ProxyPort, ProxyPwd et ProxyUID).
UseSystemProxy 0 Si la valeur est 1, le pilote utilise les paramètres de proxy qui ont été définis au niveau du système. Si des propriétés de proxy supplémentaires sont définies dans l’URL de connexion, elles remplacent celles qui ont été définies au niveau du système.

Propriétés de configuration du magasin de confiance SSL

Les propriétés de configuration du magasin de confiance SSL suivantes sont prises en charge par le pilote JDBC Databricks. Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
AcceptUndeterminedRevocation 0 S'il est défini sur 1, accepte les certificats avec un statut de révocation indéterminée lorsque la vérification de la révocation des certificats est activée.
AllowSelfSignedCerts 0 Si la valeur est définie 1, le pilote autorise les connexions aux serveurs avec des certificats SSL auto-signés.
CheckCertificateRevocation 0 Si la valeur est définie 1, le pilote vérifie si le certificat SSL a été révoqué.
SSL 1 Indique si le connecteur communique avec le serveur Spark via un socket compatible SSL.
SSLKeyStore null Chemin d’accès au fichier de magasin de clés SSL pour l’authentification par certificat client. Par défaut, l’authentification TLS uniquement sur le serveur est effectuée afin qu’un certificat client ne soit pas obligatoire.
SSLKeyStorePwd null Mot de passe du fichier keystore SSL.
SSLKeyStoreType JKS Type du magasin de clés SSL. Les valeurs valides sont JKS, , PKCS12JCEKSet DKSPKCS11.
SSLTrustStore null Chemin d’accès au fichier de magasin de confiance pour la validation de certificat SSL.
SSLTrustStorePassword null Mot de passe du fichier du magasin de confiance, s’il est protégé par un mot de passe.
SSLTrustStoreType JKS Type du magasin de confiance, par exemple, JKS ou PKCS12. S'il n'est pas spécifié, par défaut, le pilote utilise le magasin de confiance JKS. Les types valides sont JKS, PKCS12et BCFKS.
UseSystemTrustStore 0 Si 1 est choisi, le pilote utilise le magasin de confiance par défaut du système pour la vérification du certificat SSL.

Types de magasin de confiance

Le pilote JDBC prend en charge les modes SSL et les types de magasin de confiance suivants.

Mode de certificat auto-signé

Pour utiliser le mode de certificat auto-signé, définissez la propriété AllowSelfSignedCerts=1de connexion . Ce mode utilise une fabrique de sockets qui accepte tous les certificats.

Magasin de confiance personnalisé

Pour utiliser un magasin de confiance personnalisé, spécifiez un fichier de magasin de confiance personnalisé dans la propriété de connexion SSLTrustStore. Ce magasin de confiance est chargé directement à partir du chemin spécifié et utilise les certificats pour la validation SSL. Il peut être dans JKS, PKCS12 ou d’autres formats pris en charge.

Vous devez spécifier les propriétés de connexion supplémentaires suivantes :

  • SSLTrustStore : chemin d’accès au fichier de magasin de confiance
  • SSLTrustStorePassword: Mot de passe pour le magasin de confiance (si nécessaire)
  • SSLTrustStoreType: type de magasin de confiance (facultatif, valeur par défaut JKS s’il n’est pas spécifié)

Magasin de confiance des propriétés système Java

Pour utiliser le magasin de confiance des propriétés système, définissez UseSystemTrustStore=1 et veillez à ne pas spécifier de magasin de confiance personnalisé. Au lieu de cela, spécifiez un magasin de confiance à l’aide de la propriété système Java javax.net.ssl.trustStore. Cette propriété est définie au niveau JVM à l’aide de l’indicateur -D , par exemple :

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

Le pilote JDBC vérifie d’abord la propriété système Java javax.net.ssl.trustStore. S’il est défini, il utilise ce fichier de magasin de confiance au lieu de celui par défaut du JDK. Si aucune propriété système n’est définie, utilise le magasin d’approbations par défaut du JDK (cacerts), qui est situé à $JAVA_HOME/lib/security/cacerts ou un chemin similaire.

Magasin d’approbation par défaut JDK (cacerts)

Le JDK est fourni avec un magasin d’approbation intégré appelé cacerts qui contient des certificats provenant d’autorités de certification connues, ce qui permet de vérifier les certificats émis par ces autorités de certification. Ce magasin de confiance se trouve généralement dans $JAVA_HOME/lib/security/cacerts, avec pour mot de passe par défaut « changeit » ou « changeme ».

Pour utiliser le magasin d’approbations par défaut JDK, définissez UseSystemTrustStore=1 et assurez-vous que vous ne spécifiez pas de magasin d’approbations personnalisé ou d’un magasin d’approbations de propriétés système Java. Si un magasin d’approbations est également spécifié à l’aide de la propriété javax.net.ssl.trustStoresystème Java, il est ignoré, ce qui garantit que le pilote utilise uniquement les certificats du magasin d’approbation JDK par défaut.

Ordre de priorité des magasins de confiance

Le pilote utilise l’ordre de priorité suivant pour déterminer quel magasin de confiance utiliser :

  1. Magasin de confiance personnalisé spécifié dans la propriété de connexion SSLTrustStore
  2. Magasin de confiance spécifié dans la propriété système Java javax.net.ssl.trustStore (quand UseSystemTrustStore=1)
  3. Magasin de confiance par défaut du JDK (cacerts)

Recommandations en matière de sécurité

Pour sécuriser votre connexion, Databricks recommande les éléments suivants :

  • Pour les environnements de production :

    • N’utilisez pas le mode de certificat auto-signé (AllowSelfSignedCerts=1).
    • Utilisez des certificats signés par l’autorité de certification officielle.
    • Utilisez UseSystemTrustStore=1, sauf si vous avez besoin d’un magasin de confiance personnalisé.

  • Pour les magasins de confiance personnalisés :

    • Utilisez cette option lors de la connexion à des serveurs avec des certificats non dans le magasin d’approbations par défaut.
    • Vérifiez que le magasin de confiance contient la chaîne de certificats complète.
    • Protégez les fichiers du magasin de confiance avec les autorisations appropriées.

Propriétés de la stratégie de nouvelle tentative

Les propriétés de stratégie de reprise suivantes sont prises en charge par le pilote JDBC Databricks (OSS). Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
RateLimitRetry 1 Si la valeur est définie sur 1, active les réessais sur les erreurs de limite de débit.
RateLimitRetryTimeout 120 Délai d'expiration pour les nouvelles tentatives en cas de limitation de débit, exprimé en secondes.
TemporarilyUnavailableRetry 1 Si la valeur est définie à 1, active une nouvelle tentative en cas d'erreurs temporairement non disponibles.
TemporarilyUnavailableRetryTimeout 900 Délai d’expiration des nouvelles tentatives pour les erreurs dues à une indisponibilité temporaire, en secondes.
VolumeOperationRetryableHttpCode 408,429,500,502,503,504 Liste séparée par des virgules de codes HTTP pouvant faire l’objet d’une nouvelle tentative pour l’ingestion de volumes Unity Catalog.
VolumeOperationRetryTimeout 15 Délai d’expiration des nouvelles tentatives pour les requêtes HTTP d’ingestion de volume du catalogue Unity, en minutes.

Propriétés de gestion des performances et des connexions

Les propriétés de gestion des performances et des connexions suivantes sont prises en charge par le pilote JDBC Databricks (OSS). Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
CloudFetchThreadPoolSize 16 Taille du pool de threads pour les opérations de récupération cloud.
DefaultStringColumnLength 255 Nombre maximal de caractères pouvant être contenus dans les colonnes STRING pour la création de rapports de métadonnées.
HttpConnectionPoolSize 100 Taille maximale du pool de connexions HTTP.
IdleHttpConnectionExpiry 60 Heure d’expiration de la connexion HTTP inactive, en secondes.
RowsFetchedPerBlock 2000000 Nombre maximal de lignes retournées par une requête à la fois. Cela s’applique uniquement aux résultats inline.
SocketTimeout 900 Délai d’expiration du socket pour les opérations réseau, en secondes.

propriétés de configuration SQL

Les propriétés de configuration SQL suivantes sont prises en charge par le pilote JDBC Databricks. Elles sont également décrites dans Paramètres de configuration. Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
ansi_mode TRUE Indique s’il faut activer un comportement strict conforme à l'ANSI SQL pour certaines fonctions et règles de conversion.
enable_photon TRUE Indique s’il faut activer le moteur de requête vectorisée Photon.
legacy_time_parser_policy EXCEPTION Méthodes utilisées pour analyser et mettre en forme les dates et les horodatages. Les valeurs valides sont EXCEPTION, LEGACYet CORRECTED.
max_file_partition_bytes 128m Le nombre maximal d’octets à empaqueter dans une même partition lors de la lecture de sources basées sur des fichiers. Le paramètre peut être un entier positif, et éventuellement inclure une mesure telle que b (octets), k ou kb (1024 octets).
query_tags "" (chaîne vide) Liste séparée par des virgules de balises clé-valeur à attacher aux requêtes SQL pour le suivi et l’analytique dans system.query.history.
read_only_external_metastore false Contrôle si un metastore externe est traité comme étant en lecture seule.
statement_timeout 172800 Définit un délai d’expiration d’instruction SQL compris entre 0 et 172 800 secondes.
timezone UTC Définissez le fuseau horaire local. ID de région au format area/city, tel que Amérique/Los_Angeles, ou décalages de zone au format (+|-)HH, (+|-)HH:mm ou (+|-)HH:mm:ss, par exemple -08, +01:00 ou -13:33:33. En outre, UTC est pris en charge comme alias pour +00:00
use_cached_result true Indique si Databricks SQL met en cache et réutilise les résultats dans la mesure du possible.

Propriétés de journalisation

Les propriétés de journalisation suivantes sont prises en charge par le pilote JDBC Databricks. Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
LogFileCount 10 Nombre maximal de fichiers journaux autorisés
LogFileSize 10 Taille maximale autorisée du fichier journal, spécifiée en Mo
LogLevel OFF Niveau de journalisation, qui est une valeur comprise entre 0 et 6 :
  • 0 : Désactiver toute journalisation.
  • 1 : Activez la journalisation au niveau FATAL, qui enregistre des événements d’erreur très graves qui entraînent l'interruption du connecteur.
  • 2 : Activez la journalisation au niveau d’ERREUR, qui enregistre les événements d’erreur susceptibles de permettre au connecteur de continuer à s’exécuter.
  • 3 : Activez la journalisation au niveau AVERTISSEMENT, qui journalise les événements susceptibles d’entraîner une erreur si l’action n’est pas effectuée.
  • 4 : Activez la journalisation au niveau INFO, qui journalise les informations générales qui décrivent la progression du connecteur.
  • 5 : Activez la journalisation au niveau DEBUG, qui enregistre des informations détaillées utiles pour le débogage du connecteur.
  • 6 : Activez la journalisation au niveau TRACE, qui journalise toutes les activités du connecteur.

Utilisez cette propriété pour activer ou désactiver la journalisation dans le connecteur, et spécifier la quantité de détails inclus dans les fichiers journaux.
LogPath Pour déterminer le chemin par défaut des journaux, le pilote utilise la valeur définie pour ces propriétés système, dans cet ordre de priorité :
  • user.dir
  • java.io.tmpdir
  • le répertoire courant, en d'autres termes .
 Chemin d’accès complet au dossier dans lequel le connecteur enregistre les fichiers journaux lorsque la journalisation est activée, sous forme de chaîne. Pour vous assurer que l’URL de connexion est compatible avec toutes les applications JDBC, éliminez les barres obliques inverses (\) dans votre chemin de fichier en tapant une autre barre oblique inverse.
Si la LogPath valeur n’est pas valide, le connecteur envoie les informations journalisées au flux de sortie standard (System.out).

Activez et configurez la journalisation

Le pilote JDBC prend en charge les frameworks SLF4J (Simple Logging Façade for Java) et java.util.logging (JUL ). Le pilote utilise l’infrastructure de journalisation JUL par défaut.

Pour activer et configurer la journalisation pour le pilote JDBC :

  1. Activez l’infrastructure de journalisation que vous souhaitez utiliser :

    • Pour la journalisation SLF4J, définissez la propriété -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER système et fournissez l’implémentation de liaison SLF4J (compatible avec SLF4J version 2.0.13 et ultérieure) et le fichier de configuration correspondant dans le classpath.
    • Pour la journalisation JUL, définissez la propriété système -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER. Il s’agit de la valeur par défaut.

  2. Définissez la LogLevel propriété de la chaîne de connexion au niveau d’informations souhaité pour inclusion dans les fichiers journaux.

  3. Définissez la propriété LogPath sur la chaîne de connexion sur le chemin d’accès complet du dossier dans lequel vous souhaitez enregistrer les fichiers journaux.

    Par exemple, l’URL de connexion suivante active le niveau de journalisation 6 et enregistre les fichiers journaux dans le dossier C :temp :

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

  4. Redémarrez votre application JDBC et reconnectez-vous au serveur pour appliquer les paramètres.

Autres propriétés de fonctionnalité

Les propriétés suivantes activent les fonctionnalités dans le pilote JDBC Databricks. Les propriétés ne respectent pas la casse.

Propriété Valeur par défaut Descriptif
EnableArrow 1 Si la valeur est définie 0, la sérialisation des flèches pour les résultats est désactivée, ce qui désactive également le comportement d’extraction cloud, car le format flèche est nécessaire pour Cloud Fetch.
EnableComplexDatatypeSupport 0 Si la valeur est 1, la prise en charge des types de données complexes (ARRAYs, STRUCTs, MAPs) en tant qu’objets Java natifs au lieu de chaînes est activée.
EnableDirectResults 1 Si la valeur est définie 1, active les résultats directs pour améliorer les performances des requêtes.
EnableGeoSpatialSupport 0 Si la valeur est définie 1, permet la prise en charge des types de données géospatiales (GEOMETRY et GEOGRAPHY) en tant qu’objets Java structurés. Nécessite EnableComplexDatatypeSupport=1 et EnableArrow=1 (La flèche est activée par défaut). En cas de désactivation, les colonnes géospatiales sont retournées sous forme de chaîne au format EWKT. Consultez les fonctions géospatiales ST.
EnableSqlScripting 1 ou true Active la prise en charge des scripts SQL pour les blocs d’instructions composés (BEGIN... END) et appels de procédure stockée. Disponible dans la version 1.0.10 et ultérieure du pilote avec Databricks Runtime 16.3 et versions ultérieures.
Les procédures stockées nécessitent Databricks Runtime 17.0 et versions ultérieures ainsi que la version 3.0.1 du pilote et ultérieures. Utilisez Statement ou PreparedStatement pour appeler des procédures. CallableStatement n’est pas pris en charge. Pour obtenir une syntaxe et des exemples, consultez script SQL.
EnableMetricViewMetadata 0 Si la valeur est définie 1, active les opérations de métadonnées améliorées pour les vues de métriques. Consultez Utiliser les métadonnées d’affichage des métriques à l’aide du pilote JDBC Databricks.
EnableTelemetry 0 Si la valeur est définie 1, la télémétrie est activée. Voir Télémétrie.
EnableVolumeOperations 1ou true Propriété d’informations client pour activer les opérations de volume sur un flux. Consultez Gérer les fichiers dans des volumes avec le pilote JDBC Databricks. Par défaut, cette propriété active également l’opération REMOVE sur un volume.
Important: Vous devez définir cette propriété en tant que propriété d’informations client. Le fait de le fournir uniquement dans l’URL de connexion n’active pas les opérations de volume pour un flux.
MaxBatchSize 500 Taille maximale du lot pour les opérations de traitement par lots et les données.
QueryResultCompressionType 1 Les valeurs valides sont 0 (pour aucune compression) et 1 (pour la compression LZ4). Le pilote passe automatiquement à 0 (aucune compression) pour les résultats inline, quel que soit le paramètre configuré
UserAgentEntry browser Entrée User-Agent à inclure dans la requête HTTP. Cette valeur est au format suivant : [ProductName]/[ProductVersion] [Comment]
UseThriftClient 1 Si le pilote JDBC doit utiliser les API Thrift client ou les APIs d'exécution d'instructions.
VolumeOperationAllowedLocalPaths `` Liste séparée par des virgules des chemins locaux autorisés pour le téléchargement et l'upload des fichiers d'ingestion de volume du Unity Catalog. Les chemins incluent également des sous-répertoires. Lorsqu’elle n’est pas spécifiée, elle revient à la valeur de StagingAllowedLocalPaths, puis à une chaîne vide qui ne spécifie aucune restriction. Consultez Gérer les fichiers à l’aide de volumes.
Important: Si la configuration se trouve dans un environnement multilocataire (par exemple, des outils décisionnels ou des services de développement) et que les utilisateurs contrôlent l’URL JDBC complète, le service doit définir cette propriété sur un emplacement de bac à sable ou un chemin inexistant. Cela empêche les utilisateurs d’écrire des fichiers arbitraty et d’interférer avec le déploiement interne du service.

Collecte de données de télémétrie

La télémétrie permet à Databricks de simplifier le débogage et de fournir une résolution des problèmes en temps voulu en collectant :

  • Détails de l’environnement client (version du pilote, runtime, détails du système d’exploitation)
  • Configurations de connexion JDBC (exclut toutes les données PII)
  • Mesures de latence des opérations
  • Format de résultat d’exécution (JSON inline, Arrow, etc.)
  • Types d’opérations (requête d’exécution, requête de métadonnées, opérations de volume)
  • Données de classification des erreurs
  • Nombre de nouvelles tentatives

Remarque

Databricks maintient des normes strictes de confidentialité, garantissant qu’il n’y a aucune collecte de contenu de requête, de résultats ou d’informations personnelles identifiables (IIP).

  • Last updated on