通过

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

  • 项目

重要

本文档已过时，将来可能不会更新。

Databricks 建议使用 Databricks CLI 0.205 或更高版本而不是 dbx sync，前者包含类似于 dbx sync 的功能（通过 databricks sync 命令）。

Visual Studio Code 的 Databricks 扩展还包含与集成到 Visual Studio Code IDE 中的 dbx sync 类似的功能。 请注意，dbx sync 可以将文件更改从本地开发计算机同步到 Azure Databricks 工作区中的 DBFS、工作区位置和 Databricks Git 文件夹。 Visual Studio Code 的 Databricks 扩展仅支持将文件更改同步到工作区用户 (/Users) 文件和 Databricks Git 文件夹 (/Repos)。

注意

本文介绍 Databricks Labs 的 dbx，它按原样提供，并且 Databricks 不会通过客户技术支持渠道为它提供支持。 如需解答问题和提出功能请求，可以通过 GitHub 上 databrickslabs/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 不建议在 Azure Databricks 工作区中对 dbx sync 监视的文件进行更改。 如果必须进行此类由工作区发起的文件更改，则还必须执行以下操作：

  • 对于 DBFS 中的文件更改，请手动对本地文件进行相应的更改。
  • 对于 Databricks Git 文件夹中的文件更改，请将文件更改从工作区推送到 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 文件夹中的文件更改。

其他资源