Databricks Driver for SQLTools para Visual Studio Code

  • Artigo

Importante

Esse recurso está em uma versão prévia.

O Databricks Driver for SQLTools permite a você usar a extensão SQLTools para Visual Studio Code para procurar objetos SQL e executar consultas SQL em workspaces remotos do Azure Databricks.

Antes de começar

Antes de usar o Databricks Driver for SQLTools, o workspace do Azure Databricks e o computador de desenvolvimento local devem atender aos requisitos a seguir.

Requisitos do espaço de trabalho

Você deve ter pelo menos um workspace do Azure Databricks disponível e o workspace deve atender aos seguintes requisitos:

Requisitos do computador de desenvolvimento local

Você deve ter o seguinte no computador de desenvolvimento local:

  • Visual Studio Code versão 1.70 ou superior. Para exibir a versão instalada, clique em Código > Sobre o Visual Studio Code no menu principal no Linux ou macOS e Ajuda > Sobre no Windows. Para baixar, instalar e configurar o Visual Studio Code, confira Configurar o Visual Studio Code.
  • A extensão SQLTools para o Visual Studio Code.
  • A extensão Databricks Driver for SQLTools para Visual Studio Code.

Para instalar a extensão SQLTools, vá para SQLTools e clique em Instalar ou:

  1. No Visual Studio Code, clique em Exibir > Extensões no menu principal.

  2. Na caixa Pesquisar Extensões no Marketplace, insira SQLTools.

  3. Clique na entrada SQLTools de Matheus Teixeira.

    Observação

    Pode haver várias entradas SQLTools listadas. Certifique-se de clicar na entrada de Matheus Teixeira.

  4. Clique em Instalar.

Para instalar a extensão Databricks Driver for SQLTools, acesse Databricks Driver for SQLTools e clique em Instalar ou:

  1. No Visual Studio Code, clique em Exibir > Extensões no menu principal.
  2. Na caixa Pesquisar Extensões no Marketplace, insira Databricks Driver for SQLTools.
  3. Clique na entrada Databricks Driver for SQLTools.
  4. Clique em Instalar.

Autenticação

Você deve configurar a autenticação para o Databricks Driver para SQLTools da seguinte forma.

O Databricks Driver para SQLTools dá suporte para os seguintes tipos de autenticação do Azure Databricks:

Observação

O Databricks Driver for SQLTools não dá suporte para tokens do Microsoft Entra ID (antigo Azure Active Directory).

Autenticação de token de acesso pessoal do Azure Databricks

Para usar o Databricks Driver for SQLTools com o Azure Databricks autenticação por token de acesso pessoal, você deve ter um token de acesso pessoal do Azure Databricks. Para criar um token de acesso pessoal, faça o seguinte:

  1. No workspace do Azure Databricks, clique no nome de usuário do Azure Databricks na barra superior e selecione Configurações na lista suspensa.
  2. Clique em Desenvolvedor.
  3. Ao lado de Tokens de acesso, clique em Gerenciar.
  4. Clique em Gerar novo token.
  5. (Opcional) Insira um comentário que ajude você a identificar esse token no futuro e altere o tempo de vida padrão do token de 90 dias. Para criar um token sem tempo de vida (não recomendado), deixe a caixa Tempo de vida (dias) vazia (em branco).
  6. Clique em Gerar.
  7. Copie o token exibido para um local seguro e clique em Concluído.

Observação

Lembre-se de salvar o token copiado em um local seguro. Não compartilhe seu token copiado com outras pessoas. Se você perder o token copiado, não poderá regenerar exatamente aquele mesmo token. Em vez disso, será necessário repetir esse procedimento para criar um novo token. Caso você tenha perdido o token copiado ou acredite que ele tenha sido comprometido, o Databricks recomenda que você exclua imediatamente esse token do seu workspace clicando no ícone de lixeira (Revogar) ao lado do token na página de Tokens de acesso.

Se você não conseguir criar ou usar tokens em seu workspace, isso pode ocorrer porque o administrador do workspace desabilitou tokens ou não deu permissão para criar ou usar tokens. Veja o administrador do workspace ou o seguinte:

Autenticação OAuth máquina-a-máquina (M2M) do Azure Databricks

É possível usar a autenticação Azure Databricks OAuth máquina-a-máquina (M2M) para autenticar com o Databricks Driver para o SQLTools, como segue:

Observação

A autenticação OAuth M2M do Azure Databricks está disponível nas versões 0.4.2 e posteriores do Databricks Driver para SQLTools.

  1. Conclua as etapas de configuração da autenticação OAuth M2M. Confira Autenticação OAuth M2M (máquina a máquina).
  2. Crie um perfil de configuração do Azure Databricks com suas definições de configuração da autenticação OAuth M2M. Consulte a seção "Configuração" da Autenticação OAuth máquina-a-máquina (M2M).
  3. Instale e abra a extensão do Databricks para Visual Studio Code em seu computador de desenvolvimento local.
  4. Na extensão do Databricks para Visual Studio Code, clique no botão Configurar no painel Configuração. Se o botão Configurar não for exibido, clique no ícone de engrenagem (Configurar workspace).
  5. Na Paleta de Comandos, para o Databricks Host, insira a URL do Azure Databricks por espaço de trabalho, por exemplo https://adb-1234567890123456.7.azuredatabricks.net, e pressione Enter.
  6. Selecione a entrada de em perfil de configuração que corresponda à que você criou na etapa 2.
  7. Conclua as instruções na tela do navegador da Web para concluir a autenticação com sua conta do Databricks do Azure.

Autenticação OAuth usuário-para-máquina (U2M) do Azure Databricks

É possível usar a autenticação OAuth de usuário-para-máquina (U2M) do Azure Databricks para se autenticar com o Databricks Driver para SQLTools, como segue:

Observação

A autenticação OAuth U2M do Azure Databricks está disponível nas versões 0.4.2 e posteriores do Databricks Driver para SQLTools.

  1. Instale e abra a extensão do Databricks para Visual Studio Code em seu computador de desenvolvimento local.
  2. Na extensão do Databricks para Visual Studio Code, clique no botão Configurar no painel Configuração. Se o botão Configurar não for exibido, clique no ícone de engrenagem (Configurar workspace).
  3. Na Paleta de Comandos, para o Host do Databricks, insira a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net. Em seguida, pressione Enter.
  4. Selecione OAuth (usuário para computador).
  5. Conclua as instruções na tela do navegador da Web para concluir a autenticação com sua conta do Databricks do Azure. Se solicitado, permita o acesso all-apis.

Autenticação da CLI do Azure

É possível usar a CLI do Azure para se autenticar com o Databricks Driver para SQLTools, como segue:

Observação

A autenticação com a CLI do Azure está em um estado de recurso experimental. Esse recurso está disponível nas versões 0.4.2 e posteriores do Databricks Driver para SQLTools.

  1. Instale a CLI do Azure em seu computador de desenvolvimento local, caso ainda não tenha feito isso.
  2. Instale e abra a extensão do Databricks para Visual Studio Code em seu computador de desenvolvimento local.
  3. Na extensão do Databricks para Visual Studio Code, clique no botão Configurar no painel Configuração. Se o botão Configurar não for exibido, clique no ícone de engrenagem (Configurar workspace).
  4. Na Paleta de Comandos, para o Host do Databricks, insira a URL por workspace do Azure Databricks, por exemplo https://adb-1234567890123456.7.azuredatabricks.net. Em seguida, pressione Enter.
  5. Selecione CLI do Azure.
  6. Siga os prompts na tela para concluir a autenticação usando a CLI do Azure.

Conectar-se a um esquema

  1. No Visual Studio Code, na barra lateral, clique no ícone SQLTools.
  2. Na exibição SQLTools, se esta for a primeira vez que você usa a extensão SQLTools, clique em Adicionar Nova Conexão no painel Conexões. Caso contrário, clique no ícone Adicionar Nova Conexão na barra de título do painel.
  3. Na guia Configurações do SQLTools, para a etapa Selecionar um driver de banco de dados, clique no ícone Databricks.
  4. Na etapa Configurações de Conexão, insira as informações a seguir sobre o warehouse, catálogo e esquema:

    1. Em Nome da conexão, insira um nome exclusivo para essa conexão.

    2. (Opcional) Para Grupo de conexões, insira o nome de um grupo de conexões existente para adicionar a nova conexão a esse grupo. Ou insira um nome exclusivo para criar um novo grupo de conexões com a nova conexão. Os grupos de conexões facilitam a localização de conexões na extensão.

    3. Para Conectar-se usando, selecione uma das seguintes opções:

      • Para usar um token de acesso pessoal do Azure Databricks para autenticação, selecione Nome do host e Token.
      • Para as versões 0.4.2 e posteriores do Databricks Driver para SQLTools, para usar a autenticação OAuth U2M ou M2M ou a CLI do Azure, selecione extensão do VS Code (beta).

    4. Se você selecionou Nome do host e Token para Conectar usando, em seguida, para Host, insira a configuração Nome do host do servidor do warehouse. Para obter a configuração de Nome do host do servidor de um warehouse, confira Obter detalhes de conexão para um recurso de computação do Azure Databricks.

    5. Em Caminho, insira a configuração de caminho HTTP do warehouse ou do cluster. Para obter a configuração de Caminho HTTP de um warehouse, confira Obter detalhes de conexão para um recurso de computação do Azure Databricks.

    6. Se você selecionou Nome do Host e Token para Conectar usando, insira o valor do token de acesso pessoal do Azure Databricks no Token.

    7. Em Catálogo, insira o nome do catálogo.

      Observação

      Para workspaces que não estão habilitados para o Catálogo Unity, você pode deixar Catálogo em branco para usar o valor padrão de hive_metastore.

    8. Em Esquema, insira o nome do esquema.

    9. (Opcional) Para Mostrar limite padrão de registros, deixe o padrão de 50 para mostrar apenas até as primeiras 50 linhas para cada consulta, ou insira um limite diferente.

  5. Clique em Testar Conexão.
  6. Se o teste de conexão for bem-sucedido, clique em Salvar conexão.

Alterar as configurações de uma conexão

Este procedimento pressupõe que você se conectou com êxito a pelo menos um warehouse.

  1. Se a exibição do SQLTools não estiver visível, no Visual Studio Code, na barra lateral, clique no ícone SQLTools.
  2. No painel Conexões, expanda o grupo de conexões, se houver um para a conexão de destino.
  3. Clique com o botão direito do mouse na conexão e clique em Editar Conexão.
  4. Altere as configurações de destino.
  5. Clique em Testar Conexão.
  6. Se o teste de conexão for bem-sucedido, clique em Salvar conexão.

Procurar objetos de um esquema

  1. No painel Conexões, expanda o grupo de conexões, se houver um para a conexão de destino.
  2. Clique duas vezes ou expanda a conexão de destino para o warehouse.
  3. Expanda o banco de dados de destino (esquema), se houver um para a conexão.
  4. Expanda Tabelas ou Exibições, se houver uma ou mais tabelas ou exibições para o banco de dados (esquema).
  5. Expanda qualquer tabela ou exibição de destino para exibir as colunas da tabela ou da exibição.

Exibir as linhas ou o esquema de uma tabela ou exibição

Com Tabelas ou Exibições expandidas no painel Conexões, siga um destes procedimentos:

  • Para mostrar as linhas da tabela ou da exibição, clique com o botão direito do mouse na tabela ou exibição e clique em Mostrar Registros da Tabela ou Mostrar Registros da Exibição.
  • Para mostrar o esquema da tabela ou da exibição, clique com o botão direito do mouse na tabela ou exibição e clique em Descrever Tabela ou Descrever Exibição.

Gerar uma consulta de inserção para uma tabela

  1. Coloque o cursor em um editor existente no local onde você deseja que a consulta de inserção seja adicionada.
  2. Com Tabelas expandidas no painel Conexões, clique com o botão direito do mouse na tabela e clique em Gerar Consulta de Inserção. A definição da consulta de inserção é adicionada no ponto de inserção do cursor.

Criar e executar uma consulta

Este procedimento pressupõe que você se conectou com êxito a pelo menos um warehouse.

  1. No painel Conexões, expanda o grupo de conexões, se houver um para a conexão de destino.
  2. Clique duas vezes ou expanda a conexão de destino para o warehouse.
  3. Com a conexão selecionada, clique em Novo Arquivo SQL na barra de título do painel Conexões. Uma nova guia do editor é exibida.
  4. Insira sua consulta SQL no novo editor.
  5. Para executar a consulta SQL, clique em Executar na conexão ativa no editor. Os resultados da consulta são exibidos em uma nova guia do editor.

Executar uma consulta existente

Este procedimento pressupõe que você se conectou com êxito a pelo menos um warehouse.

  1. No painel Conexões, expanda o grupo de conexões, se houver um para a conexão de destino.
  2. Clique duas vezes ou expanda a conexão de destino para o warehouse.
  3. Com a conexão selecionada, abra qualquer arquivo com a extensão de arquivo de .sql ou selecione qualquer grupo de instruções SQL contínuas em qualquer editor que tenha sido aberto anteriormente.
  4. Para executar a consulta SQL em um arquivo aberto .sql, com o conteúdo do arquivo .sql exibido no editor, clique em Executar na conexão ativa no editor. Os resultados da consulta são exibidos em uma nova guia do editor.
  5. Para executar um grupo selecionado de instruções SQL contínuas em um editor aberto anteriormente, clique com o botão direito do mouse na seleção e clique em Executar Consulta Selecionada. Os resultados da consulta são exibidos em uma nova guia do editor.

Enviar logs de uso para o Databricks

Se você encontrar problemas ao usar o Databricks Driver for SQLTools, poderá enviar os logs de uso e as informações relacionadas ao Suporte do Databricks fazendo o seguinte:

  1. Instale e abra a extensão do Databricks para Visual Studio Code no computador de desenvolvimento local.
  2. Ative o log marcando a configuração Logs: Habilitado ou configurando databricks.logs.enabled como true, conforme descrito em Configurações da extensão do Databricks para Visual Studio Code. Lembre-se de reiniciar o Visual Studio Code depois de ativar o log.
  3. Tente reproduzir o problema.
  4. Na Paleta de Comandos (Exibir > Paleta de Comandos no menu principal), execute o comando Databricks: Abrir logs completos.
  5. Envie os arquivos Databricks Logs.log, databricks-cli-logs.json e sdk-and-extension-logs.json exibidos para o Suporte do Databricks.
  6. Copie também o conteúdo do Terminal (Exibir > Terminal) no contexto do problema e envie esse conteúdo para o Suporte do Databricks.

A exibição Saída (Exibir > Saída, Logs do Databricks) mostra informações truncadas se Logs: Habilitado está marcado ou databricks.logs.enabled está definido como true. Para mostrar mais informações, altere as seguintes definições, conforme descrito em Configurações da extensão do Databricks para Visual Studio Code:

  • Logs: Tamanho Máximo da Matriz ou databricks.logs.maxArrayLength
  • Logs: Tamanho Máximo do Campo ou databricks.logs.maxFieldLength
  • Logs: Profundidade de Truncamento ou databricks.logs.truncationDepth

Recursos adicionais