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 的详细信息，请参阅：
- Databricks CLI（旧）（旧 CLI）。
- 什么是 Databricks 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
通过运行以下命令之一，列出安装
databricks的路径：which -a databricks # Or: where databricks获取要使用的安装路径，而不必在每次调用 CLI 前添加完整路径。 如果不确定这是哪个路径，请运行每个位置的完整路径，后跟
-v，例如：/usr/local/bin/databricks -v若要将首先使用的安装路径放入
PATH中，请运行以下命令，将/usr/local/bin替换为要使用的路径。 请勿将databricks添加到此路径的末尾。 例如：export PATH="/usr/local/bin:$PATH"若要验证当前终端会话是否已正确设置
PATH，请运行databricks，然后运行-v并检查版本号：databricks -v若要在每次重启终端时以这种方式设置
PATH，请将步骤 3 中的命令添加到 shell 初始化文件。 例如，对于 Zshell，此文件通常位于~/.zshrc。 对于 Bash，此文件通常位于~/.bashrc。 对于其他 shell，请参阅 shell 提供程序的文档。更新 shell 初始化文件后，必须重启终端才能应用更新的
PATH值。
Windows
右键单击要使用的
databricks安装，而不必在每次调用 CLI 前添加完整路径。单击“打开文件位置”。
记下到
databricks的路径，例如C:\Windows。在“开始”菜单上，搜索“环境变量”。
单击“编辑帐户的环境变量”。
在“用户变量”部分选择“路径”变量。
单击 “编辑” 。
单击 “新建” 。
输入要添加的路径，不带
databricks.exe（如C:\Windows）。使用“上移”按钮移动刚添加到列表开头的路径。
单击 “确定” 。
若要验证
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-statuses 或 cluster-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 Active Directory）令牌，而不是 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-events 或 pipelines list-pipelines 或 pipelines 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 中不可用。 请参阅数据世系 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（默认值，如果未指定）、trace、debug、info、warn、error。
对于旧 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-catalog 和 runs）已在新 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 的帮助，请参阅以下资源：