Usar SQLAlchemy con Azure Databricks

Azure Databricks proporciona un SQLAlchemydialecto (el sistema que 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 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 la versión, 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

    almacén SQL

    • Nombre de host del servidor del almacén 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 SQL warehouse. Puede obtenerlo del valor de la ruta de acceso HTTP en la pestaña Detalles de conexión de su almacén 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

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, configurado con el token de acceso personal de Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEconfigúrelo en el valor de Nombre de host del servidor del clúster o almacén de datos SQL.
  • DATABRICKS_HTTP_PATH, establecido en el valor de Ruta de acceso HTTP del clúster o almacén 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 las versiones de Databricks SQL Connector para Python que lo admiten en cada nube, véase 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

La autenticación OAuth M2M se autentica como una 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:

  1. 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.
  2. 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, se establece en el UUID de la entidad de servicio o en el valor ID de Aplicación.
  • 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.

Referencia de DBAPI

Recursos adicionales

  • Se actualizó por última vez el