Utiliser SQLAlchemy avec Azure Databricks
Azure Databricks fournit un dialecteSQLAlchemy (le système utilisé par SQLAlchemy pour communiquer avec divers types de bases de données et d’implémentations d’API de base de données) pour Azure Databricks. SQLAlchemy est un kit d’outils Python SQL et un mappeur relationnel objet (ORM). SQLAlchemy offre une suite bien connue de modèles de persistance au niveau de l’entreprise conçue pour un accès efficace et à hautes performances aux bases de données et adaptée pour un langage de domaine simple et de type Python. Consultez Fonctionnalités et philosophie.
Le Connecteur Databricks SQL pour Python inclut le dialecte SQLAlchemy pour Azure Databricks. Cet article aborde le dialecte SQLAlchemy pour Azure Databricks version 2.0 qui nécessite un connecteur Databricks SQL pour Python version 3.0.0 ou ultérieure.
Spécifications
- Un ordinateur de développement exécutant Python >=3.8 et <=3.11.
- Databricks vous recommande d’utiliser des environnements virtuels Python, tels que ceux fournis par venv inclus avec Python. Les environnements virtuels vous permettent d’assurer que vous utilisez une combinaison des bonnes versions de Python et du connecteur Databricks SQL. La configuration et l’utilisation des environnements virtuels n’entrent pas dans le cadre de cet article. Pour plus d’informations, consultez la Création d’environnements virtuels.
- Cluster ou entrepôt SQL existant.
Bien démarrer
Installez la bibliothèque du connecteur Databricks SQL pour Python version 3.0.0 ou ultérieure sur votre ordinateur de développement en exécutant
pip install "databricks-sql-connector[sqlalchemy]"oupython -m pip install "databricks-sql-connector[sqlalchemy]". Pour obtenir des informations sur la version, voir l’Historique des versions databricks-sql-connector.Collectez les informations suivantes pour le cluster ou l’entrepôt SQL que vous souhaitez utiliser :
Cluster
- Nom d’hôte du serveur du cluster. Vous pouvez extraire celui-ci de la valeur Nom d'hôte du serveur sous l’onglet Options avancées > JDBC/ODBC pour votre cluster.
- Chemin d’accès HTTP du cluster. Vous pouvez extraire celui-ci de la valeur Chemin d'accès HTTP sous l’onglet Options avancées > JDBC/ODBC pour votre cluster.
Entrepôt SQL
- Nom d’hôte du serveur de l’entrepôt SQL. Vous pouvez l’obtenir à partir de la valeur Nom d'hôte du serveur sous l’onglet Détails de la connexion pour votre entrepôt SQL.
- Chemin HTTP de l’entrepôt SQL. Vous pouvez l’obtenir à partir de la valeur Chemin HTTP sous l’onglet Détails de la connexion pour votre entrepôt SQL.
Authentification
Le dialecte SQLAlchemy pour Azure Databricks prend en charge l’authentification par jeton d’accès personnel.
Pour créer un jeton d’accès personnel Azure Databricks, effectuez les étapes suivantes :
- Dans votre espace de travail Azure Databricks, cliquez sur votre nom d’utilisateur Azure Databricks dans la barre supérieure, puis sélectionnez Paramètres dans la liste déroulante.
- Cliquez sur Développeur.
- À côté de Jetons d’accès, cliquez sur Gérer.
- Cliquez sur Générer un nouveau jeton.
- (Facultatif) Entrez un commentaire qui vous aide à identifier ce jeton à l’avenir et modifiez sa durée de vie par défaut (90 jours). Pour créer un jeton sans durée de vie (non recommandé), laissez vide la zone Durée de vie (en jours).
- Cliquez sur Générer.
- Copiez le jeton affiché dans un emplacement sécurisé, puis cliquez sur Terminé.
Remarque
Veillez à enregistrer le jeton copié dans un emplacement sécurisé. Ne partagez pas votre jeton copié avec d'autres. Si vous le perdez, vous ne pouvez pas régénérer exactement le même. Vous devez donc répéter cette procédure pour créer un jeton. Si vous perdez le jeton copié ou si vous pensez que le jeton a été compromis, Databricks vous recommande vivement de supprimer immédiatement ce jeton de votre espace de travail en cliquant sur l’icône de la corbeille (Révoquer) à côté du jeton de la page Jetons d’accès.
Si vous n'êtes pas en mesure de créer ou d'utiliser des jetons dans votre espace de travail, cela peut être dû au fait que votre administrateur d'espace de travail a désactivé les jetons ou ne vous a pas donné l'autorisation de créer ou d'utiliser des jetons. Consultez votre administrateur d'espace de travail ou les rubriques suivantes :
Pour authentifier le dialecte SQLAlchemy, utilisez l’extrait de code suivant. Cet extrait suppose que vous avez défini les variables d’environnement suivantes :
DATABRICKS_TOKEN, réglé sur le jeton d’accès personnel Azure Databricks.DATABRICKS_SERVER_HOSTNAMEréglé sur la valeur Nom d'hôte de serveur de votre cluster ou entrepôt SQL.DATABRICKS_HTTP_PATH, réglé sur la valeur Chemin HTTP de votre cluster ou entrepôt SQL.DATABRICKS_CATALOG, défini sur le catalogue cible dans Unity Catalog.DATABRICKS_SCHEMA, défini sur le schéma cible (également appelé base de données) dans Unity Catalog.
Pour définir des variables d’environnement, consultez la documentation de votre système d’exploitation.
import os
from sqlalchemy import create_engine
access_token = os.getenv("DATABRICKS_TOKEN")
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path = os.getenv("DATABRICKS_HTTP_PATH")
catalog = os.getenv("DATABRICKS_CATALOG")
schema = os.getenv("DATABRICKS_SCHEMA")
engine = create_engine(
url = f"databricks://token:{access_token}@{server_hostname}?" +
f"http_path={http_path}&catalog={catalog}&schema={schema}"
)
# ...
Vous utilisez la variable engine précédente pour vous connecter à votre schéma et à votre catalogue spécifiés via votre ressource de calcul Azure Databricks. Si vous souhaitez obtenir des exemples de connexion, consultez la section suivante et le fichier sqlalchemy.py dans GitHub.
Exemple
Voir le fichier sqlalchemy.py dans GitHub.
Informations de référence sur DBAPI
- Voir le fichier README.sqlalchemy.md dans GitHub.
- Voir également le répertoire de code source sqlalchemy dans GitHub.