Pular para o conteúdo principal
Última atualização em

Usar o SQLAlchemy com a Databricks

A Databricks fornece um dialeto SQLAlchemy (o sistema que o SQLAlchemy usa para se comunicar com vários tipos de implementações de API de banco de dados e bancos de dados) para a Databricks. O SQLAlchemy é um kit de ferramentas SQL Python e um mapeador objeto-relacional (ORM). O SQLAlchemy fornece um conjunto de padrões de persistência de nível corporativo conhecidos, projetados para acesso eficiente e de alto desempenho ao banco de dados, adaptados a uma linguagem de domínio simples e Pythonic. Ver recurso e Filosofia.

O dialeto SQLAlchemy para Databricks precisa ser instalado para usar o recurso SQLAlchemy com Databricks. Este artigo aborda o dialeto SQLAlchemy para Databricks versão 1.0 e 2.0, que será baseado no conector Databricks SQL para Python versão 4.0.0 ou superior.

Requisitos​

  • Uma máquina de desenvolvimento executando Python >=3.8 e <=3.11.
  • A Databricks recomenda que o senhor use ambientes virtuais Python, como os fornecidos pelo venv que estão incluídos no Python. Os ambientes virtuais ajudam a garantir que o senhor esteja usando as versões corretas do Python e do Databricks SQL Connector for Python juntos. A configuração e o uso de ambientes virtuais estão fora do escopo deste artigo. Para obter mais informações, consulte Criação de ambientes virtuais.
  • Um clustering existente ou SQL warehouse.

Começar​

  • Instale 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 para o clustering ou SQL warehouse que o senhor deseja usar:

Autenticação​

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

Autenticação de access token pessoal​

Para criar um access token pessoal Databricks , siga os passos em Criar access tokens pessoal para usuários workspace.

Para autenticar o dialeto SQLAlchemy, use o seguinte trecho de código. Esse snippet pressupõe que o senhor tenha definido a seguinte variável de ambiente:

  • DATABRICKS_TOKEN, definido como os tokens de acesso pessoal Databricks.
  • DATABRICKS_SERVER_HOSTNAMEdefinido como o valor do Server Hostname para seu clustering ou SQL warehouse.
  • DATABRICKS_HTTP_PATHDefina o valor do caminho HTTP para seu clustering ou SQL warehouse.
  • DATABRICKS_CATALOGdefinido como o catálogo de destino no Unity Catalog.
  • DATABRICKS_SCHEMAdefinido para o esquema de destino (também conhecido como banco de dados) no Unity Catalog.

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

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

# ...

O senhor usa a variável engine anterior para se conectar ao catálogo e ao esquema especificados por meio do recurso Databricks compute .

Autenticação OAuth user-to-machine (U2M)​

A autenticação OAuth U2M usa o login humano em tempo real e o consentimento para autenticar a account de usuário de destino do Databricks. Para as versões do Conector SQL do Databricks para Python que o suportam em cada cloud, consulte Autenticação de usuário para máquina (U2M) OAuth.

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

Python
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 OAuth machine-to-machine (M2M)​

A autenticação OAuth M2M autentica como uma Service Principal do Databricks. Você também deve instalar o SDK do Databricks para Python (por exemplo, executando pip install databricks-sdk). Para o Databricks SQL Connector para Python e versões do SDK compatíveis com ele em cada cloud, consulte Autenticação OAuth máquina a máquina (M2M).

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

  1. Crie um Service Principal do Databricks em seu Workspace do Databricks e crie um segredo OAuth para esse Service Principal. Consulte Autorizar acesso da Service Principal do Databricks ao Databricks com OAuth.
  2. Conceda a essa Service Principal acesso ao seu cluster ou SQL Warehouse. Consulte Permissões de compute 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 snippet pressupõe que você definiu as seguintes variáveis de ambiente:

  • DATABRICKS_CLIENT_ID, definido como o valor do UUID ou ID do aplicativo da Service Principal.
  • DATABRICKS_CLIENT_SECRET, definido como o valor do Segredo para o segredo OAuth do Service Principal.
Python
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 exemplos de conexão, consulte este 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 do DBAPI​

Recurso adicional​

Nesta página