Använda SQLAlchemy med Azure Databricks

Azure Databricks tillhandahåller en SQLAlchemy-dialekt(systemet SQLAlchemy använder för att kommunicera med olika typer av implementeringar och databaser för databas-API:et) för Azure Databricks. SQLAlchemy är en Python SQL-verktygslåda och Object Relational Mapper (ORM). SQLAlchemy tillhandahåller en uppsättning välkända beständighetsmönster på företagsnivå, utformade för effektiv och högpresterande databasåtkomst, anpassad till ett enkelt och Python-domänspråk. Se Funktioner och filosofi.

SQLAlchemy-dialekten för Azure Databricks måste installeras för att använda SQLAlchemy-funktionerna med Azure Databricks. Den här artikeln beskriver SQLAlchemy-dialekten för Azure Databricks version 1.0 och 2.0, som baseras på Databricks SQL Connector för Python version 4.0.0 eller senare.

Krav

  • En utvecklingsdator som kör Python >=3.8 och <=3.11.
  • Databricks rekommenderar att du använder virtuella Python-miljöer, till exempel de som tillhandahålls av venv som ingår i Python. Virtuella miljöer hjälper dig att se till att du använder rätt versioner av Python och Databricks SQL Connector för Python tillsammans. Att konfigurera och använda virtuella miljöer ligger utanför omfånget för den här artikeln. Mer information finns i Skapa virtuella miljöer.
  • Ett befintligt kluster eller SQL-lager.

Sätta igång

  • Installera databricks-sqlalchemy för SQLAlchemy v1 med hjälp av pip install databricks-sqlalchemy~=1.0 eller för SQLAlchemy v2 med hjälp av pip install databricks-sqlalchemy. Versionsinformation finns i versionshistoriken för databricks-sqlalchemy.

  • Samla in följande information för det kluster eller SQL-lager som du vill använda:

    Kluster

    • Servervärdnamnet för klustret. Du kan hämta detta från värdet Server Hostname i fliken Avancerade alternativ > JDBC/ODBC för klustret.
    • HTTP-sökvägen för klustret. Du kan hämta detta från -värdet för HTTP-sökväg i fliken Avancerade alternativJDBC/ODBC > för ditt kluster.

    SQL-lager

    • Servervärdnamnet för SQL-lagret. Du kan hämta detta från värdet Server Hostname på fliken Anslutningsinformation för DITT SQL-lager.
    • HTTP-sökvägen för SQL-lagret. Du kan hämta detta från HTTP Path-värdet på fliken Anslutningsinformation för ditt SQL-lager.

Autentisering

SQLAlchemy-dialekten för Azure Databricks använder Databricks SQL Connector för Python för att ansluta och skickar in värdena connect_args till connectorn. Den stöder följande autentiseringstyper:

Autentisering med personlig åtkomsttoken

Om du vill skapa en personlig åtkomsttoken för Azure Databricks följer du stegen i Skapa personliga åtkomsttoken för arbetsyteanvändare.

Om du vill autentisera SQLAlchemy-dialekten använder du följande kodfragment. Det här kodfragmentet förutsätter att du har angett följande miljövariabler:

  • DATABRICKS_TOKENställs in på en personlig åtkomsttoken för Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEställs in på värdet Server Hostname för din kluster eller SQL-datalager.
  • DATABRICKS_HTTP_PATH ställ in värdet för HTTP-sökväg för ditt kluster eller SQL-lager.
  • DATABRICKS_CATALOG ställs in på målkatalogen i Unity Catalog.
  • Ange DATABRICKS_SCHEMAtill målschemat (även kallat en databas) i Unity Catalog.

Information om hur du anger miljövariabler finns i dokumentationen till operativsystemet.

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

# ...

Du använder föregående engine variabel för att ansluta till den angivna katalogen och schemat via din Azure Databricks-beräkningsresurs.

OAuth-autentisering från användare till dator (U2M)

OAuth U2M-autentisering använder realtidsinloggning och samtycke för att autentisera det aktuella användarkontot för Azure Databricks. För Databricks SQL Connector för Python-versioner som stödjer det på varje moln, se OAuth user-to-machine (U2M) autentisering.

För att autentisera SQLAlchemy-dialekten med OAuth U2M, använd följande kodsnip. Detta kodavsnitt förutsätter att du har satt DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG, och DATABRICKS_SCHEMA miljövariablerna, som beskrivs i autentisering för personlig åtkomsttoken.

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-autentisering från dator till dator (M2M)

OAuth M2M-autentisering autentiserar sig som en Azure Databricks service principal. Du måste också installera Databricks SDK för Python (till exempel genom att köra pip install databricks-sdk). För Databricks SQL Connector för Python- och SDK-versioner som stödjer det i respektive moln, se OAuth machine-to-machine (M2M) autentisering.

För att använda OAuth M2M-autentisering, gör följande:

  1. Skapa ett tjänstehuvudnamn för Azure Databricks i din Azure Databricks-arbetsyta och skapa en OAuth-hemlighet för det tjänstehuvudnamnet. Se Auktorisera tjänstens huvudnamnsåtkomst till Azure Databricks med OAuth.
  2. Ge tjänstens huvudnamn åtkomst till ditt kluster eller SQL Warehouse. Se Beräkningsbehörigheter eller Hantera ett SQL-lager.

För att autentisera SQLAlchemy-dialekten med OAuth M2M, använd följande kodsnip. Utöver miljövariablerna DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG och DATABRICKS_SCHEMA förutsätter detta utdrag att du har ställt in följande miljövariabler:

  • DATABRICKS_CLIENT_ID, inställt på tjänstens huvudnamns UUID - eller program-ID-värde .
  • DATABRICKS_CLIENT_SECRET, ange värdet Hemlig för tjänstens huvudnamns OAuth-hemlighet.
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

Anslutningsexempel finns i den här example.py

SQLAlchemy v2

Anslutningsexempel finns i följande avsnitt och filen sqlalchemy_example.py i GitHub.

DBAPI-referens

Ytterligare resurser

  • Uppdaterades senast