Gerenciando conexões Snowflake¶

Arquivo de configuração alternativo¶

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].

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

2. 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.

   Enter connection name: <connection_name>
   Enter account: <account>
   Enter user: <user-name>
   Enter password: <password>
   Enter role: <role-name>
   Enter warehouse: <warehouse-name>
   Enter database: <database-name>
   Enter schema: <schema-name>
   Enter host: <host-name>
   Enter port: <port-number>
   Enter region: <region-name>
   Enter authenticator: <authentication-method>
   Enter private key file: <path-to-private-key-file>
   Enter token file path: <path-to-mfa-token>
   Do you want to configure key pair authentication? [y/N]: y
   Key length [2048]: <key-length>
   Output path [~/.ssh]: <path-to-output-file>
   Private key passphrase: <key-description>
   Wrote new connection <connection-name> 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

Por padrão, o comando snow connection add solicita parâmetros opcionais se eles não forem especificados na linha de comando. Se quiser adicionar conexões sem especificar algum parâmetro opcional como account e ignorar os prompts interativos, você pode usar a opção --no-interactive, conforme mostrado:

snow connection add -n myconnection2 --user jdoe2 --no-interactive

Depois de adicionar uma conexão, você pode testar a conexão para garantir que ela funcione corretamente.

Como listar conexões definidas¶

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

snow connection list

+-------------------------------------------------------------------------------------------------+
| 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      |
+-------------------------------------------------------------------------------------------------+

Testar e diagnosticar 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

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

Se você encontrar problemas de conectividade, poderá executar o diagnóstico diretamente no Snowflake CLI. O suporte Snowflake também pode solicitar essas informações para ajudar você com problemas de conectividade.

A coleta de diagnósticos usa as seguintes opções de comando snow connection test:

• --enable-diag para gerar um relatório de diagnóstico.

• --diag-log-path para especificar o caminho absoluto do relatório gerado.

• --diag-allowlist-path para especificar o caminho absoluto de um arquivo JSON que contém a saída dos comandos SQL SYSTEM$ALLOWLIST() ou SYSTEM$ALLOWLIST_PRIVATELINK(). Essa opção é necessária somente se o usuário definido na conexão não tiver permissão para executar as funções da lista de permissões do sistema ou se a conexão com o URL da conta falhar.

O exemplo a seguir gera um relatório de diagnóstico para a conexão myconnection2 e armazena no arquivo ~/report/SnowflakeConnectionTestReport.txt:

snow connection test -c myconnection2 --enable-diag --diag-log-path $(HOME)/report

+----------------------------------------------------------------------------+
| key                  | value                                               |
|----------------------+-----------------------------------------------------|
| Connection name      | myconnection2                                       |
| Status               | OK                                                  |
| Host                 | example.snowflakecomputing.com                      |
| Account              | myaccount2                                          |
| User                 | jdoe2                                               |
| Role                 | ACCOUNTADMIN                                        |
| Database             | not set                                             |
| Warehouse            | not set                                             |
| Diag Report Location | /Users/<username>/SnowflakeConnectionTestReport.txt |
+----------------------------------------------------------------------------+

É possível revisar o relatório para verificar se há problemas de conectividade e discuti-los com sua equipe de rede. Você também pode fornecer o relatório ao suporte Snowflake para obter assistência adicional.

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

Default connection set to: myconnection2

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_PRIVATE_KEY_RAW

• SNOWFLAKE_SESSION_TOKEN

• SNOWFLAKE_MASTER_TOKEN

• SNOWFLAKE_TOKEN_FILE_PATH

• SNOWFLAKE_OAUTH_CLIENT_ID

• SNOWFLAKE_OAUTH_CLIENT_SECRET

• SNOWFLAKE_OAUTH_AUTHORIZATION_URL

• SNOWFLAKE_OAUTH_TOKEN_REQUEST_URL

• SNOWFLAKE_OAUTH_REDIRECT_URI

• SNOWFLAKE_OAUTH_SCOPE

• SNOWFLAKE_OAUTH_DISABLE_PKCE

• SNOWFLAKE_OAUTH_ENABLE_REFRESH_TOKENS

• SNOWFLAKE_OAUTH_ENABLE_SINGLE_USE_REFRESH_TOKENS

• SNOWFLAKE_CLIENT_STORE_TEMPORARY_CREDENTIAL

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

╭─ 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).
│ --oauth-client-id                              TEXT     Value of the client ID provided by the identity provider for Snowflake integration.
│ --oauth-client-secret                          TEXT     Value of the client secret provided by the identity provider for Snowflake integration.
│ --oauth-authorization-url                      TEXT     Identity provider endpoint supplying the authorization code to the driver.
│ --oauth-token-request-url                      TEXT     Identity provider endpoint supplying the access tokens to the driver.
│ --oauth-redirect-uri                           TEXT     URI to use for the authorization code.
│ --oauth-scope                                  TEXT     Scope requested in the identity provider authorization request.
│ --oauth-disable-pkce                                    Disables Proof Key for Code Exchange (PKCE). Default: False.
│ --oauth-enable-refresh-tokens                           Enables a silent re-authentication when the actual access token becomes outdated. Default: False.
│ --oauth-enable-single-use-refresh-tokens                Whether to opt in to single-use refresh token semantics. Default: False.
│ --client-store-temporary-credential                     Store the temporary credential.
│ --enable-diag                                           Run the python connector diagnostic test.
│ --diag-log-path                                TEXT     Diagnostic report path.
│ --diag-allowlist-path                          TEXT     Diagnostic report path to optional allowlist.
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

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-name 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.

Snowflake CLI procura a chave privada nos parâmetros de conexão na seguinte ordem:

1. Se private_key_file for especificado, Snowflake CLI lê a chave do caminho do arquivo especificado.

2. Se private_key_path for especificado, Snowflake CLI lê a chave do caminho do arquivo especificado.

3. Se private_key_file ou private_key_path não forem especificados, Snowflake CLI lê a chave diretamente do parâmetro private_key_raw.

Como usar autenticação OAuth¶

Para usar o connect através de OAuth, é 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

Usar o fluxo do código de autorização OAuth 2.0¶

O fluxo do código de autorização OAuth 2.0 é um método seguro para que um aplicativo cliente obtenha um token de acesso de um servidor de autorização em nome de um usuário, sem revelar as credenciais do usuário. Para obter mais informações sobre esse fluxo e seus parâmetros, consulte Habilitar o fluxo do Código de autorização OAuth 2.0 na documentação do Snowflake Connector para Python.

Para usar o fluxo do código de autorização OAuth 2.0, adicione uma definição de conexão ao seu arquivo config.toml semelhante à seguinte:

[connections.oauth]
authenticator = "OAUTH_AUTHORIZATION_CODE"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_redirect_uri = "http://localhost:8001/snowflake/oauth-redirect"
oauth_scope = "session:role:PUBLIC"

Usar o fluxo de credenciais de cliente OAuth 2.0¶

O fluxo de credenciais de cliente do OAuth 2.0 oferece uma maneira segura de autenticação máquina para máquina (M2M), como o Snowflake Connector para Python que se conecta a um serviço de back-end. Ao contrário do fluxo do código de autorização OAuth 2.0, esse método não depende de nenhum dado específico do usuário. Para obter mais informações sobre esse fluxo e seus parâmetros, consulte Ativar o fluxo de credenciais de cliente OAuth 2.0 na documentação do Snowflake Connector para Python.

Para usar o fluxo de credenciais de cliente OAuth 2.0, adicione uma definição de conexão ao seu arquivo config.toml semelhante à seguinte:

[connections.oauth]
authenticator = "OAUTH_CLIENT_CREDENTIALS"
user = "user"
account = "account"
oauth_client_id = "client_id"
oauth_client_secret = "client_secret"
oauth_token_request_url = "http://identity.provider.com/token"
oauth_scope = "session:role:PUBLIC"

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 quiser usar um código de acesso gerado pelo Duo em vez do mecanismo push, use a opção --mfa-passcode <passcode> ou defina passcode_in_password = true no arquivo config.toml e inclua o código de acesso em sua senha, conforme descrito em Uso da MFA com Python.

   Nota

   Se quiser usar o código de acesso na senha para autenticação, depois de executar o primeiro comando snow, você não poderá mais fornecer o código de acesso, desde que o token seja válido. Você deve fazer o seguinte:

   • Remova o código de acesso da senha.

   • Remova ou comente o passcode_in_password = true no arquivo config.toml.

Usar o cache de MFA¶

O cache de MFA é um recurso de segurança que reduz a frequência dos avisos de autenticação multifator (MFA) durante os logins. Os avisos frequentes de MFA podem interromper o fluxo de trabalho e diminuir a produtividade. O cache de MFA resolve esse problema armazenando com segurança as informações da sessão de MFA por um período específico. O uso do cache de MFA permite que você se autentique sem digitar repetidamente os códigos de MFA, desde que estejam dentro do período de tempo da sessão em cache.

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.

Para obter mais informações, consulte Uso do armazenamento em cache de tokens MFA para minimizar o número de tentativas durante a autenticação — opcional.

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 Uso de SSO com aplicativos clientes que se conectam ao Snowflake para obter detalhes e configure sua conexão usando as instruções para Python.

Usar um navegador externo¶

Você pode usar o navegador para autenticar sua conexão Snowflake CLI com qualquer provedor de identidade compatível com SAML 2.0 (IdP), como Okta ou Active Directory Federation Services.

Para usar a autenticação externa do navegador, use um dos seguintes métodos:

• Use a opção de comando snow connection add --authenticator:

  snow connection add --authenticator externalbrowser
  

  Copy

• Defina authenticator para externalbrowser em seu arquivo config.toml:

  [connections.externalbrowser]
  account = "my_account"
  user = "jdoe"
  authenticator = "externalbrowser"
  

  Copy

Usar o PAT (Programmatic Access Token)¶

O Programmatic Access Token (PAT), ou token de acesso programático, é um método de autenticação específico do Snowflake. O recurso deve ser ativado para a conta antes de ser usado (consulte Pré-requisitos para obter mais informações). A autenticação com PAT não envolve nenhuma interação humana.

Para usar o PAT com a conexão, defina authenticator para PROGRAMMATIC_ACCESS_TOKEN e token_file_path para apontar o arquivo com o token, conforme mostrado:

[connections.externalbrowser]
account = "my_account"
user = "jdoe"
authenticator = "PROGRAMMATIC_ACCESS_TOKEN"
token_file_path = "path-to-pat-token"

Para obter mais informações sobre PATs, consulte Uso de tokens de acesso programático para autenticação.