Aller au contenu principal
Dernière mise à jour le

Utiliser SQLAlchemy avec Databricks

Databricks fournit un dialecte SQLAlchemy (le système que SQLAlchemy utilise pour communiquer avec différents types d’implémentations d’API de base de données et de bases de données) pour Databricks. SQLAlchemy est une boîte à outils SQL Python et un mappeur objet-relationnel (ORM). SQLAlchemy offre une suite de modèles de persistance de niveau entreprise bien connus, conçue pour un accès efficace et très performant aux bases de données, et adaptée en un langage de domaine simple et Pythonique. Voir Fonctionnalités et philosophie.

Le dialecte SQLAlchemy pour Databricks doit être installé pour utiliser les fonctionnalités SQLAlchemy avec Databricks. Cet article aborde le dialecte SQLAlchemy pour Databricks versions 1.0 et 2.0, qui sera basé sur le connecteur Databricks SQL pour Python version 4.0.0 ou supérieure.

Exigences​

  • Une machine de développement exécutant Python >=3.8 et <=3.11.
  • Databricks recommande d'utiliser des environnements virtuels Python, tels que ceux fournis par venv qui sont inclus avec Python. Les environnements virtuels vous aident à garantir que vous utilisez ensemble les bonnes versions de Python et du connecteur Databricks SQL pour Python. La configuration et l'utilisation d'environnements virtuels dépassent le cadre de cet article. Pour plus d'informations, consultez Création d'environnements virtuels.
  • Un cluster ou un SQL Warehouse existant.

Get start​

  • Installez databricks-sqlalchemy pour SQLAlchemy v1 à l'aide de pip install databricks-sqlalchemy~=1.0 ou pour SQLAlchemy v2 à l'aide de pip install databricks-sqlalchemy. Pour les informations sur la version, consultez l'historique des versions de databricks-sqlalchemy.
  • Recueillez les informations suivantes pour le cluster ou le SQL warehouse que vous souhaitez utiliser :
  • Le hostname du serveur du cluster. Vous pouvez l'obtenir à partir de la valeur Hostname du serveur dans l'onglet Options avancées > JDBC/ODBC de votre cluster.
  • Le chemin HTTP du cluster. Vous pouvez obtenir ceci à partir de la valeur **Chemin HTTP** dans l'onglet ** Options avancées > JDBC/ODBC ** pour votre cluster.

Authentification​

Le dialecte SQLAlchemy pour Databricks utilise le connecteur Databricks SQL pour Python pour se connecter et transmet les valeurs de connect_args au connecteur. Il prend en charge les types d'authentification suivants :

Authentification par jeton d'accès personnel​

Pour créer un jeton d'accès personnel Databricks, suivez les étapes de la section Créer des jetons d'accès personnels pour les utilisateurs de Workspace.

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 Databricks.
  • DATABRICKS_SERVER_HOSTNAMEdéfini sur la valeur **Hostname du serveur** de votre cluster ou SQL Warehouse.
  • DATABRICKS_HTTP_PATH, défini sur la valeur Chemin HTTP pour votre cluster ou SQL Warehouse.
  • 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 les variables d’environnement, consultez la documentation de votre système d’exploitation.

Python
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 catalogue et à votre schéma spécifiés via votre ressource compute Databricks.

Authentification OAuth utilisateur à machine (U2M)​

L'authentification OAuth U2M utilise une connexion et un consentement humains en temps réel pour authentifier le compte utilisateur Databricks cible. Pour les versions du connecteur Databricks SQL pour Python qui prennent en charge cette fonctionnalité sur chaque cloud, voir Authentification utilisateur à machine (U2M) OAuth.

Pour authentifier le dialecte SQLAlchemy avec OAuth U2M, utilisez l'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 Authentification par jeton d'accès personnel.

Python
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 M2M OAuth s’authentifie en tant que Service Principal Databricks. Vous devez également installer le SDK Databricks pour Python (par exemple, en exécutant pip install databricks-sdk). Pour les versions du connecteur Databricks SQL pour Python et du SDK qui prennent en charge cette fonctionnalité sur chaque cloud, voir Authentification machine à machine (M2M) OAuth.

Pour utiliser l’authentification OAuth M2M, procédez comme suit :

  1. Créez un Service Principal Databricks dans votre Workspace Databricks et créez un secret OAuth pour ce Service Principal. Voir Autoriser l’accès du Service Principal Databricks à Databricks avec OAuth.
  2. Donnez à ce service principal l'accès à votre cluster ou à votre SQL warehouse. Consultez les autorisations de compute ou gérez un SQL warehouse.

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

  • DATABRICKS_CLIENT_ID, défini sur la valeur UUID ou ID de l'application du service principal.
  • DATABRICKS_CLIENT_SECRET, défini sur la valeur Secret pour le secret OAuth du Service Principal.
Python
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.py.

SQLAlchemy v2​

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

Référence DBAPI​

Ressources supplémentaires​

Sur cette page