SQLAlchemy gebruiken met Azure Databricks

Azure Databricks biedt een SQLAlchemy-dialect (het systeem dat SQLAlchemy gebruikt om te communiceren met verschillende typen database-API-implementaties en -databases) voor Azure Databricks. SQLAlchemy is een Python SQL-toolkit en Object Relational Mapper (ORM). SQLAlchemy biedt een reeks bekende persistentiepatronen op ondernemingsniveau, ontworpen voor efficiënte en krachtige databasetoegang, aangepast in een eenvoudige en Pythonische domeintaal. Zie Functies en Filosofie.

Het SQLAlchemy-dialect voor Azure Databricks moet worden geïnstalleerd om de SQLAlchemy-functies te kunnen gebruiken met Azure Databricks. In dit artikel wordt het SQLAlchemy-dialect voor Azure Databricks versie 1.0 en 2.0 behandeld. Dit is gebaseerd op Databricks SQL Connector voor Python versie 4.0.0 of hoger.

Vereisten

  • Een ontwikkelcomputer met Python >=3.8 en <=3.11.
  • Databricks raadt u aan om virtuele Python-omgevingen te gebruiken, zoals die worden geleverd door venv die zijn opgenomen in Python. Virtuele omgevingen helpen ervoor te zorgen dat u de juiste versies van Python en de Databricks SQL Connector voor Python samen gebruikt. Het instellen en gebruiken van virtuele omgevingen valt buiten het bereik van dit artikel. Zie Virtuele omgevingen maken voor meer informatie.
  • Een bestaand cluster of SQL-magazijn.

Aan de slag

  • Installeer databricks-sqlalchemy voor SQLAlchemy v1 met behulp van pip install databricks-sqlalchemy~=1.0 of voor SQLAlchemy v2 met behulp van pip install databricks-sqlalchemy. Zie de releasegeschiedenis van databricks-sqlalchemyvoor versie-informatie.

  • Verzamel de volgende informatie voor het cluster of SQL Warehouse dat u wilt gebruiken:

    groepering

    SQL Warehouse

    • De hostnaam van de server van het SQL-warehouse. U kunt deze ophalen uit de serverhostnaamwaarde op het tabblad Verbindingsgegevens voor uw SQL-warehouse.
    • Het HTTP-pad van het SQL-warehouse. U kunt dit ophalen uit de waarde van het HTTP-pad op het tabblad Verbindingsgegevens voor uw SQL-warehouse.

Verificatie

Het SQLAlchemy-dialect voor Azure Databricks gebruikt de Databricks SQL Connector voor Python om te verbinden, en geeft de waarden door connect_args aan de connector. Het ondersteunt de volgende authenticatietypen:

Persoonlijke toegangstokenauthenticatie

Als u een persoonlijk toegangstoken van Azure Databricks wilt maken, volgt u de stappen in Persoonlijke toegangstokens maken voor werkruimtegebruikers.

Gebruik het volgende codefragment om het SQLAlchemy-dialect te verifiëren. In dit fragment wordt ervan uitgegaan dat u de volgende omgevingsvariabelen hebt ingesteld:

  • DATABRICKS_TOKEN, ingesteld op het persoonlijke toegangstoken van Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEingesteld op de serverhostnaamwaarde voor uw cluster of SQL Warehouse.
  • DATABRICKS_HTTP_PATH, ingesteld op HTTP-padwaarde voor uw cluster of SQL Warehouse.
  • DATABRICKS_CATALOG, ingesteld op de doelcatalogus in Unity Catalog.
  • DATABRICKS_SCHEMA, ingesteld op het doelschema (ook wel een database genoemd) in Unity Catalog.

Als u omgevingsvariabelen wilt instellen, raadpleegt u de documentatie van uw besturingssysteem.

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

# ...

U gebruikt de voorgaande engine variabele om verbinding te maken met uw opgegeven catalogus en schema via uw Azure Databricks-rekenresource.

OAuth-verificatie van gebruikers-naar-machine (U2M)

OAuth U2M-authenticatie gebruikt realtime menselijke aanmelding en toestemmingverlening om het doelaccount van Azure Databricks te authenticeren. Voor de Databricks SQL Connector voor Python-versies die dit op elke cloud ondersteunen, zie OAuth user-to-machine (U2M) authenticatie.

Om het SQLAlchemy-dialect te authenticeren met OAuth U2M, gebruik je het volgende codefragment. Dit fragment gaat ervan uit dat je de omgevingsvariabelen DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG en DATABRICKS_SCHEMA hebt ingesteld, zoals beschreven in persoonlijke toegangstokenauthenticatie.

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

# ...

machine-naar-machine (M2M) OAuth-verificatie

OAuth M2M-authenticatie meldt zich aan als een Azure Databricks service principal. Je moet ook de Databricks SDK voor Python installeren (bijvoorbeeld door pip install databricks-sdk te draaien). Voor de Databricks SQL Connector voor Python- en SDK-versies die het op elke cloud ondersteunen, zie OAuth machine-to-machine (M2M) authenticatie.

Om OAuth M2M-authenticatie te gebruiken, doe je het volgende:

  1. Maak een Azure Databricks-service-principal in uw Azure Databricks-werkruimte en maak een OAuth-geheim voor die service-principal. Zie Autorisatie van toegang voor de service-principal tot Azure Databricks met OAuth.
  2. Geef die serviceprincipal toegang tot je cluster of SQL-warehouse. Zie Rekenmachtigingen of een SQL-magazijn beheren.

Om het SQLAlchemy-dialect te authenticeren met OAuth M2M, gebruik je het volgende codefragment. Naast de omgevingsvariabelen DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG en DATABRICKS_SCHEMA gaat dit fragment ervan uit dat je de volgende omgevingsvariabelen hebt ingesteld:

  • DATABRICKS_CLIENT_ID, ingesteld op de UUID- of Applicatie-ID van de serviceprincipal.
  • DATABRICKS_CLIENT_SECRET, ingesteld op de geheime waarde voor het OAuth-geheim van de service-principal.
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

Raadpleeg deze example.py voor verbindingsvoorbeelden

SQLAlchemy v2

Zie de volgende sectie en het sqlalchemy_example.py-bestand in GitHub voor verbindingsvoorbeelden.

DBAPI-referentie

Aanvullende bronnen

  • Laatst bijgewerkt om