Migração da CLI do Databricks

Este artigo descreve como migrar da CLI do Databricks versão 0.18 ou inferior para a CLI do Databricks versão 0.205 ou superior. As versões 0.205 da CLI do Databricks e superiores estão em Versão Prévia Pública.

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

Para obter mais informações sobre as CLIs herdada e nova, consulte:

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

Desinstalar 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

Instalar a nova CLI

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

Verificar sua instalação da 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 ambientes virtuais do Python, ambientes conda ou ambientes semelhantes.

Para verificar a versão da instalação padrão da CLI, execute o seguinte comando:

databricks -v

Se o número de 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 não deseja mais usar. Talvez seja necessário atualizar o PATH do sistema operacional para que o caminho para a versão restante da CLI que você deseja usar esteja listado.
• Se você quiser continuar usando várias versões da CLI: Prefixe o caminho completo à versão da CLI que você deseja usar para cada chamada à CLI.
• Se você quiser continuar usando várias versões da CLI, mas não quiser continuar prefixando o caminho completo à versão da CLI que você usa com mais frequência: verifique se o caminho completo para essa versão está listado primeiro no PATH do seu sistema operacional. Observe que você ainda deve preparar o caminho completo para versões da CLI que não estão listadas primeiro no PATH do sistema operacional.

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

MacOS ou Linux

1. Liste os caminhos em que o databricks está instalado executando um dos seguintes comandos:

   which -a databricks
   
   # Or:
   where databricks
   

2. Obtenha o caminho para a instalação que você deseja usar sem acrescentar o caminho completo a cada chamada à 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
   

3. Para colocar o caminho para a instalação que você deseja usar primeiro no seu PATH, execute o comando a seguir, substituindo /usr/local/bin pelo caminho que você deseja usar. Não adicione databricks ao final deste caminho. Por exemplo:

   export PATH="/usr/local/bin:$PATH"
   

4. Para verificar se o PATH foi definido corretamente para a sessão do terminal atual, execute databricks seguido por -v e verifique o número de versão:

   databricks -v
   

5. Para definir o PATH dessa forma sempre que você reiniciar o terminal, adicione o comando da etapa 3 ao arquivo de inicialização do shell. Por exemplo, para o Zshell, esse arquivo normalmente está localizado em ~/.zshrc. Para o Bash, esse arquivo normalmente está localizado em ~/.bashrc. Para outros shells, consulte a documentação do provedor de shell.

6. Depois de atualizar o arquivo de inicialização do shell, você deve reiniciar o terminal para aplicar o valor PATH atualizado.

Windows

1. Clique com o botão direito do mouse na instalação do databricks que você deseja usar sem acrescentar o caminho completo a cada chamada à CLI.

2. Clique em Abrir local do arquivo.

3. Anote o caminho para databricks, por exemplo C:\Windows.

4. No menu Iniciar, pesquise Variáveis de ambiente.

5. Clique em Editar variáveis de ambiente para sua conta.

6. Selecione a variável Caminho na seção Variáveis de usuário para <username>.

7. Clique em Editar.

8. Clique em Novo.

9. Insira o caminho que você deseja adicionar, sem databricks.exe (como C:\Windows).

10. Use o botão Mover para Cima para mover o caminho que você acabou de adicionar ao início da lista.

11. Clique em OK.

12. Para verificar se o PATH foi definido corretamente, abra um novo Prompt de Comando, execute databricks seguido por -v e verifique o número de versão:

    databricks -v
    

Usar tipos de autenticação adicionais

A CLI herdada e a nova CLI dão suporte à autenticação de token de acesso pessoal do Azure Databricks. No entanto, o Databricks recomenda que você use outros tipos de autenticação do Azure Databricks, se possível, aos quais só a nova CLI dá suporte.

Se você precisar usar a autenticação de token de acesso pessoal do Azure Databricks, o Databricks recomenda que você use uma associada a uma entidade de serviço em vez de associada a uma conta do Azure Databricks ou a um usuário do workspace. Confira Gerenciar entidades de serviço.

Além dos tokens de acesso pessoal do Azure Databricks, a nova CLI dá suporte aos tokens do Microsoft Entra ID. Esses tokens adicionais são mais seguros, pois normalmente expiram em uma hora, enquanto os tokens de acesso pessoal do Azure Databricks podem ser válidos de um dia até indefinidamente. Isso é especialmente importante se um token for verificado acidentalmente em sistemas de controle de versão que podem ser acessados por outras pessoas. Além disso, a nova CLI pode atualizar automaticamente esses tokens adicionais quando eles expiram, enquanto atualizar tokens de acesso pessoal do Azure 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 entre os comandos

A tabela a seguir lista os grupos de comandos da CLI herdada e seus de grupo de comandos equivalentes na nova CLI. Quando existem diferenças significativas entre as CLIs, tabelas adicionais listam comandos ou opções da CLI herdada e seus comandos ou opção equivalentes da nova CLI.

Grupos de comandos

configure options

Comandos de fs

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

Comandos de groups

Comandos de pipelines

Comandos de runs

Comandos de secrets

Comandos de tokens

Grupos de comandos unity-catalog

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

Comandos de workspace

Argumentos padrão e posicionais

A maioria dos comandos da nova CLI tem pelo menos um argumento padrão que não tem uma opção de acompanhamento. Alguns comandos da nova CLI têm dois ou mais argumentos posicionais que devem ser especificados em uma ordem específica e que não têm opções de acompanhamento. Isso é diferente da CLI herdada, na qual a maioria dos comandos exige que as opções sejam especificadas para todos os argumentos. Por exemplo, o comando clusters get da nova CLI usa uma ID de cluster como um argumento padrão. No entanto, o comando clusers get da CLI herdada exige que você especifique uma opção --cluster-id junto com a ID do cluster. 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 comando grants get da nova CLI usa dois argumentos padrão: o tipo protegível seguido pelo nome completo do protegível. No entanto, o comando unity-catalog permissions get da CLI herdada exige que você especifique uma opção --<securable-type> junto com a ID do cluster. 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 o rastreamento de pilha completo em caso de erro. Para a nova CLI, a opção --debug não é reconhecida. Em vez disso, realize as etapas a seguir:

• Use --log-file <path> para gravar informações de log no arquivo especificado em <path>. Se essa opção não for fornecida, as informações de log serão apresentadas para stderr. Especificar --log-file sem especificar --log-level também resulta em nenhuma informação de log sendo gravada no arquivo.
• Use --log-format <type> para especificar o formato das informações registradas. <type> pode sertext (o padrão, se não especificado) ou json.
• Use --log-level <format> para especificar o nível de informações registradas. Os valores permitidos são disabled (o padrão, se não 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 registra o rastreamento de pilha completo em um arquivo chamado 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 as perguntas comuns sobre como migrar da CLI herdada para a nova.

O que está acontecendo com a CLI herdada?

A CLI herdada ainda está disponível, mas não está recebendo atualizações não críticas. A documentação da CLI herdada reflete isso. O 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 o Databricks não planeja nenhum novo trabalho de recurso para a CLI herdada, e a CLI herdada não tem suporte por meio de canais de suporte do Databricks.

Quando a CLI herdada será preterida?

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

O Databricks não estabeleceu uma data ou linha do tempo para preterir a CLI herdada. No entanto, o Databricks recomenda que os usuários migrem para a nova CLI assim que possível.

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

Uma data de lançamento ou linha do tempo para lançar a nova CLI em GA não foi estabelecida. Isso dependerá dos comentários que o Databricks recebe dos usuários durante a Visualização Pública.

Quais são as principais diferenças entre a CLI herdada e a nova?

• 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 dependências de runtime instaladas.
• A nova CLI tem cobertura completa das APIs REST do Databricks. A CLI herdada não tem.
• A nova CLI está disponível em Visualização Pública. A CLI herdada permanece em estado experimental.

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

A nova CLI tem cobertura para quase todos os comandos da CLI herdada. No entanto, notavelmente ausente da nova CLI é o grupo de comandos stacks da CLI herdada. Além disso, alguns grupos de comandos da CLI herdada, como unity-catalog e runs, por exemplo, foram refatorados em novos grupos de comandos na nova CLI. Para obter diretrizes de migração, consulte as informações fornecidas anteriormente neste artigo.

Como fazer para migrar da CLI herdada para a nova?

Para obter diretrizes de migração, consulte as informações fornecidas anteriormente neste artigo. Observe que a nova CLI não é uma substituição suspensa para a CLI herdada e requer alguma configuração para passar do herdado para a nova CLI.

As instalações da CLI herdada e a da nova podem existir no mesmo computador?

Sim. As instalações da CLI herdada e a da nova podem existir no mesmo computador, mas devem estar localizadas em diretórios diferentes. Como os executáveis são ambos chamados databricks, você deve controlar qual executável é executado por padrão, configurando o PATH do computador. Se você quiser executar a nova CLI, mas de alguma forma executar acidentalmente a CLI herdada, por padrão, 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 desabilitar esse comportamento e executar a CLI herdada.

Obter ajuda

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

• Central de ajuda do Databricks
• Horário comercial do Databricks