Aller au contenu principal

Connexion JDBC

remarque

Cette fonctionnalité est disponible en Préversion publique pour Databricks Runtime 18.1 et DBSQL 2025.40 et versions ultérieures. Pour les SQL Warehouse, vous devez également activer la préversion Activer la mise en réseau pour les charges de travail isolées dans les SQL Warehouse Serverless .

Databricks prend en charge la connexion aux bases de données externes à l'aide de JDBC. Vous pouvez utiliser une connexion JDBC Unity Catalog pour lire et écrire dans une source de données avec l'API Spark Data Source ou l'API SQL de Remote Query de Databricks. La connexion JDBC est un objet sécurisable dans Unity Catalog qui spécifie le Driver JDBC, le chemin d'URL et les identifiants pour accéder à une base de données externe. La connexion JDBC est prise en charge sur l'ensemble des types de compute Unity Catalog, y compris serverless, les clusters standard, les clusters dédiés et Databricks SQL.

Avantages de l'utilisation d'une connexion JDBC.

  • Lire et écrire sur les sources de données à l'aide de JDBC avec l'API Spark Data Source.
  • Lecture à partir de sources de données avec JDBC en utilisant l'API SQL Remote Query.
  • Accès réglementé à la source de données à l'aide d'une connexion Unity Catalog.
  • Créez la connexion une fois et réutilisez-la sur n'importe quel compute Unity Catalog.
  • Stable pour les mises à niveau de Spark et compute.
  • Les identifiants de connexion sont masqués pour l'utilisateur qui effectue la requête.

JDBC contre la fédération de requêtes

JDBC est complémentaire de la fédération de query. Databricks recommande de choisir la fédération de query pour les raisons suivantes :

  • La fédération de query fournit des contrôles d'accès précis et une gouvernance au niveau des tables à l'aide d'un catalogue étranger. La connexion JDBC Unity Catalog fournit une gouvernance uniquement au niveau de la connexion.
  • La fédération de requêtes pousse les requêtes Spark pour des performances de requête optimales.
remarque

La fédération de query prend en charge de nombreuses bases de données populaires, y compris Oracle, MySQL, PostgreSQL, SQL Server, et Snowflake. Si votre base de données est prise en charge, Databricks recommande d'utiliser la fédération de requêtes au lieu d'une connexion JDBC. Consultez Lakehouse Federation pour la liste complète des bases de données prises en charge.

Cependant, choisissez d'utiliser une connexion JDBC Unity Catalog dans les scénarios suivants :

  • Votre base de données n'est pas prise en charge par la fédération de query.
  • Vous souhaitez utiliser un Driver JDBC spécifique.
  • Vous devez écrire dans la source de données à l'aide de Spark (la fédération de requêtes ne prend pas en charge les écritures).
  • Vous avez besoin de plus de flexibilité, de performances et de contrôle de la parallélisation grâce aux options de l’API Spark Data Source.
  • Vous souhaitez transmettre les query SQL sources avec l'option Spark query.

Pourquoi utiliser JDBC par rapport aux sources de données PySpark ?

Les sources de données PySpark sont une alternative à la source de données JDBC Spark.

Utilisez une connexion JDBC :

  • Si vous souhaitez utiliser la prise en charge JDBC intégrée de Spark.
  • Si vous souhaitez utiliser un driver JDBC prêt à l'emploi qui existe déjà.
  • Si vous avez besoin d'une gouvernance Unity Catalog au niveau de la connexion.
  • Si vous souhaitez vous connecter à partir de n'importe quel type de compute Unity Catalog : Serverless, standard, dédié, API SQL.
  • Si vous souhaitez utiliser votre connexion avec les APIs Python, Scala et SQL.

Utilisez une source de données PySpark :

  • Si vous souhaitez avoir la flexibilité de développer et de concevoir votre source de données ou votre puits de données Spark en utilisant Python.
  • Si vous l'utilisez uniquement dans des Notebooks ou des charges de travail PySpark.
  • Si vous souhaitez implémenter une logique de partitionnement personnalisée.

Ni les sources de données JDBC ni PySpark n'exposent de statistiques à l'optimiseur de query pour aider à sélectionner l'ordre des opérations.

Comment cela fonctionne

Pour vous connecter à une source de données à l'aide d'une connexion JDBC, installez le driver JDBC sur le compute Spark. La connexion vous permet de spécifier et d'installer le driver JDBC dans un sandbox isolé accessible par le compute Spark pour assurer la sécurité de Spark et la gouvernance d'Unity Catalog. Pour plus d'informations sur le sandbox, voir Comment Databricks applique-t-il l'isolement des utilisateurs ?.

Avant de commencer

Pour utiliser une connexion JDBC avec l’API Spark Data Source sur les clusters Serverless et standards, vous devez d’abord satisfaire aux exigences suivantes :

Exigences du Workspace :

  • Un Databricks Workspace activé pour Unity Catalog

Compute requis :

  • Connectivité réseau de votre ressource de compute vers le système de base de données cible. Voir Connectivité réseau.
  • Le compute Databricks doit utiliser Serverless, ou Databricks Runtime 17.3 LTS ou supérieur en mode standard ou en mode d’accès dédié.
  • Les SQL Warehouse doivent être Pro ou Serverless et doivent utiliser la version 2025,35 ou ultérieure.

Autorisations requises :

  • Pour créer une connexion, vous devez disposer du privilège CREATE CONNECTION sur le metastore attaché au workspace.
  • CREATE ou MANAGE accès à un volume Unity Catalog par le créateur de la connexion.
  • Accès au volume par l'utilisateur interrogeant la connexion.
  • Des autorisations supplémentaires sont spécifiées dans chaque section basée sur les tâches qui suit.

Méthodes d'authentification

Informations d'identification statiques

L'authentification par identifiants statiques stocke les identifiants directement sur la connexion — par exemple, un nom d'utilisateur et un mot de passe, une clé API ou tout autre champ d'identifiant accepté par le driver JDBC cible. Les informations d'identification sont transmises au Driver JDBC telles quelles lorsque la connexion est utilisée.

OAuth machine-à-machine

info

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

L’authentification OAuth Machine-to-Machine (M2M) est utilisée lorsque deux systèmes ou applications communiquent sans intervention directe de l’utilisateur. Les jetons sont émis à un client machine enregistré, qui utilise ses propres identifiants pour s'authentifier. Cette méthode d'authentification est idéale pour la communication de service à service, les microservices et les tâches d'automatisation pour lesquelles aucun contexte utilisateur n'est nécessaire.

Lorsque la connexion JDBC utilise OAuth M2M, Unity Catalog échange les identifiants client au niveau de l'endpoint de jeton configuré et transmet uniquement le jeton d'accès de courte durée résultant au driver JDBC à l'aide du paramètre de jeton du driver.

Étape 1 : créer un volume et installer le JDBC JAR

La connexion JDBC lit et installe le JAR du Driver JDBC à partir d'un volume Unity Catalog.

  1. Si vous n'avez pas d'accès en écriture et en lecture à un volume existant, créez un nouveau volume:

    SQL
    CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
  2. upload the JDBC Driver JAR vers le volume.

  3. Accordez l'accès en lecture sur le volume aux utilisateurs qui interrogent la connexion :

    SQL
    GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`

Étape 2 : Créez une connexion JDBC

Une connexion JDBC est un objet sécurisable dans Unity Catalog. Il spécifie le Driver JDBC, le chemin d’accès de l’URL, les identifiants pour accéder à un système de base de données externe et les options de liste blanche que l’utilisateur de la query peut spécifier. Pour créer une connexion, utilisez l’Explorateur de catalogues ou la commande SQL CREATE CONNECTION dans un Notebook Databricks ou l'éditeur de query Databricks SQL. Consultez Méthodes d’authentification pour connaître les méthodes d’authentification prises en charge.

remarque

Vous pouvez également utiliser l'API REST Databricks ou la CLI Databricks pour créer une connexion. Voir POST /api/2.1/unity-catalog/connections et les commandes Unity Catalog.

Autorisations requises : administrateur du Metastore ou utilisateur disposant du privilège CREATE CONNECTION.

Avant de créer une connexion, notez ce qui suit :

  • L'URL et les identifiants sont les seules options requises. N'intégrez pas les identifiants dans l'URL, car les Logs ou les erreurs peuvent les exposer. Utilisez les options d'identification dédiées pour votre méthode d'authentification choisie.
  • Utilisez externalOptionsAllowList pour contrôler les options de source de données Spark que les utilisateurs peuvent spécifier au moment de la requête. Si aucune valeur n'est spécifiée, le default est 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Définissez-le comme une chaîne vide pour limiter les utilisateurs aux seules options définies dans la connexion. Les utilisateurs ne peuvent jamais spécifier url ou host.
  1. Dans votre workspace Databricks, cliquez sur Icône de données. Catalogue .

  2. Cliquez sur Icône de prise. Connexion , puis cliquez sur Connexions .

  3. Cliquez sur Créer une connexion .

  4. Sur la page **Principes de base de la connexion** de l’assistant **Configurer la connexion**, saisissez un **Nom de connexion** convivial.

  5. Pour le type de connexion , sélectionnez JDBC .

  6. Ajouter un commentaire (facultatif).

  7. Cliquez sur Suivant .

  8. Sur la page Détails de la connexion , entrez les propriétés de connexion suivantes :

Propriété

Description

URL

L'URL JDBC de votre base de données, sous la forme jdbc:subprotocol:subname (par exemple, jdbc:oracle:thin:@<host>:<port>:<SID>).

Dépendances Java

Les fichiers JAR du driver JDBC des volumes Unity Catalog. Cliquez sur Ajouter une dépendance JAR pour ajouter chaque JAR (par exemple, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).

Liste d'autorisation des options externes

Liste, séparée par des virgules, d'options de source de données Spark que les utilisateurs qui effectuent des queries peuvent spécifier au moment de la query. Par default sur dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions. Définissez une valeur vide pour restreindre les utilisateurs uniquement aux options définies sur la connexion.

Options supplémentaires

Options de driver JDBC transmises au driver sous forme de paires clé-valeur. Utilisez cette section pour définir les informations d'identification de la base de données (par exemple, la clé user et la clé password) et toute autre propriété spécifique au driver. Basculez entre les modes de saisie **UI** et **JSON** selon vos besoins.

Propriété

Description

URL

L'URL JDBC de votre base de données, sous la forme jdbc:subprotocol:subname (par exemple, jdbc:oracle:thin:@<host>:<port>:<SID>).

Dépendances Java

Les fichiers JAR du driver JDBC des volumes Unity Catalog. Cliquez sur Ajouter une dépendance JAR pour ajouter chaque JAR (par exemple, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).

Liste d'autorisation des options externes

Liste, séparée par des virgules, d'options de source de données Spark que les utilisateurs qui effectuent des queries peuvent spécifier au moment de la query. Par default sur dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions. Définissez une valeur vide pour restreindre les utilisateurs uniquement aux options définies sur la connexion.

Options supplémentaires

Options de driver JDBC transmises au driver sous forme de paires clé-valeur. Utilisez cette section pour définir les informations d'identification de la base de données (par exemple, la clé user et la clé password) et toute autre propriété spécifique au driver. Basculez entre les modes de saisie **UI** et **JSON** selon vos besoins.

  1. Cliquez sur Créer une connexion .

OAuth machine à machine (Bêta)

info

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

Lorsque la jdbc_oauth_m2m_connector préversion est activée dans votre Workspace, le champ **Type d'authentification** apparaît sur la page **Informations de connexion de base** avec les options **Static Credential** et **OAuth Machine to Machine**. Pour créer une connexion JDBC OAuth M2M :

  1. Sur la page Informations de base de la connexion , définissez le Type d'authentification sur OAuth Machine to Machine .

  2. Cliquez sur Suivant .

  3. Sur la page Détails de la connexion , saisissez les propriétés suivantes en plus de l' URL et des dépendances Java :

Propriété

Description

ID client

L'ID client OAuth émis pour l'application.

Secret du client

Le secret client OAuth émis pour l'application.

Champ d'application d'OAuth

Portée à demander lors de l'échange de jetons. Exprimé sous forme de liste de chaînes sensibles à la casse, délimitée par des espaces.

Endpoint de jeton

L'Endpoint de jeton OAuth 2.0 utilisé pour échanger les identifiants client contre un jeton d'accès. Généralement au format https://authorization-server.com/oauth/token.

Méthode d'échange d'informations d'identification OAuth

Comment les identifiants client sont transmis à l'endpoint de jeton :

  • header_and_body — les identifiants sont envoyés à la fois dans l'en-tête Authorization et le corps de la requête (default).
  • body_only — les informations d'identification sont envoyées dans le corps de la requête uniquement.
  • header_only — les informations d'identification sont envoyées uniquement dans l'en-tête Authorization.

Nom du paramètre de jeton JDBC

La propriété KEY requise par le driver JDBC cible pour accepter le jeton d'accès OAuth. Databricks remplit dynamiquement ce paramètre VALUE avec un jeton d'accès OAuth valide généré. KEYs typiques : access_token, oauthToken ou password. Consultez la documentation de votre Driver JDBC pour connaître le nom de KEY correct du parameter.

Propriété

Description

ID client

L'ID client OAuth émis pour l'application.

Secret du client

Le secret client OAuth émis pour l'application.

Champ d'application d'OAuth

Portée à demander lors de l'échange de jetons. Exprimé sous forme de liste de chaînes sensibles à la casse, délimitée par des espaces.

Endpoint de jeton

L'Endpoint de jeton OAuth 2.0 utilisé pour échanger les identifiants client contre un jeton d'accès. Généralement au format https://authorization-server.com/oauth/token.

Méthode d'échange d'informations d'identification OAuth

Comment les identifiants client sont transmis à l'endpoint de jeton :

  • header_and_body — les identifiants sont envoyés à la fois dans l'en-tête Authorization et le corps de la requête (default).
  • body_only — les informations d'identification sont envoyées dans le corps de la requête uniquement.
  • header_only — les informations d'identification sont envoyées uniquement dans l'en-tête Authorization.

Nom du paramètre de jeton JDBC

La propriété KEY requise par le driver JDBC cible pour accepter le jeton d'accès OAuth. Databricks remplit dynamiquement ce paramètre VALUE avec un jeton d'accès OAuth valide généré. KEYs typiques : access_token, oauthToken ou password. Consultez la documentation de votre Driver JDBC pour connaître le nom de KEY correct du parameter.

  1. Cliquez sur Créer une connexion .

Le propriétaire ou le gestionnaire de la connexion peut ajouter à la connexion toute option supplémentaire prise en charge par le Driver JDBC. Pour des raisons de sécurité, les options définies dans la connexion ne peuvent pas être remplacées au moment de la query.

Étape 3 : Accorder le privilège USE

Accordez le privilège USE sur la connexion aux utilisateurs :

SQL
GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-name>;

Pour des informations sur la gestion des connexions existantes, consultez Gérer les connexions pour Lakehouse Federation.

Étape 4 : Query la source de données

Les utilisateurs disposant du privilège USE CONNECTION peuvent query la source de données à l'aide de la connexion JDBC via Spark ou l'API SQL de remote queries. Les utilisateurs peuvent ajouter toutes les options de source de données Spark prises en charge par le Driver JDBC et spécifiées dans le externalOptionsAllowList de la connexion JDBC (par exemple, dans ce cas : 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'). Pour afficher les options autorisées, exécutez la requête suivante :

SQL
DESCRIBE CONNECTION <JDBC-connection-name>;
Python
df = (
spark.read.format('jdbc')
.option('databricks.connection', '<JDBC-connection-name>')
.option('query', 'select * from <table_name>') # query in source SQL language - Option specified by querying user
.load()
)

df.display()

Migration

Pour migrer des charges de travail existantes de l’API Spark de source de données, Databricks recommande ce qui suit :

  • Supprimez l'URL et les identifiants des options dans l'API de source de données Spark.
  • Ajoutez le databricks.connection dans les options de l’API de source de données Spark.
  • Créez une connexion JDBC avec l'URL et les identifiants correspondants.
  • Dans la connexion, spécifiez les options qui doivent être statiques et ne doivent pas être spécifiées par les utilisateurs de query.
  • Dans le externalOptionsAllowList de la connexion, spécifiez les options de la source de données qui devraient être ajustées ou modifiées par les utilisateurs au moment de la query dans le code API de la source de données Spark (par exemple, 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions').

Limitations

API de source de données Spark

  • L’URL et l’hôte ne peuvent pas être inclus dans l’API de source de données Spark.
  • .option("databricks.connection", "<Connection_name>") est requis.
  • Les options définies dans la connexion ne peuvent pas être utilisées avec l'API de source de données dans votre code au moment de la requête.
  • Seules les options spécifiées dans le externalOptionsAllowList peuvent être utilisées par les utilisateurs qui effectuent des requêtes.
  • La limite de mémoire pour le Driver JDBC est de 400 Mio. Envisagez d'utiliser un fetchSize plus petit si la limite est atteinte.

Aide

  • Les sources de données Spark ne sont pas prises en charge.
  • LakeFlow Pipelines n'est pas pris en charge.
  • Dépendance de connexion à la création : java_dependencies prend uniquement en charge les emplacements de volume pour les JAR de driver JDBC.
  • Dépendance de connexion à la query : L'utilisateur de la connexion doit avoir l'accès READ au volume où se trouve le JAR du Driver JDBC.
  • En mode d’accès dédié (anciennement mode d’accès utilisateur unique), vous devez être propriétaire ou gestionnaire de la connexion pour l’utiliser.
  • Les certificats SSL ne sont pas pris en charge.
  • Les catalogues étrangers ne sont pas pris en charge avec les connexions JDBC.

Authentification

  • Ce connecteur prend en charge les informations d'identification statiques et OAuth machine à machine. Il ne prend pas en charge les identifiants Unity Catalog ni les identifiants de service.

Mise en réseau

  • Le système de base de données cible et le Workspace Databricks ne peuvent pas se trouver dans le même Virtual Private Cloud (VPC).

Connectivité réseau

La connectivité réseau de votre ressource de compute vers le système de base de données cible est requise. Consultez Recommandations réseau pour Lakehouse Federation pour des conseils généraux en matière de réseau.

Compute classique : clusters standard et dédiés

Les Virtual Private Cloud (VPC) Databricks sont configurés pour autoriser uniquement les clusters Spark. Pour se connecter à une autre infrastructure, placez le système de base de données cible dans un Virtual Private Cloud (VPC) différent et utilisez le peering Virtual Private Cloud (VPC). Une fois le peering Virtual Private Cloud (VPC) établi, vérifiez votre connectivité avec la connectionTest UDF sur le cluster ou le warehouse.

Si votre workspace Databricks et vos systèmes de base de données cibles sont dans le même Virtual Private Cloud (VPC), Databricks recommande l'un des éléments suivants :

  • Utilisez le compute serverless.
  • Configurez votre base de données cible pour autoriser le trafic TCP et UDP sur les ports 80 et 443, et spécifiez ces ports dans la connexion.

Serverless

Lorsque vous utilisez votre connexion JDBC sur le compute serverless, vous pouvez configurer un pare-feu pour l'accès au compute serverless au système de base de données cible en ajoutant des IP de sortie à une liste blanche. Vous pouvez également configurer la connectivité privée.

Test de connectivité

Pour tester la connectivité entre le compute Databricks et votre système de base de données, utilisez l'UDF suivante :

SQL
CREATE OR REPLACE TEMPORARY FUNCTION connectionTest(host string, port string) RETURNS string LANGUAGE PYTHON AS $$
import subprocess
try:
command = ['nc', '-zv', host, str(port)]
result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
return str(result.returncode) + "|" + result.stdout.decode() + result.stderr.decode()
except Exception as e:
return str(e)
$$;

SELECT connectionTest('<database-host>', '<database-port>');

FAQ

Les questions fréquemment posées suivantes couvrent le comportement de remontée de prédicats pour les connexions JDBC.

JDBC prend-il en charge le pushdown de prédicats ?

Oui. Les filtres sont transmis par default à la base de données distante pour l'API Spark Data Source (format('jdbc')) et la fonction SQLremote_query. Les prédicats qui peuvent être transmis dépendent du driver et du dialecte JDBC. Par conséquent, exécutez EXPLAIN sur votre query et inspectez le plan physique pour confirmer les filtres transmis à la source. Pour la fonction SQL remote_query, vous pouvez contrôler des pushdowns spécifiques (filtres, limites, décalages et agrégats) avec des options telles que pushdown.filters.enabled; toutes sont activées par default.

Le report de prédicat est distinct de l'exposition des statistiques de table à l'optimiseur de query. Les sources de données JDBC et PySpark n'exposent pas de statistiques à l'optimiseur de query pour aider à sélectionner l'ordre des Opérations, que les prédicats soient poussés ou non.