Usar SQLAlchemy con Azure Databricks

Azure Databricks proporciona una SQLAlchemydialecto (el sistema SQLAlchemy usa para comunicarse con varios tipos de implementaciones y bases de datos de API de base de datos) para Azure Databricks. SQLAlchemy es un kit de herramientas SQL de Python y un mapeador objeto-relacional (ORM). SQLAlchemy proporciona un conjunto de conocidos patrones de persistencia de nivel empresarial, diseñados para un acceso a bases de datos eficaz y de alto rendimiento, plasmados en un lenguaje de dominio sencillo y pythónico. Vea Características y filosofía.

El dialecto SQLAlchemy para Azure Databricks debe instalarse para usar las características de SQLAlchemy con Azure Databricks. En este artículo se describe el dialecto SQLAlchemy para Azure Databricks versión 1.0 y 2.0, que se basará en el Databricks SQL Connector para Python versión 4.0.0 o posterior.

Requisitos

Una máquina de desarrollo que ejecute Python >=3.8 y <=3.11.
Databricks recomienda usar entornos virtuales de Python, como los proporcionados por venv que se incluyen con Python. Los entornos virtuales ayudan a garantizar que usa las versiones correctas de Python y Databricks SQL Connector para Python juntos. La configuración y el uso de entornos virtuales están fuera del ámbito de este artículo. Para más información, consulte Creación de entornos virtuales.
Un clúster o un almacén de SQL existente.

Primeros pasos

Instale databricks-sqlalchemy para SQLAlchemy v1 mediante pip install databricks-sqlalchemy~=1.0 o para SQLAlchemy v2 mediante pip install databricks-sqlalchemy. Para obtener información sobre las versiones, consulta el historial de versiones de databricks-sqlalchemy.
Recopile la siguiente información para el clúster o almacén SQL que desea usar:

Clúster
- Nombre de host del servidor del clúster. Puedes obtenerlo a partir del valor Nombre de host del servidor en la pestaña Opciones avanzadas > JDBC/ODBC de tu clúster.
- Ruta de acceso HTTP del clúster. Puede obtenerlo del valor de la ruta de acceso HTTP en la pestaña Opciones avanzadas > JDBC/ODBC para su clúster.
Almacén de SQL
- Nombre de host del servidor del almacén de SQL. Puede obtenerlo del valor del nombre de host del servidor en la pestaña Detalles de conexión del almacén de SQL.
- Ruta de acceso HTTP del almacén de SQL. Puede obtenerlo del valor de la ruta de acceso HTTP en la pestaña Detalles de conexión del almacén de SQL.

Autenticación

El dialecto SQLAlchemy para Azure Databricks utiliza el conector SQL de Databricks para Python para conectarse, y pasa al conector los valores de connect_args. Soporta los siguientes tipos de autenticación:

Autenticación de token de acceso personal
Autenticación de usuario a máquina (U2M) de OAuth
Autenticación de máquina a máquina (M2M) de OAuth

Autenticación de token de acceso personal

Para crear un token de acceso personal de Azure Databricks, siga los pasos descritos en Creación de tokens de acceso personal para los usuarios del área de trabajo.

Para autenticar el dialecto SQLAlchemy, use el siguiente fragmento de código. En este fragmento, se da por supuesto que ha establecido las siguientes variables de entorno:

DATABRICKS_TOKEN, establecido en el token de acceso personal de Azure Databricks.
DATABRICKS_SERVER_HOSTNAMEEstablece el valor Nombre de host del servidor para tu clúster o almacén SQL.
DATABRICKS_HTTP_PATH, establecido en el valor de la ruta HTTP de su clúster o almacén de SQL.
DATABRICKS_CATALOG, establecido en el catálogo de destino en Unity Catalog.
DATABRICKS_SCHEMA, establecido en el esquema de destino (también conocido como base de datos) en Unity Catalog.

Para establecer variables de entorno, consulte la documentación 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}"
)

# ...

Use la variable anterior engine para conectarse a su catálogo y esquema especificados mediante el recurso de proceso de Azure Databricks.

Autenticación de usuario a máquina (U2M) de OAuth

La autenticación OAuth U2M utiliza inicio de sesión humano en tiempo real y consentimiento para autenticar la cuenta de usuario de Azure Databricks objetivo. Para conocer las versiones del conector SQL de Databricks para Python que lo admiten en cada nube, consulta Autenticación OAuth de usuario a máquina (U2M).

Para autenticar el dialecto SQLAlchemy con OAuth U2M, utiliza el siguiente fragmento de código. Este fragmento asume que has establecido las variables de entorno DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG y DATABRICKS_SCHEMA, tal y como se describe en la autenticación de token de acceso personal.

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

# ...

Autenticación de máquina a máquina (M2M) de OAuth

Autenticación OAuth M2M: se autentica como entidad de servicio de Azure Databricks. También debes instalar el SDK Databricks para Python (por ejemplo, ejecutando pip install databricks-sdk). Para las versiones de Databricks SQL Connector para Python y SDK que lo soportan en cada nube, véase autenticación OAuth máquina a máquina (M2M).

Para usar la autenticación OAuth M2M, haz lo siguiente:

Cree una entidad de servicio de Azure Databricks en el área de trabajo de Azure Databricks y cree un secreto de OAuth para esa entidad de servicio. Consulte Autorizar el acceso de una entidad de servicio a Azure Databricks con OAuth.
Dale a ese principal de servicio acceso a tu clúster o almacén SQL. Consulte Permisos de proceso o Administración de un almacenamiento de SQL.

Para autenticar el dialecto SQLAlchemy con OAuth M2M, utiliza el siguiente fragmento de código. Además de las variables de entorno DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG y DATABRICKS_SCHEMA, este fragmento presupone que has establecido las siguientes variables de entorno:

DATABRICKS_CLIENT_ID, establecido en el valor del UUID o Id. de aplicación de la entidad de servicio.
DATABRICKS_CLIENT_SECRET, configurado al valor secreto para el secreto OAuth del principal de servicio.

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

Para obtener ejemplos de conexión, consulte este example.py

SQLAlchemy v2

Para ver ejemplos de conexión, consulte la sección siguiente y el archivo sqlalchemy_example.py en GitHub.

Usar SQLAlchemy con Azure Databricks

Requisitos

Primeros pasos

Clúster

Almacén de SQL