Visual Studio Code 版 Databricks Driver for SQLTools

重要

此功能目前以公共预览版提供。

使用 Databricks Driver for SQLTools，可以使用适用于 Visual Studio Code 的 SQLTools 扩展浏览 SQL 对象并在远程 Azure Databricks 工作区中运行 SQL 查询。

Requirements

在你可以使用 Databricks Driver for SQLTools 之前，你的 Azure Databricks 工作区和本地开发计算机必须满足以下要求。

• 工作区要求
• 本地开发计算机要求
• 身份验证
  • Azure Databricks 个人访问令牌身份验证
  • Azure Databricks OAuth 计算机到计算机 (M2M) 身份验证
  • Azure Databricks OAuth 用户到机器 (U2M) 身份验证
  • Azure CLI 身份验证

工作区要求

必须至少有一个可用的 Azure Databricks 工作区，并且该工作区必须满足以下要求：

• 该工作区必须至少包含一个 Databricks SQL SQL 仓库。

  注意

  Databricks Driver for SQLTools 不支持 Azure Databricks 群集。

• 对于为 Unity Catalog 启用的工作区，工作区必须至少包含一个目录，并且该目录中至少有一个架构（以前称为数据库）。

  • 浏览数据库对象。
  • 创建目录。
  • 创建架构。

• 对于未为 Unity Catalog 启用的工作区，工作区必须至少包含一个架构（以前称为数据库）。

  • 浏览数据库对象。
  • 创建架构。

本地开发计算机要求

本地开发计算机上必须具备以下内容：

• Visual Studio Code 1.70 或更高版本。 若要查看已安装的版本，请在 Linux 或 macOS 上的主菜单中单击代码 > 关于 Visual Studio Code，或者在 Windows 上单击帮助 > 关于。 若要下载、安装和配置 Visual Studio Code，请参阅设置 Visual Studio Code。
• 适用于 Visual Studio Code 的 SQLTools 扩展。
• 适用于 Visual Studio Code 的 Databricks Driver for SQLTools 扩展。

若要安装 SQLTools 扩展，请转到 SQLTools，然后单击“安装”，或者：

1. 在 Visual Studio Code 的主菜单中，单击视图 > 扩展。

2. 在在 Marketplace 中搜索扩展框中，输入 。

3. 单击来自 Matheus Teixeira 的 SQLTools 条目。

   注意

   可能列出多个 SQLTools 条目。 请务必单击来自Matheus Teixeira的条目。

4. 单击“安装”。

若要安装 Databricks Driver for SQLTools 扩展，请转到 Databricks Driver for SQLTools，然后单击“安装”，或者：

1. 在 Visual Studio Code 的主菜单上，单击 “视图” > >“扩展”。
2. 在 Marketplace 中搜索扩展 框中，输入 。
3. 单击 Databricks Driver for SQLTools 条目。
4. 单击“安装”。

身份验证

必须为 Databricks Driver for SQLTools 设置身份验证，具体如下所示。

Databricks Driver for SQLTools 支持以下 Azure Databricks 身份验证类型：

• Azure Databricks 个人访问令牌身份验证
• Azure Databricks OAuth 计算机到计算机 (M2M) 身份验证
• Azure Databricks OAuth 用户到计算机 (U2M) 身份验证
• Azure CLI 身份验证

注意

Databricks Driver for SQLTools 不支持 Microsoft Entra ID 令牌。

Azure Databricks 个人访问令牌身份验证

若要将 Databricks Driver for SQLTools 与 Azure Databricks 个人访问令牌身份验证搭配使用，必须拥有 Azure Databricks 个人访问令牌。 若要创建个人访问令牌，请按照 为工作区用户创建个人访问令牌中的步骤作。

Azure Databricks OAuth 机器到机器 (M2M) 身份验证

可以使用 Azure Databricks OAuth 计算机到计算机 (M2M) 身份验证向 Databricks Driver for SQLTools 进行身份验证，如下所示：

注意

Databricks Driver for SQLTools 版本 0.4.2 及更高版本中提供了 Azure Databricks OAuth M2M 身份验证。

1. 完成 OAuth M2M 身份验证的配置步骤。 请参阅 OAuth 机器到机器 (M2M) 身份验证。
2. 使用 OAuth M2M 身份验证配置设置创建 Azure Databricks 配置文件。 请参阅 OAuth 计算机到计算机 (M2M) 身份验证的“配置”部分。
3. 在本地开发计算机上安装并打开 Visual Studio Code 的 Databricks 扩展。
4. 在 Databricks IDE 扩展中，点击配置面板中的配置按钮。 如果未显示“配置”按钮，请单击齿轮（“配置工作区”）图标。
5. 在“Command Palette”中，对于“Databricks Host”，请输入 Azure Databricks 每个工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net，然后按 Enter。
6. 选择与在步骤 2 中创建的那一项匹配的配置文件项。
7. 完成 Web 浏览器中的屏幕说明，以完成向 Azure Databricks 帐户的身份验证。

Azure Databricks OAuth 用户到机器 (U2M) 身份验证

可以使用 Azure Databricks OAuth 用户到计算机 (U2M) 身份验证向 Databricks Driver for SQLTools 进行身份验证，如下所示：

注意

Databricks Driver for SQLTools 版本 0.4.2 及更高版本中提供了 Azure Databricks OAuth U2M 身份验证。

1. 在本地开发计算机上安装并打开 Visual Studio Code 的 Databricks 扩展。
2. 在 Databricks IDE 扩展中，点击 配置 面板中的 配置 按钮。 如果未显示“配置”按钮，请单击齿轮（“配置工作区”）图标。
3. 在命令面板中，对于 Databricks 主机，请输入 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。 然后，按 Enter。
4. 选择“OAuth（用户到计算机）”。
5. 完成 Web 浏览器中的屏幕说明，以完成向 Azure Databricks 帐户的身份验证。 如果出现提示，请允许 all-apis 访问。

Azure CLI 身份验证

可以使用 Azure CLI 对 Databricks Driver for SQLTools 进行身份验证，具体如下所示：

注意

使用 Azure CLI 进行身份验证的功能目前处于试验状态。 此功能在 0.4.2 及更高版本的 Databricks Driver for SQLTools 中提供。

1. 在本地开发计算机上安装 Azure CLI（如果尚未这样做）。
2. 在本地开发计算机上安装并打开 Visual Studio Code 的 Databricks 扩展。
3. 在 Databricks IDE 扩展中，点击配置按钮（位于配置窗格中）。 如果未显示“配置”按钮，请单击齿轮（“配置工作区”）图标。
4. 在命令面板中，对于 Databricks 主机，请输入 Azure Databricks 每工作区 URL，例如 https://adb-1234567890123456.7.azuredatabricks.net。 然后，按 Enter。
5. 选择“Azure CLI”。
6. 按照屏幕上的提示使用 Azure CLI 完成身份验证。

连接到架构

1. 在 Visual Studio Code 的边栏中，单击 SQLTools 图标。

2. 在 SQLTools 视图中，如果这是你第一次使用 SQLTools 扩展，请在“连接”窗格中单击“添加新连接”。 否则，请单击窗格标题栏中的“添加新连接”图标。

3. 在“SQLTools 设置”选项卡上，对于“选择数据库驱动程序”步骤，单击 Databricks 图标。

4. 对于 “连接设置” 步骤，请输入有关仓库、目录和架构的以下信息：

   1. 对于连接名称，请为此连接输入一个唯一名称。
   2. （可选）对于“连接组”，请输入现有连接组的名称以将新连接添加到该组。 或者，输入唯一的名称以使用新连接创建新连接组。 使用连接组可以更轻松地在扩展中查找连接。
   1. 在 Connect using 下，请选择以下选项之一：
      • 若要使用 Azure Databricks 个人访问令牌进行身份验证，请选择“主机名和令牌”。
      • 对于 Databricks Driver for SQLTools 版本 0.4.2 及更高版本，若要使用 OAuth U2M 或 M2M 或 Azure CLI 身份验证，请选择 VS Code 扩展（beta 版本）。

   1. 如果为“连接方式”选择了“主机名和令牌”，那么，对于“主机”，请输入仓库的“服务器主机名”设置。 若要获取仓库的 Server hostname 设置，请参阅 获取 Azure Databricks 计算资源的连接详细信息。

   2. 对于“路径”，请输入仓库或群集的“HTTP 路径”设置。 若要获取仓库的HTTP 路径设置，请参阅获取 Azure Databricks 计算资源的连接详细信息。

   3. 如果为连接方式选择了主机名和令牌，请在令牌中输入你的 Azure Databricks 个人访问令牌值。

   4. 对于Catalog，请输入您的 Catalog 的名称。

      注意

      对于未为 Unity Catalog 启用的工作区，可以将目录留空以使用 hive_metastore 的默认值。

   5. 对于Schema，请输入您的 Schema 名称。

   6. （可选）对于显示记录默认限制，保留默认值 ，以便每个查询最多仅显示前 50 行，或输入不同的限制。

5. 单击 “测试连接”。

6. 连接测试成功后，单击“保存连接”。

更改连接的设置

此过程假定你已成功连接到至少一个仓库。

1. 如果 SQLTools 视图不可见，请在 Visual Studio Code 边栏中单击 SQLTools 图标。
2. 在“连接”窗格中，如果目标连接有对应的连接组，则展开该连接组。
3. 右键单击连接，然后单击“编辑连接”。
4. 更改目标设置。
5. 单击 “测试连接”。
6. 连接测试成功后，单击保存连接。

浏览架构的对象

1. 在连接窗格中，展开连接组（如果目标连接存在连接组）。
2. 双击或展开用于您的仓库的目标连接。
3. 展开目标数据库（架构）（如果连接存在数据库）。
4. 如果数据库（架构）存在一个或多个表或视图，请展开“表”或“视图”。
5. 展开任何目标表或视图以查看表或视图的列。

查看表或视图的行或架构

在“连接”窗格中展开“表”或“视图”后，执行下列操作之一：

• 若要显示表或视图的行，请右键单击该表或视图，然后单击“显示表记录”或“显示视图记录”。
• 若要显示表或视图的架构，请右键单击该表或视图，然后单击描述表或描述视图。

为表生成插入查询

1. 将光标放在现有编辑器中要添加插入查询的位置。
2. 在“连接”窗格中展开“表”后，右键单击该表，然后单击“生成插入查询”。 插入查询的定义已添加到光标的插入点。

创建并运行查询

此过程假定你已成功连接到至少一个仓库。

1. 在“连接”窗格中，展开连接组（如果目标连接存在对应的连接组）。
2. 双击或展开仓库的目标连接。
3. 选择连接后，单击“连接”窗格标题栏中的“新建 SQL 文件”。 此时将显示一个新的编辑器选项卡。
4. 在新编辑器中输入 SQL 查询。
5. 若要运行 SQL 查询，请在编辑器中单击“在活动连接上运行”。 查询的结果显示在新的编辑器选项卡中。

运行现有查询

此过程假定你已成功连接到至少一个仓库。

1. 在“连接”窗格中，展开连接组（如果存在目标连接对应的连接组）。
2. 双击或展开用于您的仓库的目标连接。
3. 选择连接后，打开文件扩展名为 .sql 的任何文件，或在以前打开的任何编辑器中选择任意一组连续的 SQL 语句。
4. 若要从打开的 .sql 文件运行 SQL 查询，并在 .sql 编辑器中显示文件的内容，请在编辑器中单击对活动连接运行。 查询的结果显示在新的编辑器选项卡中。
5. 若要在以前打开的编辑器中运行一组选定的连续 SQL 语句，请右键单击所选内容，然后单击“运行所选查询”。 查询的结果显示在新的编辑器选项卡中。

将使用情况日志发送到 Databricks

如果在使用 Databricks Driver for SQLTools 时遇到问题，可以通过执行以下操作将使用情况日志和相关信息发送到 Databricks 支持：

1. 在本地开发计算机上安装 Visual Studio Code 的 Databricks 扩展。
2. 通过勾选 Logs: Enabled 设置，或设置 databricks.logs.enabled 为 true，如 Databricks IDE 扩展设置中所述，开启日志功能。开启日志后请务必重启 Visual Studio Code。
3. 尝试重现问题。
4. 从命令面板（从主菜单中选择查看 命令面板）运行Databricks: 打开完整日志命令。
5. 将显示的 Databricks Logs.log、databricks-cli-logs.json 和 sdk-and-extension-logs.json 文件发送给 Databricks 支持人员。
6. 另外，请复制问题上下文中的 Terminal（View Terminal）内容，并将此内容发送给 Databricks 支持人员。

如果已选中日志: 已启用或者 databricks.logs.enabled 设置为 true，则输出视图（视图 > 输出，Databricks 日志）将显示截断的信息。 如需展示更多信息，请更改以下设置，详见 Databricks IDE扩展的设置：

• 日志: 最大数组长度 或
• 日志：最大字段长度 或 databricks.logs.maxFieldLength
• 日志: 截断深度 或

其他资源

• SQLTools 文档
• GitHub 上的 Databricks Driver for SQLTools