Usar SQLAlchemy com o Azure Databricks

O Azure Databricks fornece SQLAlchemy como dialeto (o sistema que o SQLAlchemy usa para se comunicar com vários tipos de implementações e bancos de dados da API de banco de dados) para o Azure Databricks. SQLAlchemy é um kit de ferramentas SQL do Python e ORM (Object Relational Mapper). O SQLAlchemy fornece um conjunto de padrões de persistência de nível empresarial conhecidos, projetados para acesso eficiente e de alto desempenho ao banco de dados, adaptados em uma linguagem de domínio simples e idiomática em Python. Consulte Recursos e Filosofia.

O dialeto SQLAlchemy para o Azure Databricks precisa ser instalado para usar os recursos do SQLAlchemy com o Azure Databricks. Este artigo aborda o dialeto SQLAlchemy para o Azure Databricks versão 1.0 e 2.0, que será baseado no Conector sql do Databricks para Python versão 4.0.0 ou superior.

Requisitos

  • Um computador de desenvolvimento executando Python >=3.8 e <=3.11.
  • O Databricks recomenda que você use ambientes virtuais Python, como os fornecidos por venv que estão incluídos no Python. Os ambientes virtuais ajudam a garantir que você esteja usando as versões corretas do Python e do Conector do SQL do Databricks para Python juntos. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, confira Criando ambientes virtuais.
  • Um cluster ou SQL warehouse existente.

Introdução

  • Instale o databricks-sqlalchemy para SQLAlchemy v1 usando pip install databricks-sqlalchemy~=1.0 ou para SQLAlchemy v2 usando pip install databricks-sqlalchemy. Para obter informações sobre a versão, consulte o histórico de versões do databricks-sqlalchemy.

  • Reúna as seguintes informações sobre o cluster ou SQL warehouse que você deseja usar:

    Clúster

    SQL Warehouse

    • O nome de host do servidor do SQL warehouse. É possível obtê-lo no valor do Nome do host do servidor na guia Detalhes da conexão do SQL warehouse.
    • O caminho HTTP do SQL warehouse. É possível obtê-lo no valor de Caminho HTTP na aba Detalhes da conexão do SQL Warehouse.

Autenticação

O dialeto SQLAlchemy para Azure Databricks usa o Databricks SQL Connector para Python para se conectar e passa os valores em connect_args para o conector. Ele suporta os seguintes tipos de autenticação:

Autenticação de token de acesso pessoal

Para criar um token de acesso pessoal do Azure Databricks, siga as etapas em Criar tokens de acesso pessoal para usuários do workspace.

Para autenticar o dialeto SQLAlchemy, use o snippet de código a seguir. Esse snippet de código pressupõe que você tenha definido as seguintes variáveis de ambiente:

  • DATABRICKS_TOKEN, definido como o token de acesso pessoal do Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEdefinido como o valor Server Hostname do seu cluster ou SQL Warehouse.
  • DATABRICKS_HTTP_PATH, definido para o valor do Caminho HTTP para seu cluster ou SQL Warehouse.
  • DATABRICKS_CATALOG, defina como o catálogo de destino no Unity Catalog.
  • DATABRICKS_SCHEMA, definido como o esquema de destino (também conhecido como banco de dados) no Catálogo do Unity.

Para definir variáveis de ambiente, consulte a documentação do sistema operacional.

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 a variável engine anterior para se conectar ao catálogo e esquema que você especificou por meio do recurso de computação do Azure Databricks.

Autenticação U2M (usuário para computador) do OAuth

A autenticação OAuth U2M utiliza login humano em tempo real e consentimento para autenticar a conta de usuário Azure Databricks alvo. Para as versões do Databricks SQL Connector para Python que o suportam em cada nuvem, veja autenticação OAuth usuário para máquina (U2M).

Para autenticar o dialeto SQLAlchemy com OAuth U2M, use o seguinte trecho de código. Este trecho assume que você definiu as DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG e DATABRICKS_SCHEMA variáveis de ambiente, conforme descrito na autenticação de token de acesso pessoal.

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

# ...

Autenticação M2M (de computador para computador) do OAuth

A autenticação OAuth M2M autentica como um principal de serviço Azure Databricks. Você também deve instalar o SDK Databricks para Python (por exemplo, executando pip install databricks-sdk). Para as versões do Databricks SQL Connector para Python e SDK que o suportam em cada nuvem, veja autenticação OAuth máquina-a-máquina (M2M).

Para usar a autenticação OAuth M2M, faça o seguinte:

  1. Crie um principal de serviço do Azure Databricks no seu espaço de trabalho do Azure Databricks e gere um segredo OAuth para esse principal de serviço. Consulte Autorizar o acesso de entidade de serviço ao Azure Databricks usando OAuth.
  2. Dê a esse principal de serviço acesso ao seu cluster ou SQL warehouse. Consulte Permissões de computação ou Gerenciar um SQL warehouse.

Para autenticar o dialeto SQLAlchemy com OAuth M2M, use o seguinte trecho de código. Além das variáveis de ambiente DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG e DATABRICKS_SCHEMA, este trecho assume que você definiu as seguintes variáveis de ambiente:

  • DATABRICKS_CLIENT_ID, definido como o valor do UUID ou da ID do aplicativo da entidade de serviço.
  • DATABRICKS_CLIENT_SECRET, defina como Segredo para o segredo de OAuth da entidade de serviço.
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 obter exemplos de conexão, consulte esta example.py

SQLAlchemy v2

Para obter exemplos de conexão, consulte a seção a seguir e o arquivo sqlalchemy_example.py no GitHub.

Referência da DBAPI

Recursos adicionais

  • Última atualização em