将 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 仓库的以下信息：

  群集

  • 群集的服务器主机名。 从群集的“高级选项”>“JDBC/ODBC”选项卡的“服务器主机名”值中可以获取此主机名。
  • 群集的 HTTP 路径。 从群集的“高级选项”>“JDBC/ODBC”选项卡的“HTTP 路径”值中可以获取此路径。

  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. 将显示的令牌复制到安全位置，然后单击“完成”。

要对 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 参考

• 请参阅 GitHub 中的 README.sqlalchemy.md 文件。
• 另请参阅 GitHub 中的 sqlalchemy 源代码目录。

其他资源

• SQLAlchemy 统一教程