Azure Databricks で SQLAlchemy を使用する

Azure Databricks では、Azure Databricks 用の SQLAlchemydialect (SQLAlchemy がさまざまな種類のデータベース API 実装やデータベースと通信するために使用するシステム) が提供されます。 SQLAlchemy は、Python SQL ツールキットであり、オブジェクト リレーショナル マッパー (ORM) です。 SQLAlchemy は、効率的で高パフォーマンスのデータベース アクセス用に設計された、よく知られたエンタープライズ レベルの永続化パターンのスイートを、シンプルで Python らしいドメイン言語に適合させて提供します。 「特徴と哲学」を参照してください。

Azure Databricks で SQLAlchemy 機能を使用するには、Azure Databricks の SQLAlchemy 方言をインストールする必要があります。 この記事では、Databricks SQL Connector for Python バージョン 4.0.0 以降に基づく Azure Databricks バージョン 1.0 および 2.0 の SQLAlchemy 言語について説明します。

要件

  • Python >=3.8 かつ <=3.11 の開発マシン。
  • Databricks では、Python 仮想環境 (Python に含まれる venv によって提供されるものなど) を使用することをお勧めしています。 仮想環境は、正しいバージョンの Python と Databricks SQL Connector for Python を一緒に使用していることを確認するのに役立ちます。 仮想環境のセットアップと使用は、この記事の範囲外です。 詳細については、「仮想環境を作成する」を参照してください。
  • 既存のクラスターまたは SQL ウェアハウス。

概要

  • pip install databricks-sqlalchemy~=1.0を使用して SQLAlchemy v1 用または pip install databricks-sqlalchemy を使用して SQLAlchemy v2 用に databricks-sqlalchemy をインストールします。 バージョン情報については、 databricks-sqlalchemy リリース履歴を参照してください。

  • 使用するクラスターまたは SQL ウェアハウスに関する次の情報を収集します。

    クラスター

    • クラスターのサーバー ホスト名。 これは、クラスターのAdvanced Options > JDBC/ODBCタブにあるServer Hostnameの値から取得できます。
    • クラスターの HTTP パス。 これは、クラスターの [詳細オプション]> [JDBC/ODBC] タブにある [HTTP パス] の値から取得できます。

    SQL ウェアハウス

    • SQL ウェアハウスのサーバー ホスト名。 これは、SQL ウェアハウスの [接続の詳細] タブにある [サーバー ホスト名] の値から取得できます。
    • SQL ウェアハウスの HTTP パス。 これは、SQL ウェアハウスの [接続の詳細] タブにある [HTTP パス] の値から取得できます。

認証

Azure DatabricksのSQLAlchemy方言は、Python 用 Databricks SQL Connector を使用して接続し、connect_argsの値をコネクタに渡します。 以下の認証タイプをサポートしています:

パーソナルアクセストークン認証

Azure Databricks 個人用アクセス トークンを作成するには、「 ワークスペース ユーザーの個人用アクセス トークンを作成する」の手順に従います。

SQLAlchemy dialect を使用するには、次のコード スニペットを使用します。 このスニペットでは、次の環境変数を設定していることを前提としています。

  • DATABRICKS_TOKEN: Azure Databricks 個人用アクセス トークンに設定。
  • DATABRICKS_SERVER_HOSTNAMEを、クラスターまたは SQL ウェアハウスのサーバー ホスト名の値に設定します。
  • DATABRICKS_HTTP_PATH を、クラスターまたは SQL ウェアハウスの HTTP パスの値に設定します。
  • DATABRICKS_CATALOG、Unity カタログのターゲット カタログに設定。
  • 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 for Python の各クラウドで対応しているバージョンについては、OAuthユーザー対マシン認証(U2M)を参照してください。

OAuth U2MでSQLAlchemyダイアレクトを認証するには、以下のコードスニペットを使用します。 このスニペットは、DATABRICKS_SCHEMAで説明されているように、、DATABRICKS_SERVER_HOSTNAME、DATABRICKS_HTTP_PATH、DATABRICKS_CATALOG 環境変数を設定したことを前提としています。

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 authentication は Azure Databricks service principal として認証されます。 また、Databricks SDK for Pythonもインストールする必要があります(例えば、pip install databricks-sdk を実行して)。 各クラウドでそれをサポートする Databricks SQL Connector for Python および SDK のバージョンについては、OAuthマシン間認証(M2M)を参照してください。

OAuth M2M認証を使用するには、以下の手順を行います:

  1. Azure Databricks ワークスペースで Azure Databricks サービス プリンシパルを作成し、そのサービス プリンシパルの OAuth シークレットを作成します。 OAuth を使用した Azure Databricks へのサービス プリンシパル アクセスの認可に関するページを参照してください。
  2. そのサービスプリンシパルにクラスタやSQLウェアハウスへのアクセス権を与えてください。 「コンピューティングのアクセス許可」または「SQL ウェアハウスを管理する」を参照してください。

OAuth M2MでSQLAlchemy方言を認証するには、以下のコードスニペットを使用します。 DATABRICKS_SERVER_HOSTNAME、DATABRICKS_HTTP_PATH、DATABRICKS_CATALOG、DATABRICKS_SCHEMA環境変数に加え、このスニペットは以下の環境変数を設定していると仮定しています:

  • DATABRICKS_CLIENT_IDは、サービス プリンシパルの UUID または アプリケーション ID の値に設定されます。
  • 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 v1

接続例については、この example.py を参照してください。

SQLAlchemy v2

接続の例については、次のセクションと GitHub の sqlalchemy_example.py ファイルを参照してください。

DBAPI リファレンス

その他のリソース