Databricks CLI 迁移

本文介绍如何从 Databricks CLI 0.18 或更低版本迁移到 Databricks CLI 0.205 或更高版本。 Databricks CLI 0.205 及更高版本为公共预览版

为简洁起见,本文将 Databricks CLI 0.18 及更低版本称为“旧”CLI,将 Databricks CLI 0.205 及更高版本称为“新”CLI。

有关旧和新 CLI 的详细信息,请参阅:

卸载旧 CLI

如果你已安装旧 CLI 并且想要卸载它,请使用 pip(或 pip3,具体取决于 Python 的版本)来运行 uninstall 命令,如下所示:

pip uninstall databricks-cli

安装新 CLI

若要了解如何安装新 CLI,请参阅安装或更新 Databricks CLI

验证你的 CLI 安装

如果不确定是否正在使用新 CLI,请按照本部分中的说明进行验证并根据需要进行调整。 在按照这些说明操作之前,请确保退出任何 Python 虚拟环境、conda 环境或类似环境。

若要检查 CLI 的默认安装版本,请运行以下命令:

databricks -v

如果版本号与预期不符,请执行下列操作之一:

  • 如果你只想使用一个版本的 CLI:卸载所有不想再使用的、以前版本的 CLI。 可能需要更新操作系统的 PATH,以便列出你要使用的 CLI 的剩余版本的路径。
  • 如果要继续使用多个 CLI 版本:在每次调用 CLI 时,在开头预置要使用的 CLI 版本的完整路径。
  • 如果要继续使用多个 CLI 版本,但不想每次都要预置最常用的 CLI 版本的完整路径:请确保该版本的完整路径在操作系统的 PATH 中列在首位。 请注意,你仍须预置未在操作系统的 PATH 中列在首位的 CLI 版本的完整路径。

若要更新操作系统的 PATH,请执行以下操作:

MacOS 或 Linux

  1. 通过运行以下命令之一,列出安装 databricks 的路径:

    which -a databricks
    
    # Or:
    where databricks
    
  2. 获取要使用的安装路径,而不必在每次调用 CLI 前添加完整路径。 如果不确定这是哪个路径,请运行每个位置的完整路径,后跟 -v,例如:

    /usr/local/bin/databricks -v
    
  3. 若要将首先使用的安装路径放入 PATH 中,请运行以下命令,将 /usr/local/bin 替换为要使用的路径。 请勿将 databricks 添加到此路径的末尾。 例如:

    export PATH="/usr/local/bin:$PATH"
    
  4. 若要验证当前终端会话是否已正确设置 PATH,请运行 databricks,然后运行 -v 并检查版本号:

    databricks -v
    
  5. 若要在每次重启终端时以这种方式设置 PATH,请将步骤 3 中的命令添加到 shell 初始化文件。 例如,对于 Zshell,此文件通常位于 ~/.zshrc。 对于 Bash,此文件通常位于 ~/.bashrc。 对于其他 shell,请参阅 shell 提供程序的文档。

  6. 更新 shell 初始化文件后,必须重启终端才能应用更新的 PATH 值。

Windows

  1. 右键单击要使用的 databricks 安装,而不必在每次调用 CLI 前添加完整路径。

  2. 单击“打开文件位置”。

  3. 记下到 databricks 的路径,例如 C:\Windows

  4. 在“开始”菜单上,搜索“环境变量”。

  5. 单击“编辑帐户的环境变量”。

  6. 在“用户变量”部分选择“路径”变量。

  7. 单击 “编辑”

  8. 单击 “新建”

  9. 输入要添加的路径,不带 databricks.exe(如 C:\Windows)。

  10. 使用“上移”按钮移动刚添加到列表开头的路径。

  11. 单击 “确定”

  12. 若要验证 PATH 是否已正确设置,请打开一个新的命令提示符,运行 databricks,然后运行 -v 并检查版本号:

    databricks -v
    

使用其他身份验证类型

旧 CLI 和新 CLI 都支持 Azure Databricks 个人访问令牌身份验证。 但是,Databricks 建议尽可能使用其他 Azure Databricks 身份验证类型,而只有新 CLI 支持它们。

如果必须使用 Azure Databricks 个人访问令牌身份验证,Databricks 建议将其与服务主体关联,而不是 Azure Databricks 帐户或工作区用户。 请参阅管理服务主体

除了 Azure Databricks 个人访问令牌之外,新 CLI 还支持 Microsoft Entra ID 令牌。 这些其他令牌更安全,因为它们通常会在一小时内过期,而 Azure Databricks 个人访问令牌的有效期可能是一天到无限期。 如果令牌意外地签入到其他人可以访问的版本控制系统中,这一点就尤其重要了。 此外,新 CLI 可以在这些其他令牌过期时自动刷新它们,而刷新 Azure Databricks 个人访问令牌要么需要手动,要么难以自动化。

有关详细信息,请参阅 Databricks CLI 身份验证

命令组和命令比较

下表列出了旧 CLI 命令组以及对应的新 CLI 命令组。 如果 CLI 之间存在显著差异,额外的表还列出了旧 CLI 命令或选项以及对应的新 CLI 命令或选项。

命令组

旧命令组 新增了命令组
cluster-policies cluster-policies。 所有命令名称都相同。
clusters clusters。 所有命令名称都相同。
configure configure。 请参阅配置选项
fs fs。 请参阅 fs 命令
groups groups。 请参阅组命令
instance-pools instance-pools。 所有命令名称都相同。
jobs jobs。 所有命令名称都相同。
libraries libraries。 所有命令名称都相同,list 除外。 list 命令不再可用,请改用 all-cluster-statusescluster-status 命令。
pipelines pipelines。 请参阅管道命令
repos repos。 所有命令名称都相同。
runs jobs。 请参阅运行命令
secrets secrets。 请参阅机密命令
stack 在新 CLI 中不可用。 Databricks 建议改用 Databricks Terraform 提供程序
tokens tokens。 请参阅令牌命令
unity-catalog 各种。 请参阅 unity-catalog 命令组
workspace workspace。 请参阅工作区命令

configure 选项

旧选项 新选项
-o 旧 CLI 使用 -o 进行 OAuth 身份验证。 新 CLI 将 -o 改造为指定 CLI 输出是文本格式还是 JSON 格式。 不适用于 Azure Databricks。
--oauth 不适用于 Azure Databricks。
-s--scope 不适用于 Azure Databricks。
-t--token -t--token(相同)
-f--token-file 在新 CLI 中不可用。
--host --host(相同)
--aad-token 出现提示时,使用 --host 并指定 Microsoft Entra ID 令牌,而不是 Azure Databricks 个人访问令牌。
--insecure 在新 CLI 中不可用。
--jobs-api-version 在新 CLI 中不可用。 新 CLI 仅使用作业 API 2.1。 若要调用旧作业 API 2.0,请使用旧 CLI 并参阅作业 CLI(旧)
--debug 若要在新 CLI 中进行调试和日志记录,请参阅调试模式
--profile --profile(相同)或 -p
-h--help -h--help(相同)

fs 命令

旧 CLI 中的所有 fs 命令在新 CLI 中都相同,但 fs mv 除外,它在新 CLI 中不可用。

旧命令 新命令
fs cat fs cat(相同)
fs cp fs cp(相同)
fs ls fs ls(相同)
fs mkdirs fs mkdir
fs mv 在新 CLI 中不可用。
fs rm fs rm(相同)

groups 命令

旧命令 新命令
groups add-member groups patch
groups create groups create(相同)
groups delete groups delete(相同)
groups list groups list(相同)
groups list-members groups list
groups list-parents groups list
groups remove-member groups patch

pipelines 命令

旧命令 新命令
pipelines create pipelines create(相同)
pipelines delete pipelines delete(相同)
pipelines deploy pipelines create
pipelines edit pipelines update
pipelines get pipelines get(相同)
pipelines list pipelines list-pipeline-eventspipelines list-pipelinespipelines list-updates
pipelines reset pipelines reset(相同)
pipelines start pipelines start update
pipelines stop pipelines stop(相同)
pipelines update pipelines update(相同)

runs 命令

旧命令 新命令
runs cancel jobs cancel-run
runs get jobs get-run
runs get-output jobs get-run-output
runs list jobs list-runs
runs submit jobs submit

secrets 命令

旧命令 新命令
secrets create-scope secrets create-scope(相同)
secrets delete secrets delete-secret
secrets delete-acl secrets delete-acl(相同)
secrets delete-scope secrets delete-scope(相同)
secrets get-acl secrets get-acl(相同)
secrets list secrets list-secrets
secrets list-acls secrets list-acls(相同)
secrets list-scopes secrets list-scopes(相同)
secrets put secrets put-secret
secrets put-acl secrets put-acl(相同)
secrets write secrets put-secret
secrets write-acl secrets put-acl

tokens 命令

旧命令 新命令
tokens create tokens create(相同)
tokens list tokens list(相同)
tokens revoke tokens delete

unity-catalog 命令组

旧 CLI 中的 unity-catalog <command> 变成了新 CLI 中的 <command>

旧命令组 新命令组
unity-catalog catalogs catalogs(相同,但删除了 unity-catalog
unity-catalog external-locations external-locations(相同,但删除了 unity-catalog
unity-catalog lineage 在新 CLI 中不可用。 请参阅使用数据世系 REST API 检索世系
unity-catalog metastores metastores(相同,但删除了 unity-catalog
unity-catalog permissions grants
unity-catalog providers providers(相同,但删除了 unity-catalog
unity-catalog recipients recipients(相同,但删除了 unity-catalog
unity-catalog schemas schemas(相同,但删除了 unity-catalog
unity-catalog shares shares(相同,但删除了 unity-catalog
unity-catalog storage-credentials storage-credentials(相同,但删除了 unity-catalog
unity-catalog tables tables(相同,但删除了 unity-catalog

workspace 命令

旧命令 新命令
workspace delete workspace delete(相同)
workspace export workspace export(相同)
workspace export-dir workspace export
workspace import workspace import(相同)
workspace import-dir workspace import
workspace list workspace list(相同)
workspace ls workspace list
workspace mkdirs workspace mkdirs(相同)
workspace rm workspace delete

默认参数和位置参数

大多数新 CLI 命令至少有一个默认参数没有附带的选项。 某些新 CLI 命令具有两个或多个位置参数,这些参数必须按特定顺序指定,并且没有附带的选项。 这与旧 CLI 不同,旧 CLI 中的大多数命令都需要为所有参数指定选项。 例如,新 CLI 的 clusters get 命令接受群集 ID 作为默认参数。 但是,旧 CLI 的 clusers get 命令要求指定 --cluster-id 选项和群集 ID。 例如:

对于旧 CLI:

# This works with the legacy CLI.
databricks clusters get --cluster-id 1234-567890-a1b23c4d

# This does **not** work with the legacy CLI - "Error:
# Missing None. One of ['cluster-id', 'cluster-name'] must be provided."
databricks clusters get 1234-567890-a1b23c4d

对于新 CLI:

# This works with the new CLI.
databricks clusters get 1234-567890-a1b23c4d

# This does **not** work with the new CLI - "Error: unknown flag: --cluster-id"
databricks clusters get --cluster-id 1234-567890-a1b23c4d

再举一个例子,新 CLI 的 grants get 命令接受两个默认参数:安全对象类型,后跟安全对象的全名。 但是,旧 CLI 的 unity-catalog permissions get 命令要求指定 --<securable-type> 选项和安全对象的全名。 例如:

对于旧 CLI:

databricks unity-catalog permissions get --schema main.default

对于新 CLI:

# This works with the new CLI.
databricks grants get schema main.default

# This does **not** work with the new CLI - "Error: unknown flag: --schema"
databricks grants get --schema main.default

调试模式

旧 CLI 提供了一个 --debug 选项,用于显示错误时的完整堆栈跟踪。 对于新 CLI,--debug 选项不会被识别。 作为替代,使用下列选项:

  • 使用 --log-file <path> 将日志信息写入 <path> 中指定的文件。 如果未提供此选项,则日志信息将输出到 stderr。 如果指定 --log-file 但不指定 --log-level,则不会将任何日志信息写入文件。
  • 使用 --log-format <type> 指定所记录信息的格式。 <type> 可以是 text(默认值,如果未指定)或 json
  • 使用 --log-level <format> 指定记录的信息级别。 允许的值包括 disabled(默认值,如果未指定)、tracedebuginfowarnerror

对于旧 CLI,以下示例显示了错误时的完整堆栈跟踪:

databricks fs ls / --debug

# Output:
#
# HTTP debugging enabled
# NoneType: None
# Error: The path / must start with "dbfs:/"

对于新 CLI,以下示例将完整堆栈跟踪记录到当前工作目录中名为 new-cli-errors.log 的文件。 堆栈跟踪以 JSON 格式写入文件:

databricks fs ls / --log-file new-cli-errors.log --log-format json --log-level trace

# Output:
#
# Error: expected dbfs path (with the dbfs:/ prefix): /
#
# (The full stack trace is also written to the new-cli-errors.log file.)

常见问题

本部分列出了有关从旧 CLI 迁移到新 CLI 的常见问题。

旧 CLI 发生了什么?

旧 CLI 依然可用,但无法收到任何非关键更新。 旧 CLI 文档说明了这一情况。 Databricks 建议用户尽快迁移到新 CLI。

旧 CLI 一直处于试验状态,免责声明表示 Databricks 计划不为旧 CLI 提供新功能,并且 Databricks 支持渠道也不为旧 CLI 提供支持。

何时弃用旧 CLI?

旧 CLI 一直处于试验状态,免责声明表示 Databricks 计划不为旧 CLI 提供新功能,并且 Databricks 支持渠道也不为旧 CLI 提供支持。

Databricks 尚未确定弃用旧 CLI 的日期或时间线。 但是,Databricks 建议用户尽快迁移到新 CLI。

新 CLI 何时正式发布 (GA)?

尚未确定新 CLI 的正式发布日期或时间线。 这将取决于 Databricks 在公共预览版期间收到的用户反馈。

旧 CLI 和新 CLI 之间的主要区别是什么?

  • 旧 CLI 作为 Python 包发布。 新 CLI 作为独立可执行文件发布,无需安装任何运行时依赖项。
  • 新 CLI 已完全涵盖 Databricks REST API, 而旧 CLI 没有。
  • 新 CLI 以公共预览版的形式提供。 旧 CLI 仍处于试验状态。

新 CLI 是否具有与旧 CLI 完全相同的功能?

新 CLI 几乎涵盖了旧 CLI 中的所有命令。 但是,值得注意的是,新 CLI 中缺少旧 CLI 中的 stacks 命令组。 此外,一些旧 CLI 命令组(如 unity-catalogruns)已在新 CLI 中重构为新的命令组。 有关迁移指导,请参阅本文前面提供的信息。

如何实现从旧 CLI 迁移到新 CLI?

有关迁移指导,请参阅本文前面提供的信息。 请注意,新 CLI 不是直接替代旧 CLI,需要一些设置才能从旧 CLI 迁移到新 CLI。

是否可以在同一台计算机上安装旧 CLI 和新 CLI?

是的。 旧 CLI 和新 CLI 可以安装在同一台计算机上,但它们必须位于不同的目录中。 由于可执行文件均命名为 databricks,因此必须通过配置计算机的 PATH 来控制默认运行的可执行文件。 如果要运行新 CLI,但意外地改为运行旧 CLI,默认情况下,旧 CLI 将使用相同的参数运行新 CLI,并显示以下警告消息:

Databricks CLI <new-version-number> found at <new-path>
Your current PATH prefers running CLI <old-version-number> at <old-path>

Because both are installed and available in PATH,
I assume you are trying to run the newer version.

If you want to disable this behavior you can set DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION=1.

Executing CLI <new-version-number>...
-------------------------------------
Databricks CLI <new-version-number>

如前面的警告消息所示,可以将 DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION 环境变量设置为 1 以禁用此行为并改为运行旧 CLI。

获取帮助

若要获取有关从旧 CLI 迁移到新 CLI 的帮助,请参阅以下资源: