Databricks で SQLAlchemy を使用する

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

Databricks の SQLAlchemy ダイアレクトは、 Databricks SQL Connector for Python に含まれています。 この記事では、Databricks SQL Connector for Python バージョン 3.0.0 を必要とする Databricks バージョン 2.0 の SQLAlchemy 方言について説明します 以上です。

要件

• Python >=3.8 および <=3.11 を実行している開発マシン。

• Databricks では、Python に含まれる venv によって提供されるものなど、Python 仮想環境を使用することをお勧めします。 仮想環境は、正しいバージョンの Python と Databricks SQL Connector for Python を一緒に使用するのに役立ちます。 仮想環境の設定と使用は、この記事の範囲外です。 詳細については、「 仮想環境の作成」を参照してください。

• 既存のクラスターまたはSQL ウェアハウス。

はじめに

• Databricks SQL Connector for Python ライブラリ バージョン 3.0.0 をインストールする または、開発用コンピューターで pip install "databricks-sql-connector[sqlalchemy]" または python -m pip install "databricks-sql-connector[sqlalchemy]"を実行して、 以上を実行します。 バージョン情報については、 databricks-sql-connector のリリース履歴を参照してください。

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

  • クラスターのサーバー・ホスト名。 これは、クラスターの [ Advanced Options] > [JDBC/ODBC ] タブの [Server ホスト名 ] の値から取得できます。

  • クラスターの HTTP パス。 これは、クラスターの [ Advanced Options] > [JDBC/ODBC ] タブの [HTTP Path] ( HTTP パス ) 値から取得できます。

  • SQLウェアハウスのサーバーホスト名。 これは、SQLウェアハウスの「 接続の詳細 」タブの 「サーバー・ホスト名 」の値から取得できます。

  • SQLウェアハウスの HTTP パス。 これは、SQLウェアハウスの「 接続の詳細 」タブの 「HTTPパス 」値から取得できます。

認証

Databricks の SQLAlchemy ダイアレクトでは、Databricks の個人用アクセストークン認証がサポートされています。

Databricks 個人用アクセストークンを作成するには、次の操作を行います。

1. Databricks ワークスペースで、上部のバーにある Databricks ユーザー名をクリックし、ドロップダウンから[設定]を選択します。

2. [ 開発者] をクリックします。

3. [アクセストークン] の横にある [管理] をクリックします。

4. [ 新しいトークンの生成] をクリックします。

5. （任意）今後このトークンを識別するのに役立つコメントを入力し、トークンのデフォルトの有効期間である90日を変更します。有効期間のないトークンを作成するには（非推奨）、[有効期間 (日) ] ボックスを空白のままにしてください。

6. [生成] をクリックします。

7. 表示されたトークンを安全な場所にコピーし、[完了] をクリックします。

注：

コピーしたトークンは、必ず安全な場所に保存してください。 コピーしたトークンを他のユーザーと共有しないでください。 コピーしたトークンを紛失した場合、まったく同じトークンを再生成することはできません。 代わりに、この手順を繰り返して新しいトークンを作成する必要があります。 コピーしたトークンを紛失した場合、またはトークンが侵害されたと思われる場合は、アクセストークン ページでトークンの横にあるごみ箱 (取り消し) アイコンをクリックして、ワークスペースからそのトークンをすぐに削除することを強くお勧めします。

ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。

• ワークスペースの個人用アクセストークン認証を有効または無効にする

• 個人用アクセストークンのアクセス許可

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

• DATABRICKS_TOKENを Databricks personal アクセストークンに設定します。

• DATABRICKS_SERVER_HOSTNAMEをクラスターまたは SQLウェアハウスの [Server Hostname ] の値に設定します。

• DATABRICKS_HTTP_PATHで、クラスターまたは SQLウェアハウスの HTTP パス 値に設定します。

• DATABRICKS_CATALOGで、Unity Catalog のターゲット カタログに設定されます。

• DATABRICKS_SCHEMAは、Unity Catalog のターゲット スキーマ (データベースとも呼ばれます) に設定されます。

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

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 コンピュート リソースを介して指定したカタログとスキーマに接続します。 接続の例については、次のセクションと GitHub の sqlalchemy.py ファイルを参照してください。

の例

GitHub の sqlalchemy.py ファイルを参照してください。

DBAPI リファレンス

• GitHub の README.sqlalchemy.md ファイルを参照してください。

• GitHub の sqlalchemy ソース コード ディレクトリも参照してください。

関連リソース

• SQLAlchemy統合チュートリアル