メインコンテンツまでスキップ
に最終更新

DatabricksでSQLAlchemyを使用する

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

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

必要条件​

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

はじめに​

  • pip install databricks-sqlalchemy~=1.0 を使用して SQLAlchemy v1 に databricks-sqlalchemy をインストールするか、pip install databricks-sqlalchemyを使用して SQLAlchemy v2 をインストールします。バージョン情報については、 databricks-sqlalchemy のリリース履歴を参照してください。
  • 使用するクラスターまたは SQLウェアハウスについて、次の情報を収集します。
  • クラスターのサーバ・ホスト名。 これは、クラスターの[Advanced OptionsJDBC (詳細オプション)]ODBC > / タブの[Server Hostname (サーバー ホスト名)] の値から取得できます。
  • クラスタリングの HTTP パス。 これは、クラスタリングの[Advanced OptionsJDBC ODBC (詳細オプション)] > / タブの[HTTP Path (HTTP パス)] の値から取得できます。

認証​

Databricks の SQLAlchemy ダイアレクトは、Databricks SQL Connector for Python を使用して接続し、 connect_args の値をコネクタに渡します。これは次の認証タイプをサポートします。

個人用アクセストークン認証​

Databricksの個人アクセス ノートを作成するには、 「ワークスペース ユーザー向けの個人アクセス ノートを作成する」のステップに従います。

SQLAlchemy ダイアレクトを認証するには、次のコードスニペットを使用します。 このスニペットは、次の環境変数を設定していることを前提としています。

  • DATABRICKS_TOKENで、Databricks 個人用アクセス トークンに設定されます。
  • DATABRICKS_SERVER_HOSTNAMEクラスターまたはウェアハウスの Server Hostname 値 SQLに設定します。
  • DATABRICKS_HTTP_PATHで、クラスターまたはSQL ウェアハウスの HTTP パス 値に設定します。
  • DATABRICKS_CATALOGで、Unity Catalog のターゲット カタログに設定します。
  • DATABRICKS_SCHEMAは、Unity Catalog のターゲット スキーマ (データベースとも呼ばれます) に設定されます。

環境変数を設定するには、オペレーティングシステムのドキュメントを参照してください。

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

# ...

前述の engine 変数を使用して、 Databricks コンピュート リソースを介して指定したカタログとスキーマに接続します。

OAuth ユーザーマシン間 (U2M) 認証​

OAuth U2M認証では、リアルタイムの人間によるサインインと同意を使用して、ターゲットの Databricks ユーザーアカウントを認証します。各クラウドでサポートされている Databricks SQL Connector for Python バージョンについては、「 OAuth ユーザーマシン間 (U2M) 認証」を参照してください。

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

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

# ...

OAuthマシン間 (M2M) 認証​

OAuth M2M認証は、Databricks Service Principalとして認証します。また、Databricks SDK for Pythonもインストールする必要があります（例えば、pip install databricks-sdkを実行してインストールします）。各クラウドでサポートされている Databricks SQL Connector for Python および SDK バージョンについては、「 OAuth マシン間 (M2M) 認証」を参照してください。

OAuth M2M認証を使用するには、次の手順を実行します。

  1. DatabricksワークスペースにDatabricks Service Principalを作成し、そのService PrincipalのOAuthシークレットを作成します。OAuth を使用した Databricks への Databricks Service Principal アクセスの承認を参照してください。
  2. Service Principalに、クラスターまたはSQL Warehouseへのアクセス権を付与します。コンピュートの権限またはSQLウェアハウスの管理を参照してください。

OAuth M2M で SQLAlchemy ダイアレクトを認証するには、次のコードスニペットを使用します。このスニペットは、 DATABRICKS_SERVER_HOSTNAME 、 DATABRICKS_HTTP_PATH 、 DATABRICKS_CATALOG 、および DATABRICKS_SCHEMA 環境変数に加えて、次の環境変数を設定していることを前提としています。

  • DATABRICKS_CLIENT_ID、Service Principalの UUID または Application ID の値に設定されます。
  • DATABRICKS_CLIENT_SECRETをService PrincipalのOAuthシークレットの シークレット の値に設定します。
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 (英語)​

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

SQLAlchemy v2 (英語)​

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

DBAPI リファレンス​

追加のリソース​

このページの見出し