Connexion JDBC

Note

Cette fonctionnalité est disponible en préversion publique pour Databricks Runtime 18.1 et DBSQL 2025.40 et versions ultérieures. Pour les entrepôts SQL, vous devez également choisir d’activer la mise en réseau pour les charges de travail isolées dans la version préliminaire de Serverless SQL Warehouses.

Azure Databricks prend en charge la connexion à des bases de données externes à l’aide de JDBC. Vous pouvez utiliser une connexion de catalogue JDBC Unity pour lire et écrire dans une source de données avec l’API de source de données Spark ou l’API SQL de requête distante Azure Databricks. La connexion JDBC est un objet sécurisable dans le catalogue Unity qui spécifie le pilote JDBC, le chemin d’URL et les informations d’identification pour accéder à une base de données externe. La connexion JDBC est prise en charge dans les types de calcul du catalogue Unity, notamment les clusters serverless, les clusters standard, les clusters dédiés et Databricks SQL.

Avantages de l’utilisation d’une connexion JDBC

Lire et écrire depuis et vers des sources de données à l’aide de JDBC avec l’API de source de données Spark.
Lire à partir de sources de données avec JDBC à l’aide de l’API SQL Remote Query.
Accès contrôlé à la source de données à l’aide d’une connexion Unity Catalog.
Créez la connexion une seule fois et réutilisez-la dans n’importe quel calcul de catalogue Unity.
Stable pour les mises à niveau Spark et de calcul.
Les informations d’identification de connexion sont masquées à l'utilisateur qui effectue la requête.

JDBC versus fédération de requêtes

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

La fédération de requêtes fournit des contrôles d’accès précis et une gouvernance au niveau de la table à l’aide d’un catalogue externe. La connexion du catalogue JDBC Unity fournit une gouvernance uniquement au niveau de la connexion.
La fédération de requêtes envoie les requêtes exécutées par Spark pour optimiser les performances de requête.

Note

La fédération de requêtes prend en charge de nombreuses bases de données populaires, notamment 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 la fédération Lakehouse pour obtenir la liste complète des bases de données prises en charge.

Toutefois, choisissez d’utiliser une connexion de catalogue JDBC Unity dans les scénarios suivants :

Votre base de données n’est pas prise en charge par la fédération des requêtes.
Vous souhaitez utiliser un pilote JDBC spécifique.
Vous devez écrire sur 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 davantage de flexibilité, de performances et de contrôle de parallélisation par le biais des options d’API de source de données Spark.
Vous souhaitez envoyer les requêtes SQL source avec l’option Spark query.

Pourquoi utiliser des sources de données JDBC et 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 intégrée de Spark JDBC.
Si vous souhaitez utiliser un pilote JDBC prêt à l'emploi qui existe déjà.
Si vous avez besoin de la gouvernance d'Unity Catalog au niveau de la connexion.
Si vous souhaitez vous connecter à partir de n’importe quel type de calcul du catalogue Unity : serverless, standard, dédié, API SQL.
Si vous souhaitez utiliser votre connexion avec des API Python, Scala et SQL.

Utilisez une source de données PySpark :

Si vous souhaitez disposer de la flexibilité nécessaire pour développer et concevoir votre source de données Spark ou votre récepteur de données à l’aide de 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 JDBC ni les sources de données PySpark n’exposent de statistiques à l’optimiseur de requête pour vous aider à sélectionner l’ordre des opérations.

Fonctionnement

Pour vous connecter à une source de données à l’aide d’une connexion JDBC, installez le pilote JDBC sur le calcul Spark. La connexion vous permet de spécifier et d’installer le pilote JDBC dans un bac à sable isolé accessible par le calcul Spark pour garantir la sécurité Spark et la gouvernance du catalogue Unity. Pour plus d’informations sur le bac à sable (sandbox), consultez Comment Databricks applique-t-il l’isolation des utilisateurs ?.

Avant de commencer

Pour utiliser une connexion JDBC avec l’API de source de données Spark sur des clusters serverless et standard, vous devez d’abord répondre aux exigences suivantes :

Configuration requise pour l’espace de travail :

Un espace de travail Azure Databricks activé pour Unity Catalog

Configuration requise pour le calcul :

Connectivité réseau de votre ressource de calcul au système de base de données cible. Consultez connectivité réseau.
Le calcul Azure Databricks doit utiliser le mode serverless, ou Databricks Runtime 17.3 LTS ou une version ultérieure en mode standard ou en mode d'accès dédié.
Les entrepôts SQL 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 CREATE CONNECTION privilège sur le metastore attaché à l’espace de travail.
CREATE ou MANAGE l’accès à un volume Unity Catalog par le créateur de connexion.
Accès au volume par l’utilisateur qui interroge la connexion.
Des autorisations supplémentaires sont spécifiées dans chaque section basée sur des tâches qui suit.

Méthodes d’authentification

Identifiant statique

L’authentification des informations d’identification statiques stocke les informations d’identification directement sur la connexion, par exemple, un nom d’utilisateur et un mot de passe, une clé API ou tout autre champ d’informations d’identification accepté par le pilote JDBC cible. Les informations d’identification sont transmises au pilote JDBC as-is lorsque la connexion est utilisée.

OAuth Machine-à-machine

Important

Cette fonctionnalité est en version bêta. Les administrateurs d’espace de travail peuvent contrôler l’accès à cette fonctionnalité à partir de la page Aperçus . Consultez Gérer les préversions d’Azure Databricks.

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 d’ordinateur inscrit, qui utilise ses propres informations d’identification pour s’authentifier. Cette méthode d’authentification est idéale pour les tâches de communication, de microservices et d’automatisation de service à service dans lesquelles aucun contexte utilisateur n’est nécessaire.

Lorsque la connexion JDBC utilise OAuth M2M, Unity Catalog échange les informations d’identification du client sur le point de terminaison de jeton configuré et transmet uniquement le jeton d’accès de courte durée résultant au pilote JDBC à l’aide du paramètre de jeton du pilote.

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

La connexion JDBC lit et installe le fichier JAR du pilote JDBC à partir d’un volume de catalogue Unity.

Si vous n’avez pas d’accès en écriture et en lecture à un volume existant, créez un volume :
```
CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
```
Charger le JAR du pilote JDBC sur le volume.
Accordez l’accès en lecture sur le volume aux utilisateurs qui interrogent la connexion :
```
GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`
```

Étape 2 : Créer une connexion JDBC

Une connexion JDBC est un objet sécurisable dans le catalogue Unity. Il spécifie le pilote JDBC, le chemin d’URL, les informations d’identification pour accéder à un système de base de données externe et les options autorisées que l’utilisateur interrogeant peut spécifier. Pour créer une connexion, utilisez l’Explorateur de catalogue ou la CREATE CONNECTION commande SQL dans un notebook Azure Databricks ou l’éditeur de requêtes Databricks SQL. Consultez les méthodes d’authentification pour connaître les méthodes d’authentification prises en charge.

Note

Vous pouvez également utiliser l’API REST Databricks ou l’interface CLI Databricks pour créer une connexion. Consultez POST /api/2.1/unity-catalog/connections et Commandes Unity Catalog.

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

Avant de créer une connexion, notez les points suivants :

L’URL et les informations d’identification sont les seules options requises. N’incorporez pas d’informations d’identification dans l’URL, car les journaux ou les erreurs peuvent les exposer. Utilisez les options d’informations d’identification dédiées pour votre méthode d’authentification choisie.
Permet externalOptionsAllowList de contrôler les options de source de données Spark que les utilisateurs peuvent spécifier au moment de la requête. S’il n’est pas spécifié, la valeur par défaut est 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. Définissez-la sur une chaîne vide pour restreindre les utilisateurs aux seules options définies dans la connexion. Les utilisateurs ne peuvent jamais spécifier url ou host.

Explorateur de catalogues

Dans votre espace de travail Azure Databricks, cliquez sur Catalogue.
Cliquez sur Connectez-vous, puis cliquez sur Connexions.
Cliquez sur Create connection (Créer la connexion).
Dans la page de Informations de base de connexion de l’assistant Configurer la connexion, entrez un Nom de connexion convivial.
Pour le type de connexion, sélectionnez JDBC.
(Facultatif) Ajoutez un commentaire.
Cliquez sur Suivant.

Dans la page Détails de la connexion, entrez les propriétés de connexion suivantes :

Propriété	Description
Url	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 pilote JDBC à partir des volumes Unity Catalog. Cliquez sur Ajouter une dépendance JAR pour ajouter chaque fichier JAR (par exemple, `/Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar`).
Liste d’autorisation des options externes	Liste des options de source de données Spark séparées par des virgules que les utilisateurs peuvent spécifier lors de la requête. La valeur par défaut est `dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions`. Définissez sur une valeur vide pour limiter les utilisateurs aux seules options définies sur la connexion.
Options supplémentaires	Options arbitraires du pilote JDBC transmises au pilote sous forme de paires clé-valeur. Utilisez cette section pour définir les identifiants de la base de données (par exemple, clé `user` et clé `password`) ainsi que toute autre propriété spécifique au pilote. Basculer entre l’interface utilisateur et les modes d’entrée JSON en fonction des besoins.

Cliquez sur Create connection (Créer la connexion).

OAuth Machine-to-Machine (bêta)

Important

Lorsque l’aperçu jdbc_oauth_m2m_connector est activé dans votre espace de travail, le champ Type d’authentification s’affiche sur la page Paramètres de base de la connexion avec les options Informations d’identification statiques et OAuth Machine to Machine. Pour créer une connexion JDBC OAuth M2M :

Sur la page Connection basics, définissez le type d’authentification sur OAuth Machine to Machine.
Cliquez sur Suivant.

Dans la page Détails de la connexion, entrez les propriétés suivantes en plus de l’URL et Java dépendances :

Propriété	Description
ID du client	ID client OAuth émis pour l’application.
Secret client	Secret client OAuth émis pour l’application.
Étendue OAuth	Étendue à demander pendant l’échange de jetons. Sous forme d’une liste de chaînes de caractères qui respectent la casse, séparées par des espaces.
Point de terminaison de jeton	Point de terminaison de jeton OAuth 2.0 utilisé pour échanger les informations d’identification du client pour 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	Méthode de transmission des informations d’identification du client au point de terminaison du jeton : header_and_body : les informations d’identification sont envoyées à la fois dans l’en-tête et le `Authorization` corps de la requête (valeur par défaut). body_only : les informations d’identification sont envoyées uniquement dans le corps de la requête. header_only : les informations d’identification sont envoyées uniquement dans l’en-tête `Authorization` .
Nom du paramètre de jeton JDBC	Clé de propriété requise par le pilote JDBC cible pour accepter le jeton d’accès OAuth. Azure Databricks renseigne dynamiquement ce paramètre VALUE avec un jeton d’accès OAuth valide généré. KEYs typiques : `access_token`, `oauthToken`, ou `password`. Reportez-vous à la documentation de votre pilote JDBC pour connaître le nom correct du paramètre KEY .

Cliquez sur Create connection (Créer la connexion).

SQL

Utilisez la CREATE CONNECTION commande SQL dans un notebook ou l’éditeur de requête Databricks SQL.

Identifiant statique

Exécutez la commande suivante, en ajustant le volume, l’URL, les informations d’identification et externalOptionsAllowList:

DROP CONNECTION IF EXISTS <JDBC-connection-name>;

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<Schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  user '<user>',
  password '<password>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

DESCRIBE CONNECTION <JDBC-connection-name>;

Exemple : Connexion ORACLE JDBC

L’exemple suivant crée une connexion JDBC à une base de données Oracle à l’aide du pilote léger Oracle. Téléchargez le fichier JAR du pilote Oracle JDBC (par exemple ojdbc11.jar) à partir de la page téléchargements Oracle JDBC et chargez-le dans un volume de catalogue Unity avant d’exécuter cette commande.

CREATE CONNECTION oracle_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/ojdbc11.jar"]'
)
OPTIONS (
  url 'jdbc:oracle:thin:@<host>:<port>:<SID>',
  user '<oracle_user>',
  password '<oracle_password>',
  externalOptionsAllowList 'dbtable,query'
);

OAuth Machine-à-machine

Exécutez la commande suivante, en ajustant le volume, l’URL, les informations d’identification et externalOptionsAllowList:

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint '<https://authorization-server.com/oauth/token>',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '<driver-token-parameter-name>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

Exemple : Connexion JDBC PostgreSQL avec OAuth M2M

L’exemple suivant crée une connexion JDBC à une base de données PostgreSQL à l’aide de l’authentification machine à machine OAuth. Téléchargez le fichier JAR du pilote JDBC PostgreSQL (par exemple postgresql-42.7.3.jar) à partir de la page de téléchargements JDBC PostgreSQL et chargez-le dans un volume de catalogue Unity avant d’exécuter cette commande. Pour les déploiements PostgreSQL configurés pour accepter un jeton d’accès OAuth dans le champ du mot de passe, réglez jdbc_token_parameter_name sur password.

CREATE CONNECTION postgres_oauth_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/postgresql-42.7.3.jar"]'
)
OPTIONS (
  url 'jdbc:postgresql://<host>:<port>/<database>?sslmode=require',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint 'https://authorization-server.com/oauth/token',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name 'password',
  externalOptionsAllowList 'dbtable,query'
);

Le propriétaire ou le gestionnaire de connexion peut ajouter à la connexion toutes les options supplémentaires prises en charge par le pilote JDBC. Pour des raisons de sécurité, les options définies dans la connexion ne peuvent pas être substituées au moment de la requête.

Étape 3 : Accorder le `USE` privilège

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

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

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

Étape 4 : Interroger la source de données

Les utilisateurs disposant du USE CONNECTION privilège peuvent interroger la source de données à l’aide de la connexion JDBC via Spark ou l’API SQL des requêtes distantes. Les utilisateurs peuvent ajouter toutes les options de source de données Spark prises en charge par le pilote JDBC et spécifiées dans la externalOptionsAllowList 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 :

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()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in source SQL language - Option specified by querying user

Migration

Pour migrer à partir de charges de travail d’API de source de données Spark existantes, Databricks recommande d’effectuer les opérations suivantes :

Supprimez l’URL et les informations d’identification des options de l’API source de données Spark.
Ajoutez le databricks.connection dans les options de l’API Spark Data Source.
Créez une connexion JDBC avec l’URL et les informations d’identification correspondantes.
Dans la connexion, spécifiez les options qui doivent être statiques et ne doivent pas être spécifiées en interrogeant les utilisateurs.
Dans la connexion, spécifiez les options de source de données qui doivent être ajustées ou modifiées par les utilisateurs au moment de la requête dans le code de l’API externalOptionsAllowListsource de données Spark (par exemple). 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'

Limites

API de source de données Spark

L’URL et l’hôte ne peuvent pas être inclus dans l’API source de données Spark.
.option("databricks.connection", "<Connection_name>") est obligatoire.
Les options définies dans la connexion ne peuvent pas être utilisées sur l’API de source de données dans votre code au moment de la requête.
Seules les options spécifiées dans le fichier externalOptionsAllowList peuvent être utilisées en interrogeant les utilisateurs.
La limite de mémoire du pilote JDBC est de 400 MiB. Envisagez d’utiliser une valeur plus petite fetchSize si la limite est atteinte.
La source de données JDBC Spark ne prend pas en charge les instructions DML arbitraires, telles que UPDATE ou DELETE, sur la base de données externe. Il prend en charge la lecture des données et l’ajout ou l’écriture de tables entières, et non les modifications au niveau des lignes.

Support

Les sources de données Spark ne sont pas prises en charge.
Les pipelines Lakeflow ne sont pas pris en charge.
Dépendance de connexion lors de la création : java_dependencies prend uniquement en charge les emplacements de volume pour les fichiers JAR du pilote JDBC.
Dépendance de connexion à la requête : l’utilisateur de connexion doit READ accéder au volume où se trouve le fichier JAR du pilote JDBC.
Sur le mode d’accès dédié (anciennement mode d’accès mono-utilisateur), 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.

Authentication

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

Networking

Le système de base de données cible et l’espace de travail Azure Databricks ne peuvent pas se trouver dans le même réseau virtuel.

Connectivité réseau

La connectivité réseau de votre ressource de calcul au système de base de données cible est requise. Consultez les recommandations en matière de mise en réseau pour lakehouse Federation pour obtenir des conseils généraux sur la mise en réseau.

Calcul classique : clusters standard et dédiés

Azure Databricks réseaux virtuels sont configurés pour autoriser uniquement les clusters Spark. Pour vous connecter à une autre infrastructure, placez le système de base de données cible dans un autre réseau virtuel et utilisez le peering de réseaux virtuels. Une fois le VNet Peering établi, vérifiez votre connectivité avec la fonction connectionTest UDF sur le cluster ou l’entrepôt.

Si votre espace de travail Azure Databricks et les systèmes de base de données cibles se trouvent dans le même réseau virtuel, Databricks recommande l’une des options suivantes :

Utilisez l'informatique sans serveur.
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 calcul sans serveur, vous pouvez configurer un pare-feu pour autoriser l’accès du calcul sans serveur au système de base de données cible en ajoutant des adresses IP sortantes à une liste d’autorisation. Vous pouvez également configurer la connectivité privée.

Test de connectivité

Pour tester la connectivité entre le calcul Azure Databricks et votre système de base de données, utilisez la fonction UDF suivante :

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équentes suivantes traitent du comportement du pushdown des prédicats pour les connexions JDBC.

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

Yes. Les filtres sont poussés vers la base de données distante par défaut pour l’API de source de données Spark (format('jdbc')) et la remote_query fonction SQL. Les prédicats pouvant être poussés dépendent du pilote JDBC et du dialecte ; exécutez donc EXPLAIN sur votre requête et inspectez le plan physique pour confirmer quels filtres sont poussés vers la source. Pour la remote_query fonction SQL, 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 défaut.

Le pushdown de prédicat se distingue de l’exposition des statistiques de table à l’optimiseur de requête. Les sources de données JDBC et PySpark n’exposent pas de statistiques à l’optimiseur de requête pour vous aider à sélectionner l’ordre des opérations, que les prédicats soient envoyés ou non.

Commentaires

Est-ce que cette page vous a été utile?

Last updated on 2026-07-24

Connexion JDBC

Avantages de l’utilisation d’une connexion JDBC

JDBC versus fédération de requêtes

Pourquoi utiliser des sources de données JDBC et PySpark ?

Fonctionnement

Avant de commencer

Méthodes d’authentification

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

Étape 2 : Créer une connexion JDBC

Explorateur de catalogues

SQL

Étape 3 : Accorder le USE privilège

Étape 4 : Interroger la source de données

Python

SQL

Migration

Limites

API de source de données Spark

Support

Authentication

Networking

Connectivité réseau

Calcul classique : clusters standard et dédiés

Serverless

Test de connectivité

FAQ

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

Commentaires

Ressources supplémentaires

Étape 3 : Accorder le `USE` privilège