使用 dbx 将本地文件与远程工作区实时同步

可以使用 Databricks Labs 的 dbx 将本地开发计算机上的文件更改与 Azure Databricks 工作区中的相应文件实时同步。 这些工作区文件可以在 DBFS 或 Databricks Git 文件夹中。

与 dbx 的实时文件同步（也称为 dbx sync）在快速代码开发场景中很有用。 例如，可以使用本地集成开发环境 (IDE) 来实现生产力功能，例如语法突出显示、智能代码完成、代码 Lint 分析，以及测试和调试等。 然后，就可以立即转到工作区并运行更新后的代码。

可以单独使用 dbx sync、也可以与自动化作业或 IDE 一起使用。

dbx sync 开发工作流

dbx sync 有两个开发工作流，一个使用 DBFS，另一个使用 Databricks Git 文件夹。

使用 dbx sync 和 DBFS 的典型开发工作流为：

1. 确定包含要同步到 DBFS 的文件的本地目录。
2. 确定希望本地目录与之同步的 DBFS 中的路径（或让 dbx sync 创建默认 DBFS 路径）。
3. 运行 dbx sync dbfs 将本地目录同步到 DBFS 路径。 dbx sync 开始监视本地目录中是否有任何文件更改。
4. 根据需要对本地目录中的文件进行更改。 dbx sync 实时将这些更改应用于 DBFS 路径中的相应文件。

使用 dbx sync 和 Databricks Git 文件夹的典型开发工作流为：

1. 如果还没有可用的存储库，请使用 Databricks Git 文件夹支持的 Git 提供程序创建一个存储库。

2. 将存储库克隆到 Azure Databricks 工作区。

3. 将存储库克隆到本地开发计算机。

4. 运行 dbx sync repo 以将本地克隆存储库与工作区克隆存储库关联。 dbx sync 开始监视本地目录中是否有任何文件更改。

5. 根据需要对本地克隆存储库中的文件进行更改。 dbx sync 实时将这些更改应用于 Databricks Git 文件夹中的相应文件。

6. 定期将更新后的文件从工作区中的克隆存储库推送到 Git 提供程序，这样存储库就可以与 Git 提供程序保持最新。

要求

如果要将 dbx sync 与 Databricks Git 文件夹结合使用，Azure Databricks 工作区必须满足以下要求：

• 建议使用 Git 提供程序克隆存储库，但这不是必需的。

在本地开发计算机上，必须安装以下组件：

• Python 3.8 或更高版本。 要检查是否安装了 Python，以及检查已安装的 Python 版本，请在终端或 PowerShell 中运行 python --version。

  python --version
  

  注意

  python 的某些安装可能要求使用 python3 而不是 python。 如果是这样，请将本文中的 python 替换为 python3。

• pip。 要检查是否安装了 pip，并检查已安装的 pip 版本，请运行 pip --version 或 python -m pip --version。

  pip --version
  
  # Or...
  
  python -m pip --version
  

  注意

  pip 的某些安装可能要求使用 pip3 而不是 pip。 如果是这样，请将本文中的 pip 替换为 pip3。

• dbx 版本 0.8.0 或更高版本。 要检查是否安装了 dbx，并检查已安装的 dbx 版本，请运行 dbx --version。 若要从 Python 包索引 (PyPI) 安装 dbx，请运行 pip install dbx 或 python -m pip install dbx。 （dbx 包括 dbx sync。）

  # Check whether dbx is installed, and check its version.
  dbx --version
  
  # Install dbx.
  pip install dbx
  
  # Or...
  python -m pip install dbx
  

  注意

  有关 dbx 的详细信息，请参阅 Databricks Labs 的 dbx 和 dbx 文档。

• 设置了身份验证的 Databricks CLI 0.18 或更低版本。 安装 dbx 时，系统会自动安装旧版 Databricks CLI（Databricks CLI 版本 0.17）。 可以在本地开发计算机上的以下一个或两个位置设置此身份验证：

  • 在 DATABRICKS_HOST 和 DATABRICKS_TOKEN 环境变量中（从旧版 Databricks CLI 版本 0.8.0 开始）。
  • 在 .databrickscfg 文件的 Azure Databricks 配置文件中。

  dbx 分别在这两个位置查找身份验证凭据。 dbx 仅使用它找到的第一组匹配的凭据。

  注意

  如果使用 .databrickscfg 文件，dbx sync 默认将在此文件中查找名为 DEFAULT 的配置文件。 要指定其他配置文件，请在运行 dbx sync 命令时使用 --profile 选项，本文稍后将对此进行介绍。

  dbx 不支持使用 .netrc 文件进行身份验证。

• 如果想将 dbx sync 与 Databricks Git 文件夹结合使用，建议使用 Git 提供程序对存储库进行本地克隆（但这不是必需的）。 要执行本地克隆，请参阅 Git 提供程序的文档。

将 DBFS 与 dbx sync 结合使用

1. 从本地开发计算机上的终端或 PowerShell，更改为包含要同步到 Azure Databricks 工作区中 DBFS 的文件的目录。

2. 运行 dbx sync 命令将本地目录同步到工作区中的 DBFS，如下所示。 （不要忘记末尾的点 (.)，它表示当前目录。）

   dbx sync dbfs --source .
   

   提示

   要指定其他源目录，请将点 (.) 替换为不同的路径。

   备注

   如果出现错误 Error: No such command 'sync'，则 dbx 安装可能已过期。 要解决此问题，请运行 pip install --upgrade dbx==<version> 或 python -m pip install --upgrade dbx==version，其中 <version> 是 dbx 的最新版本。 此版本号可在 dbx 的 PyPI 网页上找到。

   pip install --upgrade dbx==<version>
   
   # Or...
   python -m pip install --upgrade dbx==version
   

3. dbx sync 开始将当前本地目录中的文件与工作区中以下 DBFS 路径中的文件同步。 dbx sync 通过打印 Target base path 后跟 DBFS 路径来确认这一点，例如：

   /tmp/users/<your-Databricks-username>/<local-directory-name>
   

   提示

   要指定其他用户名或 DBFS 路径，请在运行 dbx sync 时分别指定 --user 和 --dest 选项。

4. 根据需要对本地文件进行更改。

   重要

   必须让终端或 PowerShell 保持打开状态，才能使 dbx sync 继续同步。 如果关闭终端或 PowerShell，dbx sync 将停止监视文件更改并停止同步。 要继续文件更改同步，请从头开始重复此过程。

5. 根据需要，在工作区中验证在 DBFS 中的上述路径中的文件更改。

将 Databricks Git 文件夹与 dbx sync 配合使用

1. 从本地开发计算机上的终端或 PowerShell，更改为包含使用 Git 提供程序的存储库克隆的根目录。

2. 在 Azure Databricks 工作区中，确定要将本地克隆存储库同步到的 Databricks Git 文件夹的名称。 可以通过单击工作区边栏中的“Git 文件夹”来查找此存储库名称。

3. 在本地开发计算机上，如下所示运行 dbx sync 命令将本地克隆存储库同步到工作区中的 Databricks Git 文件夹，并将 <your-repo-name> 替换为 Databricks Git 文件夹中的存储库名称。 （不要忘记末尾的点 (.)，它表示当前目录。）

   dbx sync repo -d <your-repo-name> --source .
   

   提示

   要指定其他源目录，请将点 (.) 替换为不同的路径。

   备注

   如果出现错误 Error: No such command 'sync'，则 dbx 安装可能已过期。 要解决此问题，请运行 pip install --upgrade dbx==<version> 或 python -m pip install --upgrade dbx==version，其中 <version> 是 dbx 的最新版本。 此版本号可在 dbx 的 PyPI 网页上找到。

   pip install --upgrade dbx==<version>
   
   # Or...
   python -m pip install --upgrade dbx==version
   

4. dbx sync 开始将本地克隆存储库中的文件与工作区中 Databricks Git 文件夹中的文件同步。 dbx sync 通过打印 Target base path 后跟 Databricks Git 文件夹路径来确认这一点，例如：

   /Repos/<your-Databricks-username>/<your-repo-name>
   

   提示

   要指定其他用户名或存储库名称，请在运行 dbx sync 时分别指定 --user 和 --dest-repo 选项。

5. 根据需要对本地文件进行更改。

   重要

   必须让终端或 PowerShell 保持打开状态，才能使 dbx sync 继续同步。 如果关闭终端或 PowerShell，dbx sync 将停止监视文件更改并停止同步。 要继续文件更改同步，请从头开始重复此过程。

6. 根据需要，在工作区中验证 Databricks Git 文件夹中的文件更改。

其他资源

• dbx 文档
• dbx 同步文档
• GitHub 上的 databrickslabs/dbx 存储库
• dbx 限制