Gerenciando conexões Snowflake

Antes de poder usar Snowflake CLI, é necessário definir conexões, que especificam como Snowflake CLI se conecta ao Snowflake. Snowflake CLI usa a seguinte hierarquia de precedência para determinar qual valor usar quando um parâmetro de conexão for definido em vários locais:

  • Parâmetros de linha de comando

  • Variáveis de ambiente que substituem parâmetros config.toml específicos, como SNOWFLAKE_CONNECTIONS_MYCONNECTION_PASSWORD

  • Conexões definidas no arquivo config.toml manualmente ou usando o comando snow connection add

  • Variáveis de ambiente genéricas, como SNOWFLAKE_USER.

Você também pode usar a opção --temporary-connection, que não requer definição em config.toml.

Cuidado

Para maior segurança, a Snowflake recomenda fortemente usar a variável de ambiente SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD ou SNOWFLAKE_PASSWORD.

Definição de conexões

As definições de conexão são armazenadas na seção de [conexões] do arquivo config.toml, semelhante ao seguinte:

[connections.myconnection]
account = "myaccount"
user = "jondoe"
password = "hunter2"
warehouse = "my-wh"
database = "my_db"
schema = "my_schema"
Copy

A definição de conexão oferece suporte às mesmas opções de configuração do Snowflake Connector para Python. Além disso, é possível especificar uma conexão padrão na variável default_connection_name no topo do arquivo. Você não pode incluí-lo em uma definição de conexão. Por exemplo:

default_connection_name = "myconnection"

[connections.myconnection]
account = "myaccount"
...
Copy

Nota

Para sistemas MacOS e Linux, Snowflake CLI exige o arquivo config.toml para limitar suas permissões de leitura e gravação somente para o proprietário do arquivo. Para definir as permissões de arquivo necessárias, execute os seguintes comandos:

chown $USER connections.toml
chmod 0600 connections.toml
Copy

Snowflake CLI também oferece suporte ao arquivo de configuração connections.toml. O arquivo deve ser colocado no mesmo diretório que o arquivo config.toml, e ele deve conter apenas conexões. As configurações em connections.toml exigem um nome de seção diferente, sem connections. Por exemplo, [connections.myconnection] seria apenas [myconnection].

Nota

Se ambas as configurações config.toml e connections.toml contiverem conexões, o Snowflake CLI usará apenas configurações de connections.toml.

Gerencie ou adicione suas conexões ao Snowflake com os comandos snow connection

Os comandos snow connection permitem criar, gerenciar e testar conexões Snowflake.

Adição de uma conexão

Para criar uma nova conexão e adicioná-la ao arquivo de configuração, faça o seguinte:

  1. Execute o comando snow conexão add:

snow connection add
Copy

  1. Quando solicitado, forneça os parâmetros necessários de conexão, conta e nome de usuário, bem como quaisquer outros parâmetros opcionais desejados.

Name for this connection: <connection-name>
Snowflake account name: <account-name>
Snowflake username: <user-name>
Snowflake password [optional]: <password-value>
Role for the connection [optional]: <role-name>
Warehouse for the connection [optional]: <warehouse-name>
Database for the connection [optional]: <database-name>
Schema for the connection [optional]: <schema-name>
Connection host [optional]: <host-name>
Connection port [optional]: <port-value>
Snowflake region [optional]: <region-name>
Authentication method [optional]: <authentication-method>
Path to private key file [optional]: <path-to-private-key>
Path to token file [optional]: <path-to-mfa-token>
Wrote new connection myconnection2 to config.toml

Você também pode adicionar valores para parâmetros específicos na linha de comando, conforme mostrado:

snow --config-file config.toml connection add -n myconnection2 --account myaccount2 --user jdoe2
Copy

Nota

Se o comando terminar com um erro – por exemplo, se a opção --private_key_file fizer referência a um arquivo inexistente –, a conexão não será salva no arquivo de configuração config.toml.

Como listar conexões definidas

Para listar as conexões disponíveis, digite o comando snow connection list, conforme mostrado:

snow connection list
Copy
+-------------------------------------------------------------------------------------------------+
| connection_name | parameters                                                       | is_default |
|-----------------+------------------------------------------------------------------+------------|
| myconnection    | {'account': 'myaccount', 'user': 'jondoe', 'password': '****',   | False      |
|                 | 'database': 'my_db', 'schema': 'my_schema', 'warehouse':         |            |
|                 | 'my-wh'}                                                         |            |
| myconnection2   | {'account': 'myaccount2', 'user': 'jdoe2'}                       | False      |
+-------------------------------------------------------------------------------------------------+

Como testar uma conexão

Para testar se uma conexão pode se conectar com sucesso ao Snowflake, insira o comando snow connection test, semelhante ao seguinte:

snow connection test -c myconnection2
Copy
+--------------------------------------------------+
| key             | value                          |
|-----------------+--------------------------------|
| Connection name | myconnection2                  |
| Status          | OK                             |
| Host            | example.snowflakecomputing.com |
| Account         | myaccount2                     |
| User            | jdoe2                          |
| Role            | ACCOUNTADMIN                   |
| Database        | not set                        |
| Warehouse       | not set                        |
+--------------------------------------------------+

Definição da conexão padrão

É possível usar o comando snow connection set-default para especificar qual Snowflake CLI de configuração deve ser usada como padrão, substituindo o arquivo de configuração default_connection_name e as variáveis SNOWFLAKE_DEFAULT_CONNECTION_NAME, se definidos.

O exemplo a seguir define a conexão padrão para myconnection2:

snow connection set-default myconnection2
Copy
Default connection set to: myconnection2

Nota

Se os arquivos connections.toml e config.toml estiverem presentes, Snowflake CLI usa apenas conexões definidas em connections.toml.

Use variáveis de ambiente para credenciais Snowflake

É possível especificar credenciais Snowflake em variáveis de ambiente do sistema em vez de em arquivos de configuração. É possível usar as seguintes variáveis de ambiente genéricas apenas para especificar parâmetros de conexão:

  • SNOWFLAKE_ACCOUNT

  • SNOWFLAKE_USER

  • SNOWFLAKE_PASSWORD

  • SNOWFLAKE_DATABASE

  • SNOWFLAKE_SCHEMA

  • SNOWFLAKE_ROLE

  • SNOWFLAKE_WAREHOUSE

  • SNOWFLAKE_AUTHENTICATOR

  • SNOWFLAKE_PRIVATE_KEY_PATH

  • SNOWFLAKE_SESSION_TOKEN

  • SNOWFLAKE_MASTER_TOKEN

Passe os parâmetros de conexão para o comando snow

É possível passar os parâmetros de conexão diretamente em cada comando snow que requer uma conexão. Para obter uma lista completa dos parâmetros de configuração de conexão, execute o comando snow sql --help, conforme mostrado. Observe que a saída mostra apenas a seção com as opções de configuração de conexão.

snow sql --help
Copy
╭─ Connection configuration ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --connection,--environment             -c      TEXT     Name of the connection, as defined in your config.toml. Default: default.            │
│ --host                                         TEXT     Host address for the connection. Overrides the value specified for the connection.   │
│ --port                                         INTEGER  Port for the connection. Overrides the value specified for the connection.           │
│ --account,--accountname                        TEXT     Name assigned to your Snowflake account. Overrides the value specified for the       │
│                                                         connection.                                                                          │
│ --user,--username                              TEXT     Username to connect to Snowflake. Overrides the value specified for the connection.  │
│ --password                                     TEXT     Snowflake password. Overrides the value specified for the connection.                │
│ --authenticator                                TEXT     Snowflake authenticator. Overrides the value specified for the connection.           │
│ --private-key-file,--private-key-path          TEXT     Snowflake private key file path. Overrides the value specified for the connection.   │
│ --token-file-path                              TEXT     Path to file with an OAuth token that should be used when connecting to Snowflake    │
│ --database,--dbname                            TEXT     Database to use. Overrides the value specified for the connection.                   │
│ --schema,--schemaname                          TEXT     Database schema to use. Overrides the value specified for the connection.            │
│ --role,--rolename                              TEXT     Role to use. Overrides the value specified for the connection.                       │
│ --warehouse                                    TEXT     Warehouse to use. Overrides the value specified for the connection.                  │
│ --temporary-connection                 -x               Uses connection defined with command line parameters, instead of one defined in      │
│                                                         config                                                                               │
│ --mfa-passcode                                 TEXT     Token to use for multi-factor authentication (MFA)                                   │
│ --enable-diag                                           Run python connector diagnostic test                                                 │
│ --diag-log-path                                TEXT     Diagnostic report path                                                               │
│ --diag-allowlist-path                          TEXT     Diagnostic report path to optional allowlist                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Cuidado

Para maior segurança, a Snowflake recomenda fortemente usar a variável de ambiente SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD ou SNOWFLAKE_PASSWORD.

Use uma conexão temporária

Você também pode especificar parâmetros de conexão na linha de comando usando a opção --temporary-connection [-x]. Ele ignora todas as definições do config.toml, usando aqueles especificados pelas opções de linha de comando. Esta abordagem pode ser útil para casos de uso de CI/CD quando você não deseja usar um arquivo de configuração. Quando você usa uma conexão temporária, o Snowflake CLI ignora quaisquer variáveis de conexão definidas no arquivo config.toml, mas ainda usa quaisquer variáveis de ambiente, como SNOWFLAKE_ACCOUNT, definidas por você.

snow sql -q "select 42;" --temporary-connection \
                           --account myaccount \
                           --user jdoe
Copy
select 42;
+----+
| 42 |
|----|
| 42 |
+----+

Cuidado

Para maior segurança, a Snowflake recomenda fortemente usar a variável de ambiente SNOWFLAKE_CONNECTIONS_<NAME>_PASSWORD ou SNOWFLAKE_PASSWORD.

Formas adicionais de autenticar sua conexão

Você também pode usar os seguintes métodos para autenticar sua conexão com o Snowflake:

Use um arquivo de chave privada para autenticação

Para usar o arquivo de chave privada para autenticação, sua configuração de conexão requer que você defina o parâmetro do authenticator para SNOWFLAKE_JWT e forneça o caminho para o arquivo com sua chave privada, semelhante ao seguinte:

  • Especifique a opção --private_key-file no comando snow connection add, conforme mostrado:

    snow connection add \
   --connection jwt \
   --authenticator SNOWFLAKE_JWT \
   --private-key-file ~/.ssh/sf_private_key.p8
    Copy

  • Use o arquivo de configuração:

    [connections.jwt]
account = "my_account"
user = "jdoe"
authenticator = "SNOWFLAKE_JWT"
private_key_file = "~/sf_private_key.p8"
    Copy

Para obter mais detalhes sobre como configurar a autenticação do par de chaves, consulte Autenticação de pares de chaves e rotação de pares de chaves.

Nota

Se sua chave privada for protegida por senha, defina a variável de ambiente PRIVATE_KEY_PASSPHRASE para essa senha.

Como usar autenticação OAuth

Para usar o connect através de OATH, é possível fazer o seguinte:

  • Especifique a opção --token-file-path no comando snow connection add, conforme mostrado:

    snow connection add --token-file-path "my-token.txt"
    Copy

  • No arquivo config.toml, defina authenticator = "oauth" e adicione o parâmetro token_file_path à definição de conexão, conforme mostrado:

    [connections.oauth]
account = "my_account"
user = "jdoe"
authenticator = "oauth"
token_file_path = "my-token.txt"
    Copy

Como usar autenticação multifator (MFA)

Para usar MFA:

  1. Configure a autenticação multifator no Snowflake e defina o parâmetro authenticator como snowflake (que é um valor padrão).

  2. Se você quiser usar uma senha numérica gerado pelo Duo em vez do mecanismo de push, use a opção de --mfa-passcode <senha numérica> ou defina passcode_in_password = true em config.toml e inclua a senha numérica em sua senha, conforme descrito em Como usar MFA em Python.

Para habilitar o cache MFA:

  1. Para sua conta, defina ALLOW_CLIENT_MFA_CACHING = true.

  2. Em seu arquivo config.toml, adicione authenticator = username_password_mfa à sua conexão.

Como usar SSO (logon único)

Se você tiver configurado o Snowflake para usar o login único (SSO), pode configurar seu aplicativo cliente para usar o SSO para autenticação. Consulte Como usar SSO com aplicativos cliente que se conectam ao Snowflake para obter detalhes e configure sua conexão usando as instruções para Python.

Linguagem: Português