Verwenden von SQLAlchemy mit Azure Databricks

Azure Databricks bietet einen SQLAlchemy-Dialekt (das von SQLAlchemy verwendete System, um mit verschiedenen Arten von Datenbank-API-Implementierungen und Datenbanken zu kommunizieren) für Azure Databricks. SQLAlchemy ist ein Python SQL-Toolkit und Object Relational Mapper (ORM). SQLAlchemy bietet eine Reihe bekannter Persistenzmuster auf Unternehmensniveau, die für einen effizienten und leistungsstarken Datenbankzugriff entwickelt wurden, angepasst an eine einfache und pythonische Domänensprache. Siehe Funktionen und Philosophie.

Der SQLAlchemy-Dialekt für Azure Databricks muss installiert werden, um die SQLAlchemy-Features mit Azure Databricks zu verwenden. In diesem Artikel wird der SQLAlchemy-Dialekt für Azure Databricks, Version 1.0 und 2.0, behandelt, der auf Databricks SQL Connector für Python Version 4.0.0 oder höher basiert.

Anforderungen

  • Ein Entwicklungscomputer, auf dem Python >=3.8 und <=3.11 läuft.
  • Databricks empfiehlt die Verwendung von virtuellen Python-Umgebungen, etwa denen, die von venv bereitgestellt werden und in Python enthalten sind. Mithilfe virtueller Umgebungen kann sichergestellt werden, dass Sie die richtigen Versionen von Python und des Databricks SQL-Connectors für Python zusammen verwenden. Einrichtung und Verwendung virtueller Umgebungen werden in diesem Artikel nicht behandelt. Weitere Informationen finden Sie unter Erstellen virtueller Umgebungen.
  • Ein vorhandener Cluster oder ein vorhandenes SQL-Warehouse.

Erste Schritte

  • Installieren Sie databricks-sqlalchemy für SQLAlchemy v1 mit pip install databricks-sqlalchemy~=1.0 oder für SQLAlchemy v2 mit pip install databricks-sqlalchemy. Versionsinformationen finden Sie im Releaseverlauf databricks-sqlalchemy.

  • Sammeln Sie die folgenden Informationen über den Cluster oder das SQL-Warehouse, den oder das Sie verwenden möchten:

    Kluster

    SQL-Warehouse

    • Der Serverhostname des SQL-Warehouses. Sie finden diesen im Wert Serverhostname auf der Registerkarte Verbindungsdetails für Ihr SQL-Warehouse.
    • Der HTTP-Pfad des SQL-Warehouses. Sie finden diesen im Wert HTTP-Pfad auf der Registerkarte Verbindungsdetails für Ihr SQL-Warehouse.

Authentifizierung

Der SQLAlchemy-Dialekt für Azure Databricks verwendet den Databricks SQL Connector für Python zur Verbindung und übergibt die Werte in connect_args an den Connector. Es unterstützt die folgenden Authentifizierungstypen:

Authentifizierung mit Personal Access Token

Führen Sie zum Erstellen eines persönlichen Azure Databricks-Zugriffstokens die Schritte unter Erstellen von persönlichen Zugriffstoken für Arbeitsbereichsbenutzer aus.

Verwenden Sie den folgenden Codeausschnitt, um den SQLAlchemy-Dialekt zu authentifizieren. Bei diesem Codeschnipsel wird davon ausgegangen, dass Sie die folgenden Umgebungsvariablen festgelegt haben:

  • DATABRICKS_TOKEN ist auf das persönliche Azure Databricks-Zugriffstoken festgelegt.
  • DATABRICKS_SERVER_HOSTNAMEauf den Wert für den Server-Hostnamen Ihres Clusters oder SQL-Warehouses gesetzt.
  • DATABRICKS_HTTP_PATH ist auf den Wert von HTTP-Pfad für Ihren Cluster oder Ihr SQL-Warehouse festgelegt.
  • DATABRICKS_CATALOG, auf den Zielkatalog in Unity Catalog festgelegt.
  • DATABRICKS_SCHEMA, auf das Zielschema (auch Datenbank genannt) in Unity Catalog festgelegt.

Informationen zum Festlegen von Umgebungsvariablen finden Sie in der Dokumentation Ihres Betriebssystems.

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}"
)

# ...

Sie verwenden die vorangehende engine-Variable, um über Ihre Azure Databricks-Compute-Ressource eine Verbindung mit Ihrem angegebenen Katalog und Schema herzustellen.

OAuth-Benutzer-zu-Computer-Authentifizierung (U2M)

OAuth-U2M-Authentifizierung verwendet die menschliche Anmeldung und Einwilligung in Echtzeit, um das Azure Databricks-Zielbenutzerkonto zu authentifizieren. Für „Databricks SQL-Connector für Python“-Versionen, die dies in jeder Cloud unterstützen, lesen Sie OAuth-User-to-Machine-Authentifizierung (U2M).

Um den SQLAlchemy-Dialekt mit OAuth U2M zu authentifizieren, verwenden Sie den folgenden Codeausschnitt. Dieser Ausschnitt setzt voraus, dass Sie die DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG und DATABRICKS_SCHEMA Umgebungsvariablen festgelegt haben, wie in Authentifizierung mit persönlichem Zugriffstoken beschrieben.

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"}
)

# ...

OAuth-Computer-zu-Computer-Authentifizierung (M2M)

Die OAuth-M2M-Authentifizierung authentifiziert als Azure Databricks-Dienstprinzipal. Du musst auch das Databricks SDK für Python installieren (zum Beispiel, indem du pip install databricks-sdk ausführst). Für den Databricks SQL Connector für Python- und SDK-Versionen, die dies in jeder Cloud unterstützen, siehe OAuth Machine-to-Machine (M2M) Authentifizierung.

Um OAuth M2M-Authentifizierung zu verwenden, führen Sie Folgendes aus:

  1. Erstellen Sie einen Azure Databricks-Dienstprinzipal in Ihrem Azure Databricks-Arbeitsbereich, und erstellen Sie ein OAuth-Geheimnis für diesen Dienstprinzipal. Siehe Autorisieren des Dienstprinzipalzugriffs auf Azure Databricks mit OAuth.
  2. Gib diesem Service-Principal Zugriff auf deinen Cluster oder dein SQL-Warehouse. Siehe Computerberechtigungen oder Ein SQL-Warehouse verwalten.

Um den SQLAlchemy-Dialekt mit OAuth M2M zu authentifizieren, verwenden Sie den folgenden Codeausschnitt. Zusätzlich zu den Umgebungsvariablen DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG und DATABRICKS_SCHEMA setzt dieser Ausschnitt voraus, dass Sie die folgenden Umgebungsvariablen festgelegt haben:

  • DATABRICKS_CLIENT_ID, auf den Wert UUID oder Anwendungs-ID des Dienstprinzipals gesetzt.
  • DATABRICKS_CLIENT_SECRET, auf den Wert Geheimnis für das OAuth-Geheimnis des Dienstprinzipals gesetzt.
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

Informationen zu Verbindungsbeispielen finden Sie in diesem example.py

SQLAlchemy v2

Verbindungsbeispiele finden Sie im folgenden Abschnitt und in der datei sqlalchemy_example.py in GitHub.

DBAPI-Referenz

Zusätzliche Ressourcen

  • Zuletzt aktualisiert um