Usare SQLAlchemy con Azure Databricks

Azure Databricks fornisce un dialettoSQLAlchemy (il sistema che SQLAlchemy usa per comunicare con vari tipi di implementazioni di API di database e database) per Azure Databricks. SQLAlchemy è un toolkit Python SQL e ORM (Object Relational Mapper). SQLAlchemy offre una suite di modelli di persistenza di livello aziendale noti, progettati per l'accesso efficiente e ad alte prestazioni al database, adattati in un linguaggio di dominio semplice e pythonico. Consultare Funzionalità e filosofia.

Il dialetto SQLAlchemy per Azure Databricks deve essere installato per usare le funzionalità SQLAlchemy con Azure Databricks. Questo articolo illustra il dialetto SQLAlchemy per Azure Databricks versione 1.0 e 2.0, che sarà basato su Databricks SQL Connector per Python versione 4.0.0 o successiva.

Requisiti

  • Un computer di sviluppo che esegue Python >=3.8 e <=3.11.
  • Databricks consiglia di usare ambienti virtuali Python, ad esempio quelli forniti da venv inclusi in Python. Gli ambienti virtuali consentono di assicurarsi di usare insieme le versioni corrette di Python e il connettore SQL di Databricks per Python. La configurazione e l'uso di ambienti virtuali non rientra nell'ambito di questo articolo. Per altre informazioni, consultare Creare ambienti virtuali.
  • Un cluster esistente o SQL warehouse.

Inizia

  • Installare databricks-sqlalchemy per SQLAlchemy v1 usando pip install databricks-sqlalchemy~=1.0 o per SQLAlchemy v2 usando pip install databricks-sqlalchemy. Per informazioni sulla versione, vedere la cronologia delle versioni di databricks-sqlalchemy.

  • Raccogliere le informazioni seguenti per il cluster o SQL Warehouse da usare:

    Gruppo

    • Nome host del server del cluster. È possibile ottenerlo dal valore Server Hostname nella scheda Opzioni avanzate> JDBC/ODBC per il cluster.
    • Percorso HTTP del cluster. È possibile ottenerlo dal valore percorso HTTP nella scheda Opzioni Avanzate > JDBC/ODBC per il cluster.

    magazzino SQL

    • Nome host del server di SQL Warehouse. È possibile ottenere questo dal valore hostname del server nella scheda Dettagli connessione per il SQL Warehouse.
    • Percorso HTTP del warehouse SQL. È possibile ottenerlo dal valore percorso HTTP nella scheda Dettagli connessione per il tuo SQL Warehouse.

Autenticazione

Il dialetto SQLAlchemy per Azure Databricks utilizza il Databricks SQL Connector per Python per connettersi e passa i valori in connect_args al connettore. Supporta i seguenti tipi di autenticazione:

Autenticazione del token di accesso personale

Per creare un token di accesso personale di Azure Databricks, seguire la procedura descritta in Creare token di accesso personali per gli utenti dell'area di lavoro.

Per autenticare il dialetto SQLAlchemy, usare il frammento di codice seguente. Questo frammento presuppone che siano state impostate le variabili di ambiente seguenti:

  • DATABRICKS_TOKEN, impostare come token di accesso personale di Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEimpostato sul valore del nome host del server per il cluster o SQL Warehouse.
  • DATABRICKS_HTTP_PATH, impostato su il valore del percorso HTTP per il tuo cluster o magazzino dati SQL.
  • DATABRICKS_CATALOG, impostato per il catalogo di destinazione in Unity Catalog.
  • DATABRICKS_SCHEMA, impostato sullo schema di destinazione (noto anche come database) in Unity Catalog.

Per impostare le variabili di ambiente, vedere la documentazione del sistema operativo.

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

# ...

Usi la variabile engine precedente per connettersi al catalogo e allo schema specificati tramite la risorsa di calcolo di Azure Databricks.

Autenticazione OAuth da utente a macchina (U2M)

L'autenticazione OAuth U2M utilizza l'accesso umano in tempo reale e il consenso per autenticare l'account utente Azure Databricks di destinazione. Per le versioni di Databricks SQL Connector per Python che lo supportano su ogni cloud, vedi autenticazione OAuth da utente a macchina (U2M).

Per autenticare il dialetto SQLAlchemy con OAuth U2M, usa il seguente frammento di codice. Questo frammento presuppone che tu abbia impostato le variabili di ambiente DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG e DATABRICKS_SCHEMA, come descritto in Autenticazione con token di accesso personale.

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

# ...

Autenticazione OAuth da computer a computer (M2M)

L'autenticazione OAuth M2M autentica come un'entità servizio di Azure Databricks. Devi anche installare l'SDK Databricks per Python (ad esempio, eseguendo pip install databricks-sdk). Per le versioni di Databricks SQL Connector per Python e SDK che lo supportano su ogni cloud, vedi autenticazione OAuth machine-to-machine (M2M).

Per utilizzare l'autenticazione OAuth M2M, fai quanto segue:

  1. Crea un principale del servizio di Azure Databricks nel tuo spazio di lavoro di Azure Databricks e crea un segreto OAuth per quel principale del servizio. Consulta Autorizzare l'accesso del principale del servizio ad Azure Databricks con OAuth.
  2. Concedi a quel service principal l'accesso al tuo cluster o SQL warehouse. Vedere Autorizzazioni di calcolo o Gestire un magazzino dati SQL.

Per autenticare il dialetto SQLAlchemy con OAuth M2M, usa il seguente estratto di codice. Oltre alle variabili di ambiente DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG e DATABRICKS_SCHEMA, questo frammento presume che tu abbia impostato le seguenti variabili di ambiente:

  • DATABRICKS_CLIENT_ID, impostato sul valore UUID o ID applicazione del principale del servizio.
  • DATABRICKS_CLIENT_SECRET, impostato al valore Secret per il segreto OAuth del principale del servizio.
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

Per esempi di connessione, consultare questo file: example.py

SQLAlchemy v2

Per esempi di connessione, vedere la sezione seguente e il file sqlalchemy_example.py in GitHub.

Riferimento DBAPI

Risorse aggiuntive

  • Ultimo aggiornamento: