Migração da CLI do Databricks

Este artigo descreve como migrar da CLI do Databricks versão 0.18 ou abaixo para a CLI do Databricks versão 0.205 ou acima. As versões 0.205 e acima da CLI do Databricks estão em Public Preview.

Para resumir, este artigo refere-se às versões 0.18 e abaixo da CLI do Databricks como a CLI “herdada” e às versões 0.205 e acima da CLI do Databricks como a CLI “nova”.

Para obter mais informações sobre o legado e as novas CLIs, consulte:

Databricks CLI (herdada) para a CLI herdada.
O que é a CLI do Databricks? para a nova CLI.

Desinstale a CLI herdada

Se você tiver a CLI herdada instalada e quiser desinstalá-la, use pip (ou pip3, dependendo da sua versão do Python) para executar o comando uninstall , da seguinte maneira:

pip uninstall databricks-cli

Instale a nova CLI

Para saber como instalar a nova CLI, consulte Instalar ou atualizar a CLI do Databricks.

Verifique sua instalação CLI

Se você não tiver certeza se está usando a nova CLI, siga as instruções nesta seção para verificar e ajustar conforme necessário. Antes de seguir estas instruções, certifique-se de sair de qualquer ambiente virtual Python, ambientes conda ou ambientes semelhantes.

Para verificar a versão de sua instalação default da CLI, execute o seguinte comando:

databricks -v

Se o número da versão não for o esperado, siga um destes procedimentos:

Se você quiser usar apenas uma versão da CLI: desinstale todas as versões anteriores da CLI que você não deseja mais usar. Talvez seja necessário atualizar PATH do seu sistema operacional para que o caminho para a versão restante da CLI que você deseja usar seja listado.
Se você quiser continuar usando várias versões da CLI: anexe o caminho completo à versão da CLI que deseja usar para cada chamada à CLI.
Se você deseja continuar usando várias versões da CLI, mas não deseja continuar anexando o caminho completo à versão da CLI que usa com mais frequência: certifique-se de que o caminho completo para essa versão esteja listado primeiro em seu PATH do sistema. Observe que você ainda deve preceder o caminho completo para as versões da CLI que não estão listadas primeiro no PATH do seu sistema operacional.

Para atualizar PATH do seu sistema operacional, faça o seguinte:

Liste os caminhos em que databricks está instalado executando um dos seguintes comandos:
```
which -a databricks

# Or:
where databricks
```
Obtenha o caminho para a instalação que deseja usar sem preceder o caminho completo para cada chamada para a CLI. Se você não tiver certeza de qual caminho é esse, execute o caminho completo para cada local, seguido por -v, por exemplo:
```
/usr/local/bin/databricks -v
```
Para colocar o caminho para a instalação que deseja usar primeiro em seu PATH, execute o seguinte comando, substituindo /usr/local/bin pelo caminho que deseja usar. Não adicione databricks ao final deste caminho. Por exemplo:
```
export PATH="/usr/local/bin:$PATH"
```
Para verificar se o PATH foi definido corretamente para a sessão de terminal atual, execute databricks seguido de -v e verifique o número da versão:
```
databricks -v
```
Para que o PATH seja definido dessa maneira toda vez que você reiniciar o terminal, adicione o comando da passo 3 ao arquivo de inicialização do shell. Por exemplo, para Zshell, esse arquivo geralmente está localizado em ~/.zshrc. Para Bash, esse arquivo geralmente está localizado em ~/.bashrc. Para outros shells, consulte a documentação do provedor de shell.
Depois de atualizar o arquivo de inicialização do shell, reinicie o terminal para aplicar o valor PATH atualizado.

Clique com o botão direito do mouse na instalação de databricks que deseja usar sem preceder o caminho completo para cada chamada para a CLI.
Clique em Abrir local do arquivo.
Observe o caminho para databricks, por exemplo C:\Windows.
No menu começar , procure por variável de ambiente.
Clique em Editar variável de ambiente para sua account.
Selecione a variável Path na seção Variáveis de usuário para <username> .
Clique em Editar.
Clique em Novo.
Insira o caminho que deseja adicionar, sem databricks.exe (como C:\Windows).
Use o botão Mover para cima para mover o caminho que você acabou de adicionar ao início da lista.
Clique em OK.
Para verificar se o PATH foi definido corretamente, abra um novo prompt de comando, execução databricks seguido de -v e verifique o número da versão:
```
databricks -v
```

Use tipos de autenticação adicionais

A CLI herdada e a nova CLI oferecem suporte à autenticação access tokens pessoal do Databricks. No entanto, o Databricks recomenda que você use outros tipos de autenticação do Databricks, se possível, aos quais somente a nova CLI dá suporte.

Se for necessário usar a autenticação Databricks pessoal access token, a Databricks recomenda que o senhor use uma autenticação associada a uma entidade de serviço em vez de um usuário Databricks account ou workspace. Consulte gerenciar entidade de serviço.

A nova CLI oferece suporte a tokens OAuth, além do access token pessoal do Databricks. Esses tokens adicionais são mais seguros, pois normalmente expiram em uma hora, enquanto access token pessoal do Databricks pode ser válido de um dia até indefinidamente. Isso é especialmente importante se um tokens for verificado acidentalmente em sistemas de controle de versão que podem ser acessados por outros. Além disso, a nova CLI pode refresh automaticamente esses tokens adicionais quando eles expiram, enquanto refresh access token pessoal do Databricks é um processo manual ou pode ser difícil de automatizar.

Para obter mais informações, consulte Autenticação para a CLI do Databricks.

Grupo de comandos e comparações de comandos

A tabela a seguir lista os grupos de comandos legados da CLI e seus novos grupos de comandos CLI equivalentes. Onde existem diferenças significativas entre as CLIs, tabelas adicionais listam os comandos ou opções da CLI herdada e seus novos comandos ou opções da CLI equivalentes.

Grupos de comando

Grupo de comando legado	Novo grupo de comando
`cluster-policies`	`cluster-policies`. Todos os nomes de comando são iguais.
`clusters`	`clusters`. Todos os nomes de comando são iguais.
`configure`	`configure`. Consulte as opções de configuração.
`fs`	`fs`. Veja os comandos fs.
`groups`	`groups`. Consulte comandos de grupos.
`instance-pools`	`instance-pools`. Todos os nomes de comando são iguais.
`jobs`	`jobs`. Todos os nomes de comando são iguais.
`libraries`	`libraries`. Todos os nomes de comando são iguais, exceto para `list`. O comando `list` não está mais disponível; use os comandos `all-cluster-statuses` ou `cluster-status` em vez disso.
`pipelines`	`pipelines`. Consulte os comandos de pipelines.
`repos`	`repos`. Todos os nomes de comando são iguais.
`runs`	`jobs`. Veja comandos de execução.
`secrets`	`secrets`. Veja os comandos secretos.
`stack`	Não disponível na nova CLI. Databricks recomenda que você use o provedor Databricks Terraform em vez disso.
`tokens`	`tokens`. Consulte comandos de tokens.
`unity-catalog`	Vários. Consulte grupos de comandos do catálogo de unidade.
`workspace`	`workspace`. Consulte comandos da área de trabalho.

`configure` Opções

Opção herdada	Nova opção
`-o`	A CLI legada usa `-o` para autenticação OAuth. Para OAuth na nova CLI, consulte Autenticação de credenciais clouds do Google ou Autenticação de ID clouds do Google. A nova CLI tem como objetivo `-o` especificar se a saída da CLI está em formato de texto ou JSON.
`--oauth`	Para OAuth na nova CLI, consulte Autenticação de credenciais clouds do Google ou Autenticação de ID clouds do Google.
`-s` ou `--scope`	Para OAuth na nova CLI, consulte Autenticação de credenciais clouds do Google ou Autenticação de ID clouds do Google.
`-t` ou `--token`	`-t` ou `--token` (o mesmo)
`-f` ou `--token-file`	Não disponível na nova CLI.
`--host`	`--host` (mesmo)
`--aad-token`	Use `--host` e especifique tokens de ID do Microsoft Entra quando solicitado, em vez de um access token pessoal do Databricks.
`--insecure`	Não disponível na nova CLI.
`--jobs-api-version`	Não está disponível na nova CLI. A nova CLI usa apenas a API 2.1 do Jobs. Para chamar a API 2.0 de Jobs herdada, use a CLI herdada e consulte CLI da Databricks (herdada).
`--debug`	Para depuração e login na nova CLI, consulte o modo de depuração.
`--profile`	`--profile` (mesmo) ou `-p`
`-h` ou `--help`	`-h` ou `--help` (o mesmo)

`fs` comando

Todos os comandos fs na CLI herdada são os mesmos na nova CLI, exceto fs mv , que não está disponível na nova CLI.

comando herdado	Novo comando
`fs cat`	`fs cat` (mesmo)
`fs cp`	`fs cp` (mesmo)
`fs ls`	`fs ls` (mesmo)
`fs mkdirs`	`fs mkdir`
`fs mv`	Não disponível na nova CLI.
`fs rm`	`fs rm` (mesmo)

`groups` comando

comando herdado	Novo comando
`groups add-member`	`groups patch`
`groups create`	`groups create` (mesmo)
`groups delete`	`groups delete` (mesmo)
`groups list`	`groups list` (mesmo)
`groups list-members`	`groups list`
`groups list-parents`	`groups list`
`groups remove-member`	`groups patch`

`pipelines` comando

comando herdado	Novo comando
`pipelines create`	`pipelines create` (mesmo)
`pipelines delete`	`pipelines delete` (mesmo)
`pipelines deploy`	`pipelines create`
`pipelines edit`	`pipelines update`
`pipelines get`	`pipelines get` (mesmo)
`pipelines list`	`pipelines list-pipeline-events` ou `pipelines list-pipelines` ou `pipelines list-updates`
`pipelines reset`	`pipelines reset` (mesmo)
`pipelines start`	`pipelines start update`
`pipelines stop`	`pipelines stop` (mesmo)
`pipelines update`	`pipelines update` (mesmo)

`runs` comando

comando herdado	Novo comando
`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` comando

comando herdado	Novo comando
`secrets create-scope`	`secrets create-scope` (mesmo)
`secrets delete`	`secrets delete-secret`
`secrets delete-acl`	`secrets delete-acl` (mesmo)
`secrets delete-scope`	`secrets delete-scope` (mesmo)
`secrets get-acl`	`secrets get-acl` (mesmo)
`secrets list`	`secrets list-secrets`
`secrets list-acls`	`secrets list-acls` (mesmo)
`secrets list-scopes`	`secrets list-scopes` (mesmo)
`secrets put`	`secrets put-secret`
`secrets put-acl`	`secrets put-acl` (mesmo)
`secrets write`	`secrets put-secret`
`secrets write-acl`	`secrets put-acl`

`tokens` comando

comando herdado	Novo comando
`tokens create`	`tokens create` (mesmo)
`tokens list`	`tokens list` (mesmo)
`tokens revoke`	`tokens delete`

`unity-catalog` grupos de comando

unity-catalog <command> na CLI herdada torna-se apenas <command> na nova CLI.

Grupo de comando legado	Novo grupo de comando
`unity-catalog catalogs`	`catalogs` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog external-locations`	`external-locations` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog lineage`	Não disponível na nova CLI.
`unity-catalog metastores`	`metastores` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog permissions`	`grants`
`unity-catalog providers`	`providers` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog recipients`	`recipients` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog schemas`	`schemas` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog shares`	`shares` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog storage-credentials`	`storage-credentials` (o mesmo, mas elimine `unity-catalog`)
`unity-catalog tables`	`tables` (o mesmo, mas elimine `unity-catalog`)

`workspace` comando

comando herdado	Novo comando
`workspace delete`	`workspace delete` (mesmo)
`workspace export`	`workspace export` (mesmo)
`workspace export-dir`	`workspace export`
`workspace import`	`workspace import` (mesmo)
`workspace import-dir`	`workspace import`
`workspace list`	`workspace list` (mesmo)
`workspace ls`	`workspace list`
`workspace mkdirs`	`workspace mkdirs` (mesmo)
`workspace rm`	`workspace delete`

Argumentos padrão e posicionais

A maioria dos novos comandos da CLI tem pelo menos um argumento default que não possui uma opção de acompanhamento. Alguns novos comandos da CLI têm dois ou mais argumentos posicionais que devem ser especificados em uma ordem específica e que não possuem opções de acompanhamento. Isso é diferente da CLI herdada, em que a maioria dos comandos exige que as opções sejam especificadas para todos os argumentos. Por exemplo, o novo comando clusters get da CLI usa um ID clusters como um argumento default . No entanto, o comando clusers get da CLI herdada requer que você especifique uma opção --cluster-id junto com o ID clusters . Por exemplo:

Para a CLI herdada:

# 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

Para a nova 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

Como outro exemplo, o novo comando grants get da CLI usa dois argumentos default : o tipo protegível seguido pelo nome completo do protegível. No entanto, o comando unity-catalog permissions get da CLI herdada requer que você especifique uma opção --<securable-type> junto com o nome completo do protegível. Por exemplo:

Para a CLI herdada:

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

Para a nova 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

Modo de depuração

A CLI herdada fornece uma opção --debug para mostrar rastreamento de pilha completo em caso de erro. Para a nova CLI, a opção --debug não é reconhecida. Em vez disso, use as seguintes opções:

Use --log-file <path> para gravar informações logs no arquivo especificado em <path>. Se esta opção não for fornecida, as informações logs serão enviadas para stderr. Especificar --log-file sem também especificar --log-level resulta em nenhuma informação logs sendo gravada no arquivo.
Use --log-format <type> para especificar o formato dos logs de informação. <type> pode ser text (o default, se não for especificado) ou json.
Use --log-level <format> para especificar o nível dos logs de informação. Os valores permitidos são disabled (o default, se não for especificado), trace, debug, info, warn e error.

Para a CLI herdada, o exemplo a seguir mostra o rastreamento de pilha completo em caso de erro:

databricks fs ls / --debug

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

Para a nova CLI, o exemplo a seguir logs o rastreamento de pilha completo em um arquivo denominado new-cli-errors.log no diretório de trabalho atual. O rastreamento de pilha é gravado no arquivo no formato 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.)

Perguntas comuns

Esta seção lista perguntas comuns sobre a migração do legado para a nova CLI.

O que está acontecendo com a CLI herdada?

A CLI herdada ainda está disponível, mas não está recebendo nenhuma atualização não crítica. A documentação herdada da CLI reflete isso. Databricks recomenda que os usuários migrem para a nova CLI o mais rápido possível.

A CLI herdada sempre esteve em um estado Experimental com um aviso de isenção de responsabilidade de que Databricks não planeja nenhum novo trabalho de recurso para a CLI herdada e a CLI herdada não tem suporte por meio do canal de suporte da Databricks.

Quando a CLI herdada será descontinuada?

A CLI herdada sempre esteve em um estado Experimental com um aviso de isenção de responsabilidade de que Databricks não planeja nenhum novo trabalho de recurso para a CLI herdada e a CLI herdada não tem suporte por meio do canal de suporte da Databricks.

Databricks não estabeleceu uma data ou cronograma para substituir a CLI herdada. No entanto, o Databricks recomenda que os usuários migrem para a nova CLI o mais rápido possível.

Quando a nova CLI será lançada como disponibilidade geral (GA)?

Uma data de lançamento ou cronograma para liberar a nova CLI como GA não foi estabelecida. Isso dependerá do feedback que o Databricks recebe dos usuários durante a visualização pública.

Quais são as principais diferenças entre as CLIs herdadas e as novas?

A CLI herdada foi lançada como um pacote Python. A nova CLI é lançada como um executável autônomo e não precisa de nenhuma dependência Runtime instalada.
A nova CLI tem cobertura completa das APIs REST do Databricks. A CLI herdada não.
A nova CLI está disponível como uma visualização pública. A CLI herdada permanece em um estado Experimental.

A nova CLI tem paridade total de recursos com a CLI herdada?

A nova CLI cobre quase todos os comandos da CLI herdada. No entanto, notavelmente ausente da nova CLI está o grupo de comandos stacks na CLI herdada. Além disso, alguns grupos de comandos legados da CLI, como unity-catalog e runs foram refatorados em novos grupos de comandos na nova CLI. Para obter orientação sobre migração, consulte as informações fornecidas anteriormente nestes artigos.

Como faço para migrar do legado para a nova CLI?

Para obter orientação sobre migração, consulte as informações fornecidas anteriormente nestes artigos. Observe que a nova CLI não é uma substituição imediata da CLI herdada e requer alguma configuração para passar da herdada para a nova CLI.

As instalações de CLIs antigas e novas podem existir na mesma máquina?

Sim. As instalações do legado e das novas CLIs podem existir na mesma máquina, mas devem estar localizadas em diretórios diferentes. Como os executáveis são ambos denominados databricks, você deve controlar qual executável é executado por default configurando o PATH de sua máquina. Se você deseja executar a nova CLI, mas de alguma forma executar acidentalmente a CLI herdada, por default , a CLI herdada executará a nova CLI com os mesmos argumentos e mostrará a seguinte mensagem de aviso:

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>

Conforme mostrado na mensagem de aviso anterior, você pode definir a variável de ambiente DATABRICKS_CLI_DO_NOT_EXECUTE_NEWER_VERSION como 1 para desativar esse comportamento e, em vez disso, executar a CLI herdada.

Obter ajuda

Para obter ajuda com a migração da CLI herdada para a nova CLI, consulte os seguintes recursos:

Suporte Databricks