Использование SQLAlchemy с Azure Databricks

Azure Databricks предоставляет SQLAlchemyдиалект (систему, которую SQLAlchemy использует для взаимодействия с различными типами реализаций API баз данных и базами данных) для Azure Databricks. SQLAlchemy — это SQL-инструментарий для Python и объектно-реляционное отображение (ORM). SQLAlchemy предоставляет набор известных шаблонов персистентности корпоративного уровня, предназначенных для эффективного и высокопроизводительного доступа к базе данных, адаптированных в простой, идиоматичный для Python предметно-ориентированный язык. См. Функции и философия.

Диалект SQLAlchemy для Azure Databricks необходимо установить для использования функций SQLAlchemy с Azure Databricks. В этой статье рассматривается диалект SQLAlchemy для Azure Databricks версии 1.0 и 2.0, который будет основан на соединителе SQL Databricks для Python версии 4.0.0 или более поздней.

Требования

  • Машина разработки под управлением Python >=3.8 и <=3.11.
  • Databricks рекомендует использовать виртуальные среды Python, например среду venv, входящую в состав Python. Виртуальные среды помогают обеспечить использование правильных версий Python и Соединителя SQL Databricks для Python вместе. Настройка и использование виртуальных сред выходят за рамки этой статьи. Дополнительные сведения см. в статье «Создание виртуальных сред».
  • Существующий кластер или хранилище SQL.

Начало работы

  • Установите databricks-sqlalchemy для SQLAlchemy версии 1 с помощью pip install databricks-sqlalchemy~=1.0 или SQLAlchemy версии 2 с помощью pip install databricks-sqlalchemy. См. сведения о версии в истории выпусков databricks-sqlalchemy .

  • Соберите следующие сведения о кластере или хранилище SQL, которое вы хотите использовать:

    Кластер

    • Имя хоста сервера кластера. Вы можете получить это из значения имени узла сервера на вкладке Дополнительные параметры JDBC/ODBC для вашего кластера.
    • HTTP-путь кластера. Это можно получить из значения пути HTTP на вкладке дополнительные параметры JDBC/ODBC кластера.

    Хранилище SQL

    • Имя хоста хранилища SQL. Вы можете получить это из значения имени узла сервера на вкладке "Сведения о подключении" для вашего хранилища SQL.
    • Путь HTTP хранилища SQL. Это можно получить из значения пути HTTP на вкладке сведения о подключении для хранилища SQL.

Проверка подлинности

Диалект SQLAlchemy для Azure Databricks использует Databricks SQL Connector для Python для подключения и передаёт значения connect_args в соединитель. Он поддерживает следующие типы аутентификации:

Аутентификация персонального токена доступа

Чтобы создать личный маркер доступа Azure Databricks, выполните действия, описанные в разделе "Создание личных маркеров доступа для пользователей рабочей области".

Для аутентификации диалекта SQLAlchemy используйте следующий фрагмент кода. В этом фрагменте предполагается, что вы установили следующие переменные среды:

  • Установите DATABRICKS_TOKENдля токена личного доступа Azure Databricks.
  • задать значение имени узла сервера для кластера или хранилища SQL.
  • DATABRICKS_HTTP_PATHзадайте значение пути HTTP для кластера или хранилища SQL.
  • DATABRICKS_CATALOG, установите целевой каталог в Unity Catalog.
  • DATABRICKS_SCHEMA, установите целевую схему (также называемую базой данных) в каталоге Unity.

Чтобы задать переменные среды, ознакомьтесь с документацией операционной системы.

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

# ...

Предыдущая engine переменная используется для подключения к указанному каталогу и схеме через вычислительный ресурс Azure Databricks.

Аутентификация OAuth по схеме пользователь - машина (U2M)

OAuth U2M-аутентификация использует вход пользователя в систему в реальном времени и его согласие для аутентификации целевой учетной записи пользователя Azure Databricks. Для версий Databricks SQL Connector для Python, которые поддерживаются в каждом облаке, см. аутентификацию OAuth user-to-machine (U2M).

Для аутентификации диалекта SQLAlchemy с помощью OAuth U2M используйте следующий фрагмент кода. Этот фрагмент предполагает, что вы установили переменные среды DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG и DATABRICKS_SCHEMA, как описано в Personal access token authentication.

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

# ...

Аутентификация OAuth для взаимодействия машина-машина (M2M)

Аутентификация OAuth M2M выполняет аутентификацию как субъект-служба Azure Databricks. Также необходимо установить SDK Databricks для Python (например, запустив pip install databricks-sdk). Сведения о версиях Databricks SQL Connector for Python и SDK, которые поддерживают эту возможность в каждом облаке, см. в аутентификация OAuth типа «машина-машина» (M2M).

Чтобы использовать аутентификацию OAuth M2M, выполните следующее:

  1. Создайте сервисный принципал Azure Databricks в рабочей области Azure Databricks и создайте секрет OAuth для этого сервисного принципала. См Авторизация доступа сервисного принципала к Azure Databricks с помощью OAuth.
  2. Дайте этому субъекту-службе доступ к вашему кластеру или хранилищу SQL. См. сведения о разрешениях вычислений или управлении хранилищем SQL.

Для аутентификации диалекта SQLAlchemy с помощью OAuth M2M используйте следующий фрагмент кода. В дополнение к переменным среды DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG и DATABRICKS_SCHEMA этот фрагмент предполагает, что вы установили следующие переменные среды:

  • DATABRICKS_CLIENT_IDУстановите для главного объекта службы значение UUID или идентификатор приложения.
  • DATABRICKS_CLIENT_SECRET, установите значение секрет для OAuth секрета служебного принципала.
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 версии 1

Примеры подключения можно увидеть в этом example.py

SQLAlchemy версии 2

Примеры подключения см. в следующем разделе и файле sqlalchemy_example.py в GitHub.

Справочник по DBAPI

Дополнительные ресурсы

  • Последнее обновление: