Use SQLAlchemy com Databricks

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

O dialeto SQLAlchemy para Databricks está incluído no Databricks SQL Connector para Python. Este artigo aborda o dialeto SQLAlchemy para Databricks versão 2.0, que requer Databricks SQL Connector para Python versão 3.0.0 ou acima.

Requisitos

  • Uma máquina de desenvolvimento executando Python >=3.8 e <=3.11.

  • A Databricks recomenda que utilize ambientes virtuais Python, como os fornecidos pela venv que estão incluídos no Python. Os ambientes virtuais ajudam a garantir que você está usando as versões corretas do Python e do Databricks SQL Connector para Python juntos. Configurar e usar ambientes virtuais está fora do escopo deste artigo. Para mais informações, consulte Criando ambientes virtuais.

  • Uma empresa existente cluster ou SQL warehouse.

Começar

  • Instale a biblioteca Databricks SQL Connector para Python versão 3.0.0 ou acima em sua máquina de desenvolvimento executando pip install "databricks-sql-connector[sqlalchemy]" ou python -m pip install "databricks-sql-connector[sqlalchemy]". Para obter informações sobre a versão, consulte a história de lançamento do databricks-sql-connector.

  • Reúna as seguintes informações para os clusters ou SQL warehouse que você deseja usar:

    • O hostname do servidor do SQL warehouse. Você pode obter isso no valor do servidor hostname na Detalhes da conexão tab do seu SQL warehouse.

    • O caminho HTTP do SQL warehouse. Você pode obter isso no valor HTTP Path na Connection Details tab do SQL warehouse seu .

Autenticação

O dialeto SQLAlchemy para Databricks oferece suporte à autenticação access token pessoal do Databricks.

Para criar um access token pessoal do Databricks, faça o seguinte:

  1. Em seu Databricks workspace, clique em seu nome de usuário Databricks na barra superior e selecione Settings (Configurações ) no menu suspenso.

  2. Clique em Desenvolvedor.

  3. Ao lado do access token, clique em gerenciar.

  4. Clique em Gerar novos tokens.

  5. (Opcional) Insira um comentário que o ajude a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem vida útil (não recomendado), deixe a caixa Duração (dias) vazia (em branco).

  6. Clique em Gerar.

  7. Copie o token exibido em um local seguro e clique em Concluído.

Observação

Certifique-se de salvar os tokens copiados em um local seguro. Não compartilhe seus tokens copiados com outras pessoas. Se você perder os tokens copiados, não poderá regenerar exatamente os mesmos tokens. Em vez disso, você deve repetir este procedimento para criar novos tokens. Se você perder os tokens copiados ou acreditar que os tokens foram comprometidos, o Databricks recomenda fortemente que você exclua imediatamente esses tokens do seu workspace clicando no ícone da lixeira (Revogar) ao lado dos tokens na página access tokens .

Se não for possível criar ou usar tokens no seu workspace, isso pode ocorrer porque o administrador do workspace desativou os tokens ou não lhe deu permissão para criar ou usar tokens. Consulte o administrador do workspace ou o seguinte:

Para autenticar o dialeto SQLAlchemy, use o trecho de código a seguir. Este trecho pressupõe que você definiu a seguinte variável de ambiente:

  • DATABRICKS_TOKEN, defina como o access token pessoal do Databricks.

  • DATABRICKS_SERVER_HOSTNAMEdefinido como o valor hostnamedo servidor para seus clusters ou SQL warehouse.

  • DATABRICKS_HTTP_PATH, defina o valor do Caminho HTTP para seus clusters ou SQL warehouse.

  • DATABRICKS_CATALOG, defina como o catálogo de destino no Unity Catalog.

  • DATABRICKS_SCHEMA, defina como o esquema de destino (também conhecido como banco de dados) no Unity Catalog.

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

# ...

Você usa a variável engine anterior para se conectar ao catálogo e esquema especificados por meio do recurso compute do Databricks. Para obter exemplos de conexão, consulte a seção a seguir e o arquivo sqlalchemy.py no GitHub.

Exemplo

Consulte o arquivo sqlalchemy.py no GitHub.

Referência DBAPI

Recursos adicionais