通过

将 SQLAlchemy 与 Azure Databricks 配合使用

  • 项目

Azure Databricks 为 Azure Databricks 提供 SQLAlchemy 方言（SQLAlchemy 用于与各种类型的数据库 API 实现和数据库进行通信的系统）。 SQLAlchemy 是 Python SQL 工具包和对象关系映射器 (ORM)。 SQLAlchemy 提供了一整套众所周知的企业级持久性模式，旨在实现高效且高性能的数据库访问，并采用简单的 Pythonic 域语言。 请参阅特征和理念。

Azure Databricks SQLAlchemy 方言随附于适用于 Python 的 Databricks SQL 连接器中。 本文介绍 Azure Databricks 版本 2.0 的 SQLAlchemy 方言，这需要适用于 Python 的 Databricks SQL 连接器版本 3.0.0 或更高版本。

要求

  • 运行 Python >=3.8 和<=3.11 的开发计算机。
  • Databricks 建议使用 Python 虚拟环境，例如 python 随附的 venv 提供的环境。 虚拟环境有助于确保同时使用正确版本的 Python 和适用于 Python 的 Databricks SQL 连接器。 设置和使用虚拟环境不在本文的讨论范围之内。 有关详细信息，请参阅创建虚拟环境。
  • 现有群集或 SQL 仓库。

开始使用

  • 通过运行 pip install "databricks-sql-connector[sqlalchemy]" 或 python -m pip install "databricks-sql-connector[sqlalchemy]"，在开发计算机上安装适用于 Python 的 Databricks SQL 连接器库版本 3.0.0 或更高版本。 有关版本信息，请参阅 databricks-sql-connector 发布历史记录。

  • 收集想要使用的群集或 SQL 仓库的以下信息：

    群集

    SQL 仓库

    • SQL 仓库的服务器主机名。 从 SQL 仓库的“连接详细信息”选项卡的“服务器主机名”值中可以获取此主机名。
    • SQL 仓库的 HTTP 路径。 从 SQL 仓库的“连接详细信息”选项卡的“HTTP 路径”值中可以获取此路径。

身份验证

Azure Databricks 的 SQLAlchemy 方言支持 Azure Databricks 个人访问令牌身份验证。

要创建 Azure Databricks 个人访问令牌，请执行以下操作：

  1. 在 Azure Databricks 工作区中，单击顶部栏中的 Azure Databricks 用户名，然后从下拉列表中选择“设置”。
  2. 单击“开发人员”。
  3. 在“访问令牌”旁边，单击“管理”。
  4. 单击“生成新令牌”。
  5. （可选）输入有助于将来识别此令牌的注释，并将令牌的默认生存期更改为 90 天。 若要创建没有生存期的令牌（不建议），请将“生存期(天)”框留空（保留空白）。
  6. 单击“生成” 。
  7. 将显示的令牌复制到安全位置，然后单击“完成”。

注意

请务必将复制的令牌保存到安全的位置。 请勿与他人共享复制的令牌。 如果丢失了复制的令牌，你将无法重新生成完全相同的令牌， 而必须重复此过程来创建新令牌。 如果丢失了复制的令牌，或者认为令牌已泄露，Databricks 强烈建议通过单击“访问令牌”页上令牌旁边的垃圾桶（撤销）图标立即从工作区中删除该令牌。

如果你无法在工作区中创建或使用令牌，可能是因为工作区管理员已禁用令牌或未授予你创建或使用令牌的权限。 请与工作区管理员联系，或参阅以下主题：

要对 SQLAlchemy 方言进行身份验证，请使用以下代码片段。 此代码片段假定你已设置以下环境变量：

  • DATABRICKS_TOKEN，设置为 Azure Databricks 个人访问令牌。
  • DATABRICKS_SERVER_HOSTNAME，设置为你的群集或 SQL 仓库的服务器主机名值。
  • 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 变量通过 Azure Databricks 计算资源连接到指定的目录和架构。 有关连接示例，请参阅以下部分和 GitHub 中的 sqlalchemy.py 文件。

示例

请参阅 GitHub 中的 sqlalchemy.py 文件。

DBAPI 参考

其他资源