Utiliser SQLAlchemy avec Azure Databricks

Azure Databricks fournit un dialecte SQLAlchemy (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 propose un ensemble de modèles de persistance bien connus, de niveau entreprise, conçus pour un accès efficace et hautement performant aux bases de données, et adaptés à un langage de domaine simple et pythonique. Consultez Fonctionnalités et philosophie.

Le dialecte SQLAlchemy pour Azure Databricks doit être installé pour utiliser les fonctionnalités SQLAlchemy avec Azure Databricks. Cet article traite du dialecte SQLAlchemy pour Azure Databricks version 1.0 et 2.0, qui sera basé sur Databricks SQL Connector pour Python version 4.0.0 ou ultérieure.

Exigences

  • 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 pour Python. 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.

Commencez

  • Installez databricks-sqlalchemy pour SQLAlchemy v1 à l’aide de pip install databricks-sqlalchemy~=1.0 ou de SQLAlchemy v2 à l’aide de pip install databricks-sqlalchemy. Pour obtenir des informations sur la version, voir l’Historique des versions databricks-sqlalchemy.

  • Collectez les informations suivantes pour le cluster ou l’entrepôt SQL que vous souhaitez utiliser :

    Groupe

    • 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 utilise le connecteur SQL de Databricks pour Python afin de se connecter, et transmet les valeurs dans connect_args au connecteur. Il prend en compte les types d’authentification suivants :

Authentification par jeton d’accès personnel

Pour créer un jeton d’accès personnel Azure Databricks, suivez les étapes décrites dans Créer des jetons d’accès personnels pour les utilisateurs de l’espace de travail.

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, défini sur le jeton d'accès personnel d'Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAME réglé sur la valeur Nom d'hôte de serveur de votre cluster ou entrepôt SQL.
  • DATABRICKS_HTTP_PATH, défini sur la valeur Chemin HTTP de votre cluster ou SQL warehouse.
  • DATABRICKS_CATALOG, défini pour le catalogue cible dans Unity Catalog.
  • DATABRICKS_SCHEMA, défini selon le schéma cible (également appelé base de données) dans le Catalogue Unity.

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 précédente engine pour vous connecter à votre catalogue et schéma spécifiés via votre ressource de calcul Azure Databricks.

Authentification OAuth de l'utilisateur à la machine (U2M)

L’authentification OAuth U2M utilise la connexion en temps réel d’un utilisateur et le consentement pour authentifier le compte utilisateur Azure Databricks cible. Pour les versions de Connecteur Databricks SQL pour Python qui le prennent en charge sur chaque cloud, voir l’authentification OAuth utilisateur à machine (U2M).

Pour authentifier le dialecte SQLAlchemy avec OAuth U2M, utilisez le extrait de code suivant. Cet extrait suppose que vous avez défini les variables d’environnement DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG et DATABRICKS_SCHEMA, comme décrit dans l’authentification par jeton d’accès personnel.

import os
from sqlalchemy import create_engine

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://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"auth_type": "databricks-oauth"}
)

# ...

Authentification OAuth machine à machine (M2M)

L’authentification OAuth M2M permet de s’authentifier en tant que principal de service Azure Databricks. Vous devez également installer le SDK Databricks pour Python (par exemple, en exécutant pip install databricks-sdk). Pour les versions de Databricks SQL Connector pour Python et SDK qui le prennent en charge sur chaque cloud, voir authentification OAuth machine-to-machine (M2M).

Pour utiliser l’authentification OAuth M2M, faites ce qui suit :

  1. Créez un principal de service Azure Databricks dans votre espace de travail Azure Databricks et créez un secret OAuth pour ce principal de service. Consultez Autoriser l'accès principal de service pour Azure Databricks avec OAuth.
  2. Donnez à ce principal de service l’accès à votre cluster ou entrepôt SQL. Consultez Autorisations de calcul ou Gérer un entrepôt SQL.

Pour authentifier le dialecte SQLAlchemy avec OAuth M2M, utilisez le extrait de code suivant. En plus des DATABRICKS_SERVER_HOSTNAMEvariables , DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG, et DATABRICKS_SCHEMA d’environnement, ce fragment suppose que vous avez défini les variables d’environnement suivantes :

  • DATABRICKS_CLIENT_ID, assigné au principal de service avec la valeur UUID ou ID d’application.
  • DATABRICKS_CLIENT_SECRET, défini sur la valeur secret pour le secret OAuth du principal de service.
import os
from databricks.sdk.core import Config, oauth_service_principal
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"credentials_provider": credential_provider}
)

# ...

SQLAlchemy v1

Pour des exemples de connexion, consultez cet exemple de fichier example.py

SQLAlchemy v2

Pour obtenir des exemples de connexion, consultez la section suivante et le fichier sqlalchemy_example.py dans GitHub.

Référence DBAPI

Ressources supplémentaires

  • Dernière mise à jour :