Connexion JDBC

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.
• Lisez à partir de sources de données avec JDBC à l’aide de l’API SQL de requête distante.
• 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 traitement.
• 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 déporte les requêtes exécutées par Spark pour optimiser les performances de requête.

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 des requêtes vers le bas 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 workloads PySpark.
• Si vous souhaitez implémenter une logique de partitionnement personnalisée.

Ni JDBC ni les sources de données PySpark ne prennent en charge le pushdown des prédicats. Ils n’exposent pas non plus les 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 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.

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

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

2. Chargez le fichier JAR du pilote JDBC sur le volume.

3. 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 qui spécifie le pilote JDBC, le chemin d’URL et les informations d’identification permettant d’accéder à un système de base de données externe et d’options autorisées à utiliser par l’utilisateur interrogeant. 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.

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

Explorateur de catalogues

1. Dans votre espace de travail Azure Databricks, cliquez sur Catalogue.
2. En haut du volet Catalogue, cliquez sur , puis sélectionnez Créer une connexion dans le menu.
3. Dans la page de Informations de base de connexion de l’assistant Configurer la connexion, entrez un Nom de connexion convivial.
4. Sélectionnez le type de connexionJDBC.
5. (Facultatif) Ajoutez un commentaire.
6. Cliquez sur Suivant.
7. Dans la page Authentification , entrez les propriétés de connexion suivantes :
   • URL JDBC : URL de connexion JDBC pour votre base de données (par exemple, jdbc:oracle:thin:@<host>:<port>:<SID>).
   • Utilisateur : nom d’utilisateur de la base de données.
   • Mot de passe : mot de passe de la base de données.
   • Chemin du driver JDBC : chemin vers le fichier JAR du driver JDBC dans le volume du Unity Catalog (par exemple, /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar).
8. Cliquez sur Create connection (Créer la connexion).

SQL

Exécutez la commande suivante dans un notebook ou l’éditeur de requête SQL, 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'
);

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. Les utilisateurs ne peuvent spécifier que les options de source de données Spark qui ne sont pas déjà définies dans la connexion.

Le externalOptionsAllowList créateur de connexion permet au créateur de connexion de spécifier les options de source de données Spark que les utilisateurs peuvent fournir au moment de la requête. Dans cet exemple, les utilisateurs peuvent uniquement utiliser : 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. externalOptionsAllowList peut être une chaîne vide pour assurer que seules les options spécifiées dans la connexion du catalogue Unity sont utilisées. L’URL et l’hôte ne sont jamais autorisés à être spécifiés par les utilisateurs.

L’URL est la seule option obligatoire lors de la création de la connexion. Si aucune liste d'autorisation n'est spécifiée, une liste d'autorisation par défaut est utilisée, laquelle contient : 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'.

Databricks recommande de spécifier les informations d’identification dans la connexion.

É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 Database native SQL language - Option specified by querying user
  .load()
)

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in Database native 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.

Support

• Les sources de données Spark ne sont pas prises en charge.
• Les pipelines déclaratifs Spark 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 jars 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

• Seule l’authentification de base est prise en charge (nom d’utilisateur et mot de passe). Il n’existe aucune prise en charge des authentifications du Unity Catalog, OAuth ou des authentifications 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 VPC.

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

Les VPN Azure Databricks 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 VPC et utilisez le peering VPC. Une fois le peering VPC établi, vérifiez la connectivité avec l’UDF connectionTest sur le cluster ou l’entrepôt de données.

Si votre espace de travail Azure Databricks et vos systèmes de base de données cibles se trouvent dans le même VPC, 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 un calcul sans serveur, configurez un pare-feu pour permettre l'accès au calcul sans serveur via des adresses IP fixes, ou configurez une 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>');