适用于 Visual Studio Code 的 Databricks Driver for SQLTools

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

准备阶段

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

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

工作区要求

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

• 该工作区必须至少包含一个 Databricks 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. 在“在市场中搜索扩展”框中，输入 SQLTools。

3. 单击 Matheus Teixeira 中的 SQLTools 条目。

   注意

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

4. 单击“安装”。

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

1. 在 Visual Studio Code 的主菜单中，单击“视图”>“扩展”。
2. 在“在市场中搜索扩展”框中，输入 Databricks Driver for SQLTools。
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 身份验证

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

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

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

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

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

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

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

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

Azure CLI 身份验证

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

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

连接到架构

1. 在 Visual Studio Code 的边栏中，单击 SQLTools 图标。
2. 在 SQLTools 视图中，如果这是你第一次使用 SQLTools 扩展，请在“连接”窗格中单击“添加新连接”。 否则，请单击窗格标题栏中的“添加新连接”图标。
3. 在“SQLTools 设置”选项卡上，对于“选择数据库驱动程序”步骤，单击 Databricks 图标。
4. 对于“连接设置”步骤，输入有关仓库、目录和架构的以下信息：

   1. 对于“连接名称”，请为此连接输入一个唯一名称。

   2. （可选）对于“连接组”，请输入现有连接组的名称以将新连接添加到该组。 或者，输入唯一的名称以使用新连接创建新连接组。 使用连接组可以更轻松地在扩展中查找连接。

   3. 对于“连接方式”，请选择以下其中一项：

      • 若要使用 Azure Databricks 个人访问令牌进行身份验证，请选择“主机名和令牌”。
      • 对于 Databricks Driver for SQLTools 版本 0.4.2 及更高版本，若要使用 OAuth U2M 或 M2M 或 Azure CLI 身份验证，请选择“VS Code 扩展（beta 版本）”。

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

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

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

   7. 对于“目录”，请输入目录的名称。

      注意

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

   8. 对于“架构”，请输入架构的名称。

   9. （可选）对于“显示记录的默认限制”，保留默认值 50，以便为每个查询最多仅显示前 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. 通过检查 日志启用日志记录：启用 设置或将 databricks.logs.enabled 设置为 true，如 Visual Studio Code Databricks 扩展的 设置中所述 启用日志记录后，请务必重启 Visual Studio Code。
3. 尝试重现问题。
4. 在“命令面板”（在主菜单中选择“查看”>“命令面板”）中，运行“Databricks: 打开完整日志”命令。
5. 将显示的 Databricks Logs.log、databricks-cli-logs.json 和 sdk-and-extension-logs.json 文件发送给 Databricks 支持人员。
6. 另外，请复制问题上下文中的“终端”（“查看”>“终端”）的内容，并将此内容发送给 Databricks 支持人员。

如果已选中“日志: 已启用”或者 databricks.logs.enabled 设置为 true，则“输出”视图（“视图”>“输出”>“Databricks 日志”）将显示截断的信息。 若要显示详细信息，请更改以下设置，如 Visual Studio Code 的 Databricks 扩展设置中所述：

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

其他资源

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