Migração do SnowSQL para Snowflake CLI¶

Instalar o software Snowflake CLI¶

Assim como o SnowSQL, o Snowflake CLI fornece instaladores binários. Além disso, ele também permite que você instale o software usando homebrew e pip.

Atualmente, o Snowflake CLI aceita as seguintes plataformas:

• macOS (arm)

  • Instalador de pacotes

  • Homebrew

  • PyPi (pip)

• macOS (x86_64):

  • Instalador de pacotes

  • Homebrew

  • PyPi (pip)

• Linux (x86_64 e aarch64):

  • Instalador de pacotes deb

  • Instalador de pacotes rpm

  • PyPi (pip)

• Windows (64 bits):

  • Instalador

  • PyPi (pip)

Atualmente, o Snowflake CLI não aceita as seguintes plataformas:

• Instalador bash do Linux

Para obter mais informações sobre a instalação do Snowflake CLI, consulte Instalação do Snowflake CLI.

Migrar suas conexões e configurações do SnowSQL¶

O Snowflake CLI fornece um grupo de comandos snow helpers para simplificar o processo de transição do SnowSQL para o Snowflake CLI. Use estes comandos para importar facilmente suas conexões existentes e suas variáveis ​​de ambiente:

• O comando snow helpers import-snowsql-connections usa um menu interativo para permitir que você escolha quais conexões do SnowSQL deseja importar. Para obter mais informações, consulte Importação de conexões de SnowSQL.

• O comando snow helpers check-snowsql-env-vars ajuda a diagnosticar quais variáveis ​​de ambiente estão definidas no seu ambiente do SnowSQL e exibe os equivalentes do Snowflake CLI correspondentes. Para obter mais informações, consulte Usos das variáveis em SQL.

Se você usar o SnowSQL para executar instruções SQL em linha ou executar arquivos, mas não quiser editar todos os seus scripts, considere criar um alias que mapeie snowsql para o comando snow sql. Por exemplo, em sistemas do tipo Unix, use o seguinte comando:

alias snowsql='snow sql'

Com esse alias, você pode usar seus scripts existentes com o Snowflake CLI.

Observe que, se você for um usuário mais avançado do SnowSQL, poderá ocasionalmente encontrar mensagens de incompatibilidade, que normalmente estão relacionadas às opções usadas para configurar o SnowSQL. Como o Snowflake CLI não usa todas as opções de configuração do SnowSQL, talvez seja necessário fazer cópias dos seus scripts e remover essas opções incompatíveis.

Reverter para o SnowSQL¶

O Snowflake CLI usa seus próprios arquivos de configuração, então você pode continuar a usar o SnowSQL. Você pode instalar o SnowSQL e o Snowflake CLI e executá-los independentemente. Se você definir um alias, conforme descrito acima, deverá removê-lo para usar o comando snowsql para o SnowSQL.

Diferenças nos arquivos de configuração¶

• SnowSQL

  O SnowSQL é configurado por seu arquivo de configuração, que é um arquivo no formato TOML que contém configurações de conexão, diversas configurações da ferramenta e variáveis ​​que podem ser usadas em consultas SQL. As configurações podem ser divididas em vários locais, o que permite definir padrões para todo o sistema e substituí-los para diferentes usuários. Você também pode especificar configurações de locais personalizados especificando a opção de linha de comando --config. Para obter mais informações, consulte Referência de parâmetros de conexão.

• Snowflake CLI

  O Snowflake CLI também possui seu próprio arquivo de configuração TOML que especifica as configurações de conexão e as definições da ferramenta. Ele não permite definir variáveis ​​para uso posterior em consultas SQL. As variáveis no Snowflake CLI são definidas no nível do projeto em arquivos de definição de projeto. O Snowflake CLI usa apenas um arquivo de configuração que, por padrão, está localizado no diretório inicial do usuário. Você também pode especificar configurações de locais personalizados especificando a opção de linha de comando --config. Para mais informações, consulte a referência de comando snow.

Encontrar o arquivo de configuração padrão Snowflake CLI¶

A localização da configuração padrão do Snowflake CLI depende do seu sistema e é determinada pela ordem especificada no Local do arquivo de configuração .toml.

• Para encontrar o valor do parâmetro default_config_file_path para a sua instalação do Snowflake CLI, execute o comando snow --info conforme mostrado:

  snow --info
  

  Copy

  [
    ...
  
    {
        "key": "default_config_file_path",
        "value": "/<user_home>/.snowflake/config.toml"
    },
  
    ...
  ]
  

Importação de conexões de SnowSQL¶

Você pode importar todas as suas conexões SnowSQL com o comando snow helpers import-snowsql-connections. Para obter mais informações, consulte Importação de conexões de SnowSQL e a referência do comando snow helpers import-snowsql-connections.

Migrar manualmente a configuração de conexão padrão¶

Se você optar por não importar conexões usando o comando snow helpers import-snowsql-connections, poderá migrar a conexão padrão manualmente.

As diferenças na especificação da conexão padrão incluem o seguinte:

• SnowSQL

  A conexão padrão é configurada no arquivo de configuração do SnowSQL, e as configurações de conexão são definidas diretamente na seção [connections].

• Snowflake CLI

  A conexão padrão é configurada no arquivo de configuração do Snowflake CLI como uma conexão com o nome default_connection_name, definido no nível superior da configuração (consulte Definição da conexão padrão). Você pode alterar a conexão padrão usando o comando snow connection set-default.

Por padrão, tanto o SnowSQL quanto o Snowflake CLI usam a configuração de conexão padrão para se conectar ao Snowflake. Se você o tiver configurado no SnowSQL, migre essa configuração para o arquivo de configuração do Snowflake CLI, da seguinte forma:

1. Abra o arquivo de configuração do SnowSQL e encontre os parâmetros de conexão padrão na seção [connections]. Você precisará dos valores dos parâmetros de conexão ao adicionar a conexão ao Snowflake CLI.

2. Para adicionar a conexão ao Snowflake CLI, use um dos seguintes métodos:

   • Edite manualmente o arquivo de configuração do Snowflake CLI da seguinte forma:

     1. Abra o arquivo de configuração do Snowflake CLI.

     2. Adicione uma seção [connections.your_connection_name] e copie/cole os detalhes da configuração padrão do arquivo de configuração do SnowSQL.

     3. Altere os nomes dos seguintes parâmetros, conforme mostrado:

        • accountname para account

        • username para user

        • dbname para database

        • schemaname para schema

        • warehousename para warehouse

        • rolename para role

     4. Adicione ou defina a configuração default_connection_name = "your_connection_name" no nível superior do arquivo de configuração (consulte Definição da conexão padrão).

   • Use os comandos snow connection add e snow connection set-default. Para obter mais informações, consulte Gerencie ou adicione suas conexões ao Snowflake com os comandos snow connection.

Migrar manualmente suas configurações de conexão nomeada¶

Se você não usar o comando snow helpers import-snowsql-connections para importar suas conexões, poderá migrá-las manualmente.

As diferenças na especificação de conexões nomeadas incluem o seguinte:

• SnowSQL

  As conexões nomeadas são configuradas no arquivo de configuração do SnowSQL. Cada conexão nomeada tem sua própria seção [connections.your_connection_name].

• Snowflake CLI

  O Snowflake CLI usa quase o mesmo formato para configurar conexões nomeadas. Você pode copiá-las da configuração do SnowSQL e renomear os parâmetros conforme especificado na conexão padrão.

Por padrão, o SnowSQL e o Snowflake CLI permitem que você use uma conexão nomeada para se conectar ao Snowflake. Se desejar continuar usando essas conexões nomeadas no SnowSQL, você deve migrá-las para o arquivo de configuração do Snowflake CLI:

1. Abra o arquivo de configuração do SnowSQL e localize as seções [connections.your_connection_name]. Você precisa dos valores dos parâmetros de conexão ao adicionar as conexões ao Snowflake CLI.

2. Para adicionar a conexão ao Snowflake CLI, use um dos seguintes métodos:

   • Edite manualmente o arquivo de configuração do Snowflake CLI da seguinte forma:

     1. Abra o arquivo de configuração do Snowflake CLI.

     2. Adicione uma seção [connections.your_connection_name] e copie/cole os detalhes da configuração padrão do arquivo de configuração do SnowSQL.

     3. Altere os nomes dos seguintes parâmetros, conforme mostrado:

        • accountname para account

        • username para user

        • dbname para database

        • schemaname para schema

        • warehousename para warehouse

        • rolename para role

   • Use o comando snow connection add. Para obter mais informações, consulte Gerencie ou adicione suas conexões ao Snowflake com os comandos snow connection.

Configurar logs¶

Para configurar manualmente o registro em log para o Snowflake CLI, consulte a documentação Configuração do registro em log.

Migrar suas variáveis¶

O Snowflake CLI não aceita a especificação de variáveis ​​no arquivo de configuração. Em vez disso, ele usa uma abordagem mais focada em projetos, que associa variáveis ​​a projetos específicos. O Snowflake CLI permite definir variáveis ​​em arquivos de definição de projeto snowflake.yml. Você pode então usar essas variáveis ​​em consultas SQL, conforme descrito em Sobre arquivos de definição de projeto.

• Para definir variáveis ​​para o seu projeto, adicione uma seção env ao arquivo snowflake.yml do projeto e inclua as variáveis ​​que você queira usar em suas consultas.

O exemplo a seguir define duas variáveis: database e role:

definition_version: 2
env:
  database: "dev"
  role: "eng_rl"

Migrar manualmente suas variáveis ​​de ambiente¶

No SnowSQL, você pode usar variáveis ​​de ambiente (como $SNOWSQL_ACCOUNT e $SNOWSQL_DATABASE) em vez de especificar parâmetros de linha de comando ao iniciar uma conexão. Essa abordagem oferece outra maneira de especificar configurações de conexão padrão. O Snowflake CLI oferece a mesma funcionalidade, mas usa nomes diferentes para esses parâmetros e permite que você substitua muitos outros parâmetros de configuração por meio de variáveis ​​de ambiente. Se você estiver usando variáveis ​​de ambiente para se conectar ao Snowflake, para obter mais informações, consulte Conexão ao Snowflake com variáveis ​​de ambiente. Consulte também informações sobre as possibilidades de configurar variáveis ​​de ambiente na documentação do Snowflake CLI.

Usar a conexão padrão¶

• Para conectar-se usando a configuração padrão definida no seu arquivo de configuração:

  • SnowSQL

    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -q "select 1"
    

    Copy

Usar uma conexão com opções de linha de comando¶

• Para conectar-se usando a configuração padrão definida no seu arquivo de configuração e substituir parâmetros por opções de linha de comando:

  • SnowSQL

    snowsql --username myname -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql --username myname -q "select 1"
    

    Copy

    Para obter uma lista de possíveis opções de linha de comando, consulte snow sql. Observe que algumas opções têm nomes diferentes daqueles no SnowSQL.

Usar uma configuração nomeada¶

• Para conectar-se usando uma configuração nomeada definida no seu arquivo de configuração:

  • SnowSQL

    snowsql -c dev -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -c dev -q "select 1"
    

    Copy

Usar apenas opções de linha de comando¶

• Para conectar-se usando apenas opções de linha de comando em vez de uma conexão configurada:

  • SnowSQL

    snowsql \
      --accountname myaccount \
      --username myuser \
      --authenticator SNOWFLAKE_JWT \
      --private-key-path "path_to_my_key" \
      -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql \
      --temporary-connection \
      --accountname myaccount \
      --username myuser \
      --authenticator SNOWFLAKE_JWT \
      --private-key-path "path_to_my_key" \
      -q "select 1"
    

    Copy

    Observe que o Snowflake CLI requer a opção --temporary-connection para esse método.

Usar variáveis ​​de ambiente¶

• Para conectar-se usando a conexão padrão, passando alguns parâmetros como variáveis ​​de ambiente:

  • SnowSQL

    export SNOWSQL_USER=myuser
    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    export SNOWFLAKE_USER=myuser
    snow sql -q "select 1"
    

    Copy

    Observe que os nomes das variáveis ​​de ambiente podem ser diferentes. Para obter mais informações, consulte Use variáveis de ambiente para credenciais Snowflake.

Usar uma mistura de conexões, variáveis ​​de ambiente e opções de linha de comando¶

• Para conectar-se usando uma abordagem mista com uma conexão nomeada, variáveis ​​de ambiente e opções de linha de comando:

  • SnowSQL

    export SNOWSQL_USER=myuser
    snowsql -c dev --accountname myaccount -q "select 1"
    

    Copy

  • Snowflake CLI

    export SNOWFLAKE_USER=myuser
    snow sql -c dev --accountname myaccount -q "select 1"
    

    Copy

    Você pode usar este método com as conexões padrão e nomeada.

Executar consultas SQL a partir de várias entradas¶

O Snowflake CLI permite executar consultas SQL usando entradas semelhantes às manipuladas pelo SnowSQL. Os exemplos a seguir executam consultas SQL usando várias entradas.

• Executar consultas usando parâmetros de linha de comando:

  • SnowSQL

    snowsql -q "select 1"
    

    Copy

  • Snowflake CLI

    snow sql -q "select 1"
    

    Copy

• Executar consultas a partir de um arquivo:

  • SnowSQL

    snowsql -f test.sql
    

    Copy

  • Snowflake CLI

    snow sql -f test.sql
    

    Copy

• Executar consultas a partir da entrada padrão:

  • SnowSQL

    cat test.sql | snowsql
    

    Copy

  • Snowflake CLI

    cat test.sql | snow sql --stdin
    

    Copy

Salvar resultados da consulta em um arquivo JSON¶

Atualmente, o Snowflake CLI não oferece suporte a todas as opções de formatação de saída do SnowSQL. O Snowflake CLI permite salvar os resultados da consulta como uma tabela formatada ou como JSON. Embora CSV e outros formatos ainda não estejam disponíveis, você pode usar ferramentas externas, como jq, para converter dados de outros formatos de JSON.

• SnowSQL

  snowsql \
    -f test.sql \
    -o "output_format=json" \
    -o "output_file=result.json"
  

  Copy

• Snowflake CLI

  snow sql -f test.sql --format json > result.json
  

  Copy

Executar consultas usando variáveis¶

Tanto o SnowSQL quanto o Snowflake CLI permitem usar variáveis ​​em consultas. O SnowSQL permite usar variáveis ​​de opções de linha de comando, a partir do arquivo de configuração, e usando algumas variáveis ​​internas. Embora o Snowflake CLI não aceite variáveis ​​no arquivo de configuração ou o uso de variáveis ​​internas, ele suporta a especificação de parâmetros com opções de linha de comando e a especificação de variáveis ​​em arquivos de definição de projeto. Para obter informações sobre como migrar as variáveis ​​do seu arquivo de configuração do SnowSQL, consulte Migrar suas variáveis.

Após migrar suas variáveis ​​da configuração do SnowSQL, você pode executar consultas do Snowflake CLI usando variáveis ​​tanto de opções de linha de comando quanto de definições de projeto.

Ao usar variáveis, observe as seguintes diferenças importantes entre o SnowSQL e o Snowflake CLI:

• Eles usam sintaxes diferentes para substituições de variáveis. O SnowSQL usa a sintaxe &variable ou &{variable}, enquanto o Snowflake CLI usa <% variable %>. A sintaxe do SnowSQL atualmente é aceita, mas ficou obsoleta.

• O Snowflake CLI habilita automaticamente a substituição de variáveis; portanto, você não precisa habilitá-la explicitamente como no SnowSQL.

• Os nomes de variáveis ​​em arquivos de definição de projeto do Snowflake CLI devem ser prefixados com ctx.env, conforme mostrado:

Os exemplos a seguir mostram as diferenças ao executar consultas SQL com variáveis:

• Execute uma consulta usando variáveis ​​em opções de linha de comando, em que x é o nome da variável:

  • SnowSQL

    snowsql \
      -o variable_substitution=true \
      -q "select &x" \
      -D x=1
    

    Copy

  • Snowflake CLI

    snow sql \
      -q "select <% x %>" \
      -D x=1
    

    Copy

  • Snowflake CLI (usando sintaxe obsoleta para facilitar migrações rápidas)

    snow sql \
      -q "select &x" \
      -D x=1
    

    Copy

• Execute uma consulta usando variáveis ​​em uma configuração do SnowSQL em comparação a um arquivo de definição de projeto Snowflake CLI:

  • SnowSQL

    # save variables to config
    echo "[variables]
    xyz=Hello World" > custom_config
    
    
    # execute query
    snowsql \
      --config custom_config \
      -o variable_substitution=true \
      -q "select '&{xyz}'"
    

    Copy

  • Snowflake CLI

    # save variables to project definition
    echo "definition_version: 2
    env:
      xyz: Hello World" > snowflake.yml
    
    # execute query
    snow sql -q "select '<% ctx.env.xyz %>'"
    

    Copy

  • Snowflake CLI (usando sintaxe obsoleta para facilitar migrações rápidas)

    # save variables to project definition
    echo "definition_version: 2
    env:
      xyz: Hello World" > snowflake.yml
    
    
    # execute query
    snow sql -q "select '&{ctx.env.xyz}'"
    

    Copy